treeweft-mcp

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses key behavioral traits: top_k=5, optional file_path filter applied server-side, and that it returns focused context. However, it does not describe the output format or any side effects, which is a minor gap but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with usage context and key differentiators. Every word earns its place, and it avoids unnecessary detail while conveying the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, no output schema, no annotations), the description is incomplete. It does not explain what the tool returns, how to use most parameters, or any limitations beyond the top_k and file_path filters. An agent would struggle to use this tool effectively with only this description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions top_k (implicitly) and file_path, leaving 9 other parameters (language, use_hyde, cross_repo, etc.) unexplained. This is insufficient for a tool with 11 parameters, as the agent has no guidance on how to set them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear purpose: explaining a specific concept or section of code with tight, focused context. It explicitly contrasts with search_code, saying it is the same but with top_k=5 and an optional file_path filter, which distinguishes it from siblings and clarifies its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: use when the user wants a focused explanation (e.g., 'explain how X works') rather than broad search. It names the alternative (search_code) and highlights the differences, giving the agent a clear routing decision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that name resolution auto-resolves and returns callers across all matches with target_id set, which is a useful behavioral detail. However, it does not disclose whether the operation is read-only, any potential side effects, error behavior, or what happens when no callers are found or the entity does not exist. This is insufficient for a query tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence with no filler. It front-loads the core purpose ('Find callers of a function/method') and packs the two input modes into a compact, readable structure. Every phrase earns its place, making it both concise and efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists and the parameter count is small, the description leaves critical gaps: source_id is unexplained, and there is no guidance on when to use this tool relative to siblings like find_references. The tool could be called correctly with name_or_id alone, but an agent lacks context about optional parameters and selection criteria, making the description incomplete for optimal usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the missing parameter documentation. It explains the meaning of name_or_id (either a name that auto-resolves or a full entity id) and notes that results include target_id. However, source_id is completely undocumented in both the schema and the description, leaving agents to guess its purpose and behavior. The description adds some value for one parameter but fails to cover the other.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: finding callers of a function/method. It specifies the resource (function/method) and the action (find callers), and distinguishes it from sibling tools like find_references by focusing on callers specifically. The two input modes (name or full entity id) are explicitly described, making the intent unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by defining what the tool does and how inputs are handled, but it provides no explicit guidance on when to use this over alternatives like find_references or graph_explore. There is no mention of scenarios where this tool is preferable or when it should not be used. The input mode details (auto-resolve name vs. full id) are helpful but not contextual usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden and discloses key behavior: it returns every match across files and leaves disambiguation to the caller, indicating a read-oriented lookup. It doesn't explicitly state side-effect-freeness, but the 'Find/Looks up/Returns' framing makes the read-only intent clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences front-load purpose, then behavior, then filters; no filler. The only minor redundancy is 'Find where a symbol is defined' vs 'Looks up ... by name', but it doesn't hurt clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 3-param lookup complexity and an available output schema, the description supplies enough invocation context: what is searched, what is returned, and what each parameter does. A statement about no side effects or source_id provenance would be a small addition, but is not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so this dimension relies on the description. It defines name (lookup by name), kind (allowed values 'Class' or 'Function'), and source_id (scope to one indexed source), which covers all three parameters' primary semantics, though it doesn't specify name format or case sensitivity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names the exact operation ('Find where a symbol is defined') and the second narrows the resource to Class/Function entities, which clearly separates this from sibling tools like find_references and find_callers. It also states the return policy (all matches, caller disambiguates), so there's no ambiguity about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context: use when you need definition locations for a named Class/Function, and use optional filters to narrow by kind or source. It does not explicitly name alternatives or when-not conditions, but its purpose is specific enough to route selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully discloses that all incoming relationship kinds are returned and that input can be a name or entity id, but it does not mention behavior on ambiguous names, result limits, or whether the operation is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with the core behavior and relationship taxonomy front-loaded. There is no filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the basic call is feasible, but the description leaves source_id unexplained and gives no guidance for choosing among the many graph/reference sibling tools. It is adequate but not complete for confident selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies name_or_id as accepting 'a name or a full entity id', but says nothing about the optional source_id parameter, leaving its purpose unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Find all references' to a symbol, and enumerates the exact incoming relationship types (CALLS, INHERITS, IMPORTS, DEFINES). This clearly distinguishes it from siblings like find_definition and find_callers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for discovering all incoming references, but it does not explicitly say when to choose this over find_callers, find_definition, or search_code. No exclusions, prerequisites, or alternative routing guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. The word 'Get' implies a read-only operation, which is a positive signal. However, the description does not disclose any potential side effects, error conditions (e.g., invalid job_id), or whether the operation is safe. For a simple getter, the description provides minimal behavioral context beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the action ('Get') and the resource ('current state of an index job'). It is efficiently worded with no redundant information, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description lists the possible states, which tells the agent what to expect in the response. It does not mention error handling or the exact return format, but for a basic getter this is sufficient. No critical missing context for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does not explicitly mention job_id or its role. The description only says 'an index job', which indirectly refers to the parameter but does not explain its format, constraints, or how it relates to the job. The schema only lists the parameter as a string with a title, so the description adds little semantic value for the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'current state of an index job', and lists the possible states (queued/running/done/failed). It distinguishes this tool from siblings like list_index_jobs (which lists all jobs) and wait_for_index_job (which blocks). However, it does not explicitly name an alternative, so it loses a point for not being more explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (when you have a job_id and want its current state), but it does not provide explicit guidance on when not to use it or mention alternatives. Given the sibling tools, an agent might confuse it with list_index_jobs or wait_for_index_job. No exclusions or alternative routing is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the core behavior: finds entities related to the query, then traverses callers, callees, imports, and inheritance up to `depth` hops. This goes beyond the title and gives the agent a clear model of what happens. It stops short of stating whether the operation is strictly read-only or how results are returned, but the exploratory nature is well conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences. The first front-loads the use case with concrete examples, and the second states the traversal behavior while naming the alternative tool. Every clause adds value, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 10 parameters, no description coverage in the schema, no annotations, and no output schema. The description covers when to use it and the core traversal idea, but it omits the meaning of most parameters, return format, and any caveats or prerequisites. For a tool of this complexity, this is a material gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 10 parameters, but it only explains `depth` ('up to depth hops'). Parameters like `use_hyde`, `use_hybrid`, `rerank_pool`, `use_graph_scoring`, and `use_summary_vector` are left entirely to name inference, which is insufficient for a tool with this many tuning knobs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('explore', 'traverses') and resource (graph/connections) and clearly states the tool provides a structural/architectural view rather than code snippets. It explicitly distinguishes itself from `search_code`, and the examples ('what depends on X', 'call graph around Y') make the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance: when the user wants dependency/call-graph/architecture insight. It also provides an explicit exclusion and alternative: for 'find the code that does X', use `search_code` instead. This leaves little ambiguity about tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses that facet search returns no code, that this tool returns exact indexed chunks, reconstructs merged ranges, and supports markdown or JSON output. It does not cover error behaviors or edge cases, but for a read-oriented hydration tool it provides substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the first sentence states the core action, the second gives the workflow context, and the third covers output options. Every sentence contributes useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for the core calling pattern: it identifies the prerequisite call, the required input, the batching behavior, and the output format options. The main gap is the unexplained `source_id` parameter and the lack of guidance on failure or stale hit_id scenarios, but the output schema helps cover return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains that `ids` should be facet hit_ids and that `response_format` accepts 'markdown' (default) or 'json'. However, the `source_id` parameter is never mentioned, leaving one optional parameter semantically unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: fetch full code bodies for facet search hits. It differentiates itself from alternatives by referencing the specific search_code facet flow and read_file comparison. The verb 'fetch' and resource 'code bodies' are concrete and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool: after a search_code call with response_mode='facet', passing the hit_id values. It also names an alternative (read_file) and explains why hydrate_chunks is cheaper and more precise, giving clear decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses async return, the job_id, and the force re-index/no-op behavior. It does not mention side effects (index persistence) or permissions, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, async behavior, and force semantics. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async tool, it covers the key workflow: immediate return, job_id, and polling via get_index_job. It does not explain the pattern parameter or error handling, but given the simplicity and no output schema, it is reasonably complete. The missing pattern is the main gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain parameters. It explains force ('Set force=true to re-index... otherwise no-ops'), and directory is implied by the title. However, the pattern parameter is never mentioned, leaving its meaning and default unexplained, which is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Index all code files in a directory (recursive)'. This distinguishes it from siblings like index_file (single file) and index_repo (repo-level). The recursive scope and directory target are explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: it is asynchronous (returns immediately with job_id, poll get_index_job), and explains the force parameter's no-op behavior. However, it does not explicitly exclude alternatives such as index_file for single files or mention when to prefer another tool, leaving some inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool is asynchronous ('Returns immediately with a job_id'), names the follow-up tool for tracking, explains the no-op behavior for unchanged files, and details the underlying pipeline. This is rich behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero filler, and the core action is front-loaded. Each sentence adds necessary information: what it does, how to track it, and when to adjust behavior. The structure is ideal for an AI agent scanning quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two simple parameters, no annotations, and no output schema, the description is complete. It covers the asynchronous workflow, the no-op case, the force option, and the downstream storage destinations. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains force's meaning and effect in detail ('re-index even if this file is already indexed and unchanged'). file_path is not elaborated beyond 'single code file,' but its name and string type make it self-explanatory. This is good compensation for a small parameter set.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Index a single code file,' which clearly differentiates it from siblings like index_directory and index_repo. It also states the full processing pipeline and the asynchronous result behavior, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: this is for a single file, implying index_directory/index_repo are alternatives for broader scopes. It also explains when to set force=true and when the call no-ops, which is concrete usage guidance. It does not explicitly enumerate sibling alternatives or exclusion criteria, but the single-file scope is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly warns that it 'Drops the source's existing graph entities and re-extracts' – a destructive side effect – and further states it 'Returns immediately with a job_id; poll get_index_job', revealing the asynchronous nature. It also notes 'safe to re-run', which indicates idempotency. This is a thorough behavioral disclosure for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first line states the purpose, then usage conditions, then behavior, then async handling, and ends with a concrete sourcing instruction. Every sentence adds value; no filler or repetition. It packs a lot of essential context into two sentences without becoming unwieldy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter, no annotations, and no output schema, the description covers all necessary aspects: what it does, when to use it, potential destructive behavior, async nature, how to track progress, and where to obtain the source_id. There is no missing information an agent would need to invoke or monitor this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only declares source_id as a required string with no description coverage, leaving the description to compensate. The description adds crucial meaning by indicating that source_id refers to an already-indexed source and explicitly instructs 'Get source_id from list_indexed_sources'. This goes beyond the schema, though it doesn't explain the ID format or any validation rules, but for a single param this is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Build (or rebuild)') and resource ('Neo4j code graph for an already-indexed source'), and immediately identifies this as 'pass 2 of two-pass indexing'. It distinguishes itself from siblings by explicitly referencing the graph-backed tools that return empty and by noting it operates on an already-indexed source, which sets it apart from index_file/index_directory/index_repo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'when chunks/vectors exist but graph-backed tools return empty, or after a chunks-only index (skip_graph=true)'. Provides a prerequisite for obtaining source_id from list_indexed_sources and mentions the alternative of polling via get_index_job. This gives clear decision criteria and action steps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly: it reveals the async return via job_id, the polling mechanism, upsert/no-duplicate semantics, and the no-op behavior for unchanged sources unless force=true. This goes well beyond the basic 'index' action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding distinct value: what the tool does, how inputs are provided, and what behavioral results to expect. The core purpose is front-loaded and every sentence earns its place with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the job_id lifecycle, re-indexing behavior, force re-indexing, and acceptable source types. It does not explicitly state whether url and path are mutually exclusive or mention auth requirements, but for a 4-parameter tool with no output schema, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains path vs URL usage, the force flag's effect, and branch auto-detection for local repos. The branch parameter's role is only implied as an override rather than explicitly stated, which is a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Index a git repository' gives a specific verb and resource. The rest of the description further distinguishes it from siblings like index_file and index_directory by clarifying that it handles git repositories via local path or remote URL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on input types (local path with ~/ expansion or remote git URL) and the asynchronous workflow (returns job_id, poll get_index_job). It does not explicitly name alternative indexing tools or state when not to use this tool, but the usage context is strong enough to guide an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it lists sources and their stats, but does not reveal any potential side effects, performance implications, or whether the listing is read-only. For a no-parameter tool, the description is minimal and leaves the agent without information about ordering, pagination, or potential cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that front-loads the action ('List all indexed sources') and specifies the scope and content. There is no extraneous information, and every word serves a purpose. It is optimally concise for a simple listing operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so the description need not explain the return format. The description states the tool lists all indexed sources with their stats, which is sufficient for a no-parameter tool. Minor details like whether the list is paginated or ordered are not addressed, but the output schema likely covers the structure. Overall, it is reasonably complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is trivially 100%. According to the baseline for tools with no parameters, a score of 4 is appropriate. The description does not need to explain parameters that do not exist, and no additional semantic clarification is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all indexed sources (repos, directories, files) with their stats. It uses a specific verb and resource, and it is distinct from sibling tools like list_index_jobs or the indexing operations. The agent can unambiguously identify this as the listing tool for indexed sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or typical use cases. There is no direction like 'use this to view all indexed sources' or 'instead of X'. The agent must infer its purpose solely from the name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose scope ('across all sources') and what each entry contains, which is useful. However, it does not address filtering behavior, ordering, limits, or whether this is a purely read-only snapshot; those gaps keep it at minimum viable rather than strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two focused sentences: the first states the core action and return contents, the second gives concrete usage questions. No filler or redundant schema repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is an output schema, and the tool is simple with only one optional parameter. Still, the complete absence of parameter documentation is a real gap, and the description would be stronger if it mentioned that status filters results and what values are accepted. Overall adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one optional 'status' parameter with 0% description coverage, and the description never mentions that status can be used as a filter. It only lists status as an output field. Since schema coverage is low and the description does not compensate, an agent gets little guidance on how or why to supply this parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('List indexing jobs') and clearly defines scope ('across all sources'). It enumerates the fields returned and includes concrete user questions, making the tool's purpose unmistakable even among many sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear use cases ('is treeweft busy?', 'what happened to my last index job?'), which tells an agent when to select this tool. It does not explicitly contrast it with get_index_job, wait_for_index_job, or list_job_errors, so exclusions/alternatives are not fully spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the return structure in detail (file_path, error_kind, error_message, elapsed_s, occurred_at) and the read-only nature via the verb 'List.' It does not mention pagination behavior or how missing job IDs are handled, but the core behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence front-loads the main action and enumerates the output fields; the second adds a practical use case. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple read-only nature, the description covers the purpose, the returned entry fields, and the intended use case. Pagination defaults and required parameters are already present in the schema, and the absence of an output schema is compensated by explicitly listing the return fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies job_id as the identifier of a specific indexing job, but says nothing about limit/offset semantics or their defaults. The description adds useful meaning for the primary parameter but not for the pagination parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List the per-file errors recorded during a specific indexing job.' The resource is clearly distinct from siblings like list_index_jobs or get_index_job, and the 'which files failed?' and 'why?' clause reinforces the concrete use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case: 'Useful for which files failed? and why? without grepping process logs.' This implies when to use the tool but does not explicitly name alternatives or exclusion conditions, so it falls short of the full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers. It discloses idempotence ('drops + rebuilds, so rebuilding a healthy source is harmless'), async queue behavior ('kicks them off and returns'), and the unreliable graph_indexed flag ('jobs marked themselves indexed while writing nothing'). It also specifies the return shape ('one entry per source with its job_id (or error)'), which is critical for a bulk async operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (7 sentences) but each sentence earns its place: purpose, mechanics, trigger condition, idempotence, default with flag warning, return shape, and async follow-up. It could be trimmed slightly (e.g., 'POST /index-graph' is an implementation detail), but the density of relevant information remains high and the key caveats are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 1 optional parameter, no output schema, and no annotations, this description covers the decision to call it, the dangerous flag, the async nature, the return format, and the tracking mechanism. An agent can invoke it correctly and interpret results without needing additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate for the single boolean parameter. It does exactly that: 'only_missing=true (which filters to graph_indexed=false) will skip the very sources that need repair.' This adds critical semantic meaning beyond the Boolean type and default, explaining why the default is false and why setting it true is dangerous in the intended use case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Bulk-build the Neo4j code graph for indexed sources.' It then clarifies the mechanism ('Lists sources, then enqueues a graph job for each') and ties it to a concrete failure mode ('find_definition/graph tools are globally empty'), which distinguishes it from single-source siblings like index_graph. The only_missing caveat further disambiguates correct vs. incorrect usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the trigger condition: 'Use this once to repair a bulk import where chunks were indexed but the graph was never built.' It also warns against the harmful alternative ('only_missing=true ... will skip the very sources that need repair') and provides a follow-up action ('poll list_index_jobs(status='running') to track'), giving an agent a complete plan. No alternative tool is named, but the condition is precise enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It explicitly discloses the destructive side effects (drops Milvus chunks and Neo4j entities) and a safety nuance (preserves entities still referenced elsewhere). It does not explicitly state that the operation is irreversible, but the 'drops' language strongly implies permanence. This is adequate for a simple removal tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the primary action and includes the key side-effect and preservation note. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has only one parameter and no output schema, the description covers the essential behavioral context: what gets removed and what is preserved. It does not mention potential errors or asynchronous behavior, but for a straightforward removal operation the description is reasonably complete. A slightly more complete version would note irreversibility, but the current description is sufficient for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only the name 'source_id' with no description, and the tool description does not elaborate on what constitutes a valid source_id or how to obtain it. With 0% schema description coverage, the description should compensate, but it does not. The parameter semantics are left entirely to the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (remove) on a specific resource (indexed source) and describes the primary effect (drops Milvus chunks and Neo4j entities). This clearly distinguishes it from sibling tools which are all about indexing, searching, or explaining code. The removal tool is unique among the siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an indexed source needs to be removed, but it does not explicitly state when to use it versus other tools. There are no alternative removal tools, so no differentiation is needed, but it also does not mention any preconditions (e.g., source must exist) or post-conditions. It does mention a preservation nuance which gives some usage context, but overall it leaves the when-not-to-use implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations to provide a safety profile, the description carries the full burden and does so thoroughly: it explains the embedding/vector-search/graph-expansion pipeline, what fields chunks contain, citation format, response modes, staleness checking with a performance cost, and output format. No annotation contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place; it is front-loaded with the most important usage information and then layers supporting detail. Dense structure with scoping rules and response modes, but no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Coverage is strong for common use cases: scope requirements, response modes, citations, and performance trade-offs are all present, and an output schema exists so return-value details are redundant. It loses one point because the many advanced schema parameters remain undocumented and there is no explicit distinction from the sibling search_code_enhanced tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to several core parameters (query, top_k, language, source_id, path_prefix, cross_repo, check_staleness, response_mode, response_format) beyond a schema that has 0% description coverage. However, 10+ parameters (use_hyde, use_hybrid, rerank_pool, adaptive_topk, strip_imports, include_community_summaries, etc.) are left completely unexplained, which is a clear gap for a tool with 19 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise purpose: semantic code search over an indexed repository, returning ranked code chunks. It explicitly differentiates itself from grep/Read and establishes itself as the PRIMARY search tool, making the resource and behavior unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('use FIRST for any question about how indexed code works...') and names alternatives with the condition that selects them ('Prefer this over grep/Read for indexed repos: grep needs exact strings'). It also tells the agent when to raise top_k and warns against invalid scope combinations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it delivers: it discloses the two-pass search/rerank behavior, result citation fields and sources map, staleness checking cost, response_mode variants, and default output format. This goes well beyond a simple 'search' label.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficiently front-loaded: it opens with the decisive use condition, then packs behavioral and option details into a few sentences with no filler. Every sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (19 params, response modes, output formats) and the description covers most key behaviors and outputs, especially given an output schema exists. It leans on search_code for parameter definitions and doesn't spell out every parameter, but the essential invocation decisions (when, how, output shape) are addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds real meaning for check_staleness, response_mode, and response_format, and references search_code for the rest. However, with 0% schema description coverage for 19 parameters, most inputs (e.g., top_k, use_hyde, cross_repo, rerank_pool) are left undefined in this tool's definition and only inherited by reference to a sibling.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific use case ('when search_code results suggest the answer spans multiple structurally-related files') and a specific action ('pull in chunks from those neighbor files in one shot'). It clearly distinguishes itself from the sibling search_code by describing the second-pass Milvus search and neighbor-file filtering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly conditions use on search_code results and names the alternative directly. It also provides guidance among response modes, including when to fall back to read_file for 'facet' mode, and notes the performance tradeoff of check_staleness.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral burden. It discloses the underlying mechanism for local-path vs URL sources, the exact return shape, and the null behavior for non-git inputs. This exceeds the minimum expectation, though it stops short of mentioning error cases or network/auth dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly crafted sentences: the action, the mechanism, and the return value. No filler, all information is relevant)Skip the previous line. The return type and edge case are front-loaded, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter fro no output schema and no annotations, the description is nearly complete. It defines the return object and covers the non-git edge case, but omits practical details like how to obtain a source_id or what happens when a local path or URL is unreachable. For such a simple tool, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the single parameter. It reveals that source_id refers to 'an indexed source' and that it can be either a local-path or URL source, which adds meaning beyond the minimal schema. However, it does not explicitly address where source_id comes from or its expected format, leaving room for ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Check'), a specific resource ('indexed source'), and a precise outcome ('out of date relative to its current upstream HEAD'). It also distinguishes the tool from sibling indexing/search tools by describing a focused status-check behavior that none of the siblings cover.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool by explaining the check it performs)Skip the previous line. It does not explicitly name alternatives or state when not to use it. A user must infer that this is for verifying staleness rather than for indexing or searching, and there is no routing to sibling tools like list_indexed_sources.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool blocks, polls server-side, and terminates on done/failed/cancelled or timeout, which are key behaviors. It does not, however, describe what happens after timeout (e.g., returns a status or throws an error) or the exact return value, leaving a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two sentences that front-load the core action ('Block until...') and then add the polling detail and usage context. Every sentence earns its place; there is no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple wait tool with only two parameters and no output schema, the description covers purpose, behavior, and usage. However, it omits what happens on timeout (return vs. error) and does not describe the return value format, which is a meaningful gap given that the output schema is absent. The description is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for missing parameter explanations. The description does not clarify job_id (where it comes from) or timeout_s beyond the default. While the parameter names are self-explanatory, the description adds no additional meaning, and the lack of guidance on the source or format of job_id is a notable omission.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: it blocks until an index job reaches done/failed/cancelled or a timeout. The verb 'block' and the resource 'index job' are specific, and the terminal states are enumerated. It distinguishes itself from siblings like get_index_job, which would check status without blocking, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides a usage condition: 'Use this when you want a synchronous index call.' This tells the agent when to select this tool over the asynchronous alternatives. However, it does not name specific alternatives or explicitly state when not to use it, so it falls short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.