MCP tools reference
These are the tools a coding agent sees when it is connected to Niro. The list below is copied from what the engine itself serves, so it matches what your agent gets. Each tool's description is quoted exactly as the engine gives it to agents, so its wording is the engine's own.
A few things that hold for every tool:
- Answers are text. They are written for an agent to read, not as JSON fields.
- Every answer starts with a line saying where it came from: "Answered from the local graph on this machine (niro-local)."
- The tools answer for one folder: the one your agent's session started in. To ask about another folder, run
niro askfrom that folder. purposechanges the shape of an answer. Many tools take it. The values are LOCATE, ORIENT, COMPREHEND, TRACE, DEBUG, PROPAGATE, ASSESS_RISK, VERIFY, IMPLEMENT, AUDIT and SCOUT:- VERIFY gives names only;
- ASSESS_RISK gives counts;
- COMPREHEND and DEBUG add the source code of the method asked about.
- Two tools are off in this release:
find_reusable_codeandfind_known_issues. They need LLM documentation, which this release does not include, so they are not in the list. - The engine offers no MCP resources or prompts, only these tools.
- While a full build rewrites the graph, only
get_index_status,code_grepandget_source_codeanswer. The others say a build is running.
You can try any tool from the terminal: niro ask <tool> key=value. With no tool named, niro ask lists them.
For the limits on answer sizes and page sizes, see Limits.
The tools
resolve_nameget_call_chainget_reverse_call_chainget_blast_radiusget_impact_analysisget_class_structurelist_typesfind_api_endpointsget_exception_flowlist_eventsget_event_producers_and_handlersfind_orphaned_eventsfind_outbound_http_callsget_service_topologyfind_handlerlist_data_resourcesget_data_resource_usageget_index_statuscode_grepget_source_codemark_task_complete
resolve_name
List what a name matches in the graph, at most 25. Not a step before other tools: they take a short name themselves and say when it matched several things. Use this to choose among matches.
| Input | Type | Required | What it is |
|---|---|---|---|
entity_fqn |
string | yes |
get_call_chain
Returns the call chain (callers, callees, or both) for a method. Accepts method_fqn (partial auto-resolves) or http_path. direction is both (default), callers or callees; scope='direct' (default) is one level, scope='transitive' with transitive_depth 2 or 3 goes further.
| Input | Type | Required | What it is |
|---|---|---|---|
method_fqn |
string | no | |
http_path |
string | no | |
direction |
string | no | |
scope |
string | no | |
transitive_depth |
integer | no | |
max_depth |
integer | no | |
depth |
integer | no | |
include_all |
boolean | no | |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: TRACE. |
include_source_code |
boolean | no | When true, the answer carries the numbered source of the method asked about, whole up to 150 lines (a longer one is marked as cut); listed methods carry their file and line only. On by default for purpose COMPREHEND or DEBUG; false turns it off. |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
get_reverse_call_chain
Returns all callers (upstream) for a method or class. Accepts method_fqn, class_fqn, or http_path. For class-level impact use class_fqn — finds callers of all callable methods in one call. Up to 300 callers per answer; limit and offset page them.
| Input | Type | Required | What it is |
|---|---|---|---|
method_fqn |
string | no | |
http_path |
string | no | |
scope |
string | no | |
transitive_depth |
integer | no | |
max_depth |
integer | no | |
depth |
integer | no | |
include_all |
boolean | no | |
limit |
integer | no | |
offset |
integer | no | |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: PROPAGATE. |
include_source_code |
boolean | no | When true, the answer carries the numbered source of the method asked about, whole up to 150 lines (a longer one is marked as cut); listed methods carry their file and line only. On by default for purpose COMPREHEND or DEBUG; false turns it off. |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
get_blast_radius
Returns the full blast radius for a code change: both upstream callers that break AND downstream callees that receive different input. Seeds can be a method, class, HTTP endpoint, or event. Default direction='both', depth 3. For coupling through a shared data resource use get_data_resource_usage. Single call, no chaining needed.
| Input | Type | Required | What it is |
|---|---|---|---|
method_fqn |
string | no | |
method_fqns |
list of string | no | Several methods analysed as ONE change, in one call. |
class_fqn |
string | no | |
http_path |
string | no | |
event_fqn |
string | no | Event name, event_source or topic; seeds every method that triggers, handles or registers for it. |
depth |
integer | no | Levels to walk, 1 to 5. Default 3. |
direction |
string | no | both (default), upstream (callers), downstream (callees). |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: ASSESS_RISK. |
include_source_code |
boolean | no | When true, the answer carries the source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut) of the method asked about and of up to 20 of the methods that depend on it or that it depends on. Purpose COMPREHEND or DEBUG alone adds only the method's own source. |
data_resource_fqn |
string | no | |
include_data_coupling |
boolean | no | |
include_http_candidates |
boolean | no | Also include CALLS_HTTP_CANDIDATE callers/callees — HTTP calls whose target base URL could not be resolved, so the method is one of several plausible targets rather than a confirmed one. Always shown in a separate section labeled inferred, never mixed into the confirmed cross-service list. Default true. |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
get_impact_analysis
Analyzes what breaks if you change a method, class, HTTP endpoint, or event. Returns upstream callers across service boundaries (HTTP/events). Default direction='upstream'. For a data resource (firestore collection, SQL table, S3 bucket) use get_data_resource_usage. Single call — no chaining needed.
| Input | Type | Required | What it is |
|---|---|---|---|
method_fqn |
string | no | |
method_fqns |
list of string | no | Several methods analysed as ONE change, in one call. |
class_fqn |
string | no | |
http_path |
string | no | |
event_fqn |
string | no | Event name, event_source or topic; seeds every method that triggers, handles or registers for it. |
depth |
integer | no | Levels to walk, 1 to 5. Default 3. |
direction |
string | no | upstream (default, callers), downstream (callees), both. |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: ASSESS_RISK. |
include_source_code |
boolean | no | When true, the answer carries the source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut) of the method asked about and of up to 20 of the methods that depend on it or that it depends on. Purpose COMPREHEND or DEBUG alone adds only the method's own source. |
data_resource_fqn |
string | no | |
include_data_coupling |
boolean | no | |
include_http_candidates |
boolean | no | Also include CALLS_HTTP_CANDIDATE callers/callees — HTTP calls whose target base URL could not be resolved, so the method is one of several plausible targets rather than a confirmed one. Always shown in a separate section labeled inferred, never mixed into the confirmed cross-service list. Default true. |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
get_class_structure
One type's methods, constructors, fields, constants, and what it extends or implements.
| Input | Type | Required | What it is |
|---|---|---|---|
class_fqn |
string | yes | |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: COMPREHEND. |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (members by kind), locations (file:line and exact id per member), names (one member per line). Leave it out for the full answer. |
list_types
Every class, interface and enum in this project, by name, with the file each lives in. Use it to see what the codebase contains before asking about anything in particular.
| Input | Type | Required | What it is |
|---|---|---|---|
kind |
string | no | |
limit |
integer | no | |
offset |
integer | no |
find_api_endpoints
Returns the HTTP endpoints (REST APIs) this project declares and exposes. Use '/' as path_pattern for all of them, or a substring of a path to narrow it. Remote methods and sockets that are not plain HTTP (gRPC, WebSocket, XML-RPC, Go net/rpc, SignalR) are listed too, each marked with its protocol.
| Input | Type | Required | What it is |
|---|---|---|---|
path_pattern |
string | no | |
service_filter |
string | no | Optional: filter by service name (e.g., 'billing-svc'). Keeps a route only when the path of the file of the method that HANDLES it, or that method's repository id, contains this text, ignoring case: it names the service that serves the route. |
limit |
integer | no | |
offset |
integer | no | |
protocol |
string | no | Optional: keep only one protocol: 'http' (plain HTTP), or 'grpc', 'websocket', 'xmlrpc', 'netrpc', 'signalr'. Leave it out for every protocol; a line that is not plain HTTP ends with its protocol in brackets, and a remote method call shows the method in place of the path (RPC shipping.quote). |
get_exception_flow
Which exceptions can escape a method, and where they are thrown and caught. Reach for it before writing a caller's error handling, or to find who would have to handle a new checked exception.
| Input | Type | Required | What it is |
|---|---|---|---|
method_fqn |
string | yes | |
depth |
integer | no | |
direction |
string | no | 'downstream' (default): what escapes this method. 'upstream': which callers must handle or declare exception_type. |
exception_type |
string | no | For direction=upstream: the exception type (simple or qualified name) to trace up the callers. |
from_line |
integer | no | |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: COMPREHEND. |
include_source_code |
boolean | no | When true, the answer ends with the method's own source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut). On by default for purpose COMPREHEND or DEBUG; false turns it off. |
list_events
Every event this project publishes or subscribes to, with how many places do each. Use it to see what moves through the system without a direct call.
| Input | Type | Required | What it is |
|---|---|---|---|
event_source_pattern |
string | no | |
event_type |
string | no | |
limit |
integer | no | |
offset |
integer | no |
get_event_producers_and_handlers
For one event, named by its topic or its full name, who publishes it and who handles it. Use it before changing either side.
| Input | Type | Required | What it is |
|---|---|---|---|
name |
string | no | |
type |
string | no | |
from_line |
integer | no |
find_orphaned_events
Events with only one side: published and nothing listens, or listened for and nothing publishes. Each is either a real gap or a name that does not match.
| Input | Type | Required | What it is |
|---|---|---|---|
limit |
integer | no | |
offset |
integer | no |
find_outbound_http_calls
Returns the outbound HTTP calls this project makes to other services, and where they land when the address could be worked out. Use it to see what a folder depends on over the network before changing either end. Calls that are not plain HTTP (gRPC, WebSocket, XML-RPC, Go net/rpc, SignalR) are listed too, each marked with its protocol.
| Input | Type | Required | What it is |
|---|---|---|---|
path_pattern |
string | no | |
service_filter |
string | no | Optional: filter by calling service name (e.g., 'orders-svc'). Keeps a call only when the path of the file that MAKES it contains this text (case-sensitive), so it names the calling service, never the service called. To find calls into a service, leave it out and look at where each call lands. |
limit |
integer | no | |
offset |
integer | no | |
protocol |
string | no | Optional: keep only one protocol: 'http' (plain HTTP), or 'grpc', 'websocket', 'xmlrpc', 'netrpc', 'signalr'. Leave it out for every protocol; a line that is not plain HTTP ends with its protocol in brackets, and a remote method call shows the method in place of the path (RPC shipping.quote). |
get_service_topology
Shows which folder of this project calls which, over HTTP, with the routes involved. Use it to get the shape of the system before looking at any one part of it.
| Input | Type | Required | What it is |
|---|---|---|---|
from_line |
integer | no |
find_handler
Given a method, shows what answers the HTTP calls it makes. Use it when a call leaves the code you are reading and you need the code at the other end.
| Input | Type | Required | What it is |
|---|---|---|---|
fqn |
string | no | |
from_line |
integer | no | |
relationship_type |
string | no | Filter by edge type (e.g., CALLS_HTTP, CALLS_HTTP_CANDIDATE, TRIGGERS_EVENT, CALLS). Omit to return all handler relationships. |
include_http_candidates |
boolean | no | Also return CALLS_HTTP_CANDIDATE handlers: HTTP calls whose target base URL could not be resolved. Always labeled inferred and listed separately. Default true. |
purpose |
string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: LOCATE. |
fqns |
list of string | no | Array of method FQNs for batch handler lookup. |
list_data_resources
Every database, cache or queue this project touches, with how many places touch each. Use it to see what the code stores before asking about any one of them. A cache key the code builds at run time is listed under its fixed start, marked (rest at run time). A stored procedure the code calls is listed with the kind procedure.
| Input | Type | Required | What it is |
|---|---|---|---|
limit |
integer | no | |
offset |
integer | no |
get_data_resource_usage
What reads, writes or deletes one store. Give the plain name, such as 'orders', or the full 'mongodb:collection:orders'. Use it before changing a table or collection, to see who depends on it. A cache key built at run time is named by its fixed start, such as 'stock:'. A method whose SQL is in its annotation (@Query, @SqlQuery) is listed itself.
| Input | Type | Required | What it is |
|---|---|---|---|
resource_fqn |
string | yes | |
from_line |
integer | no |
get_index_status
What is indexed for this folder, by kind. Use it when an answer looks empty or out of date, or to learn whether a folder that is not indexed can be.
It takes no inputs.
code_grep
Regex/literal search inside source file contents (lines, not file names). Supports match_mode (exact|regex), case_sensitive, single or batch patterns. Returns matching file paths and line numbers. For multiple terms use 'patterns' array or regex alternation (foo|bar). Each match also names the method_fqn and class_fqn that enclose it when the graph knows the line: pass method_fqn straight to get_blast_radius before changing that code, no second lookup needed. For class declarations by name use get_class_structure, not this tool. Searches the files the build reads plus config, build and text files (.yml, .json, .properties, .xml, .sql, .md, Dockerfile, .tf and the like), with secrets in those masked, source first. A PARTIAL answer gives continue_from to search the rest. 50 files per page by default: use limit and offset for more.
| Input | Type | Required | What it is |
|---|---|---|---|
pattern |
string | no | |
patterns |
list of string | no | |
path_pattern |
string | no | |
max_matches_per_file |
integer | no | |
match_mode |
string | no | |
case_sensitive |
boolean | no | |
limit |
integer | no | |
offset |
integer | no | |
continue_from |
integer | no | |
answer |
string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and enclosing method fqn per hit), names (the methods holding a hit), match (only the text the pattern matched). Leave it out for the full answer. |
get_source_code
Read source code for one or more files. Single mode: pass source_id with optional line range, or fqn for a method or class. Batch mode: pass 'sources' array to fetch multiple snippets in one call, much more efficient than separate calls when tracing execution paths. Accepts full paths or partial file names. Only files inside this worktree that the build reads, plus the config, build and text files code_grep searches, with secrets masked.
| Input | Type | Required | What it is |
|---|---|---|---|
source_id |
string | no | |
fqn |
string | no | |
target |
string | no | |
start_line |
integer | no | |
end_line |
integer | no | |
sources |
list of object or string | no | |
entity_fqns |
list of string | no |
mark_task_complete
BEFORE YOU CALL THIS after changing code: for every method the task changed, and every MyBatis mapper statement it changed (a statement in mapper XML is its mapper interface method of the same id), call get_blast_radius on that method and check each caller it lists against the change: does the caller still get what it expects, and does it read a value the change now blanks, drops or reshapes? Do this even when the change looks local. Signal the end of a task and get back a one-line receipt saying what niro-local answered and what that replaced. Call it once at the end of every turn in which you either asked niro-local anything, or read, searched or edited this project's source with your own tools. A turn where you never asked it matters just as much to report: set searched_code_natively to true in that case. SHOW THE RECEIPT: when the answer is a line starting with '[NIRO-CLI]', reproduce it as the very last line of your reply, on its own line, wrapped in single backticks so it reads as a message from the tool rather than as your own prose. The backticks are the only thing you may add: the text between them must be character for character what came back. Do not reword it, expand it, or add your own commentary about how useful it was. If nothing comes back, print nothing. A reply without the line is unfinished: it is how the person sees what these tools did. Never write the line yourself: its numbers are measured by this server, so yours would be false. niro_helpfulness says whether niro-local's answers helped: helpful, partial, not_helpful, or not_used when you never asked it. task_outcome says whether the work itself finished: succeeded, partial or failed. A turn where it let you down is the most useful one to report. niro_did and without_niro_extra_tool_calls are required: the first is what the person reads, the second is the 'instead of ~N searches' part of the line, and 0 is a valid answer.
| Input | Type | Required | What it is |
|---|---|---|---|
niro_did |
string | yes | DISPLAY ONLY: this is the line the DEVELOPER sees at the end of the task. Write it in niro-local's voice, not yours. One clause, MAXIMUM 70 CHARACTERS, starting with a past-tense verb, saying what niro-local found for the user this turn and what finding it with grep and file reads would have taken. Name concrete things the tools actually returned: counts of callers, files, services, endpoints, events. Add the contrast only when it is factual, e.g. 'that a grep would have missed', 'across 8 files', 'in 3 services'. FORBIDDEN: adjectives of value (powerful, invaluable, huge, quickly); any claim about time or money saved; any claim about how good niro-local is; tool names; source code; file paths; praise. State the finding and let the reader draw the conclusion. GOOD: 'Mapped 29 callers across 8 files that a grep would have missed' | 'Found 2 cross-service HTTP callers behind an unresolved base URL' | 'Traced the write path to 3 services sharing one collection' | 'Confirmed the 29-caller list was complete' BAD: 'niro-local brilliantly uncovered hidden dependencies' (praise) | 'Saved you 20 minutes' (time claim) | 'get_blast_radius returned 29 callers' (tool name) | 'Would have missed the callers' (passive, and it is the assistant's voice). IF NIRO-LOCAL DID NOT HELP THIS TURN, SAY SO: 'Returned nothing useful here'. Do not invent a win. Those turns are the ones most worth seeing, and the line is dropped rather than shown when you answer this way. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
without_niro_extra_tool_calls |
integer | yes | Estimated ADDITIONAL native tool calls (Read, Grep, Bash, WebFetch, subagent delegations, etc.) you would have needed to reach the same answer if niro-local's tools did not exist this turn. HOW TO DERIVE IT: go through each niro-local tool call you actually made this turn and ask 'what native call(s) would I have substituted for this one, and how many?', e.g. one get_blast_radius call might substitute for roughly 6 grep/read calls across the caller graph; one get_call_chain might substitute for 3-4 dead-end file reads. Sum those substitutions across all the niro-local calls you made this turn. 0 is a valid and expected answer when you made no niro-local tool calls this turn, or niro-local made no material difference. This is a separate hypothetical total for the without-niro-local scenario: do not confuse it with total_tool_calls. |
searched_code_natively |
boolean | no | |
niro_helpfulness |
one of helpful, partial, not_helpful, not_used |
no | |
helpfulness_reason |
string | no | Why niro-local's answers helped or did not. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
task_outcome |
one of succeeded, partial, failed |
no | |
total_tool_calls |
integer | no | |
subagent_tool_calls |
integer | no | |
without_niro_gap |
string | no | What finding the same thing without niro-local would have taken. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
without_niro_call_types |
list of one of grep_search, file_read, bash_exec, web_search, subagent_delegation, other |
no | |
summary |
string | no | What the task was and what was done, in plain words. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |