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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say the file is modified in place, where the field lands by default, whether the write is transactional, or what happens if the model is not found. Only format coverage is offered.

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, front-loaded with the action and then the applicable formats. Zero filler; nothing could be removed without losing 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?

For a 6-parameter, 3-required destructive mutation tool with no output schema, the description is minimal. The schema covers parameters well, but an agent gets no guidance on default placement, error behavior when the model/file cannot be resolved, or interaction with the sibling editing tools.

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 100% and every parameter has its own description, so the schema does the heavy lifting. The description only restates the supported languages and a couple of field_type examples that already appear in the schema, adding no new semantic detail (e.g. how the default insertion point is chosen when 'after' is omitted).

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?

States a concrete verb+resource ('Add a field to a model/class/interface') and enumerates the supported file types and frameworks (.prisma, .py dataclass/SQLAlchemy, .ts/.tsx). It is clear on its own, but it does not distinguish itself from sibling editing tools such as insert_near_symbol or edit_lines_in_symbol, which likely also mutate source structure.

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 supported-format list implies when the tool applies, but there is no explicit when-to-use guidance versus the many sibling mutation tools (insert_near_symbol, replace_symbol_source, edit_lines_in_symbol). No prerequisites, no exclusions, no alternative named.

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?

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description doesn't need to restate that. It adds only the audited formats and check names, and says nothing about how secrets are reported (redacted vs raw), how the capped issue list is ordered, or what happens when no config file matches.

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?

A single front-loaded line with zero filler: verb, resource, formats, and check categories in one sentence. It is arguably clipped to the point of under-specification, but nothing is padded or redundant.

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?

No output schema exists, yet the description does not describe the shape of the audit report (severity grouping, issue locations, how many issues are returned). For an audit tool whose whole value is the report, that leaves a real 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 100%, so every parameter and its defaults (project default: active, max_issues default 10, 0 = unlimited) is already documented in the schema. The description names three of the five check values but omits 'loaders' and 'schema', adding no semantics beyond the schema.

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?

States a specific verb ('Audit') and resource ('config files') and narrows scope with concrete file formats (.env/.yaml/.toml/.json) and three check categories. It reads clearly apart from file-read siblings like read_lines or get_env_usage, though it never explicitly contrasts itself with them.

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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as get_env_usage or analyze_docker. The agent must infer that this is the config-audit entry point purely from the name and file extensions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds useful scope content (which Dockerfile aspects are audited and that it cross-references config files), a modest addition beyond the structured fields. It says nothing about output format or depth of analysis.

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?

A single front-loaded sentence with a colon-delimited enumeration; no filler and the audited dimensions are immediately visible.

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 read-only audit tool with one optional parameter and no output schema, the description adequately conveys what is inspected. It could be slightly more complete by hinting at the shape or scope of the audit result, but the annotations carry the safety profile.

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?

Only one optional parameter (project) with 100% schema coverage, so the schema already documents its meaning and default. The description adds no parameter-level detail, and the baseline for a fully documented schema is 3.

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?

States a specific verb (audit) and resource (Dockerfiles) and enumerates what it inspects: base images, stages, exposed ports, ENV/ARG, and config cross-referencing. It is distinguishable from most siblings, though it does not name the closely related analyze_config or get_env_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?

There is no when-to-use guidance, no prerequisites, and no mention of when a sibling like analyze_config would be preferred. The Dockerfile scope is implied by the resource name but nothing routes the agent between overlapping analysis tools.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the annotations: no mention of whether it reads git history vs. current index, how 'hotspots' are computed, or whether the narrative is deterministic.

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?

A single unpunctuated fragment is not concise so much as under-specified; there is no front-loading of the core action and no structure to separate purpose from output. It under-delivers rather than being tight.

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 no output schema, the description partially compensates by naming the output contents (stats, hotspots, suggested type), which is genuinely useful. However, for a 4-parameter tool with no usage guidance and no behavioral detail, it remains thin overall.

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 75% (project, max_files, max_symbols_per_file documented; changed_files is self-evident as required). The description adds nothing about parameters, but the schema largely carries that burden, so the baseline 3 applies.

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 fragment 'Compact commit/review narrative with stats, hotspots, suggested type' conveys that a summarized commit/review artifact is produced, but it is a noun phrase with no verb and no explicit scope. It does not distinguish itself from siblings like get_project_summary, get_changed_symbols, or find_hotspots, which plausibly overlap.

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?

There is no statement of when to call this tool, what preconditions it needs (e.g., a git repo state or prior change detection), or which sibling to use instead. The agent must infer usage purely from the name.

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?

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds no behavioral context beyond the transform vocabulary that already lives in the schema - nothing about what the id refers to, cost, or result shape for a read-only aggregation.

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?

A single front-loaded sentence with the operation modes listed compactly. No filler, though the brevity borders on under-specification of the modes' semantics.

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 read-only tool with safety annotations and no output schema, the essentials are sparse. The description omits what the required id references and how each transform behaves, which an agent would need to call the mode variants 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 coverage is 67% and the schema already documents transform and pattern. The description partially mirrors the transform enum but adds no meaning beyond it and says nothing about the required id parameter, so it does not compensate for the coverage 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?

States a specific verb (aggregate) and resource (capture) and enumerates the aggregation modes, which separates it from capture_get, capture_search, and capture_list. It is less explicit than ideal about what a 'capture' is, but the intent is readable.

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?

No when-to-use guidance and no alternatives named. It never explains when to pick stats vs count_lines vs extract vs count, nor how this differs from pull-oriented siblings like capture_get or capture_list, leaving selection to 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that – no note on truncation when max_bytes clips content, no indication of what a capture contains or how large reads behave.

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?

One short sentence, front-loaded with verb and resource, and the range hint is placed immediately after. No wasted words, though it is arguably terse enough that the range list omits the schema's 'relevant:' mode.

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 read-only tool with 100% schema coverage and full annotations, the definition is minimally adequate. It never explains what a capture is, how it relates to the capture_search/capture_list siblings, or that max_bytes may truncate the returned content.

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 100%, so the schema already documents id, range (including the 'relevant:<question>' mode), and max_bytes in more detail than the description. The description's range list is a partial restatement rather than added meaning, so the baseline 3 applies.

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?

States a specific verb (Read) and resource (a capture), and the parenthetical previews the range modes. It does not differentiate itself from the other capture_* siblings (capture_search, capture_list, capture_aggregate), but the purpose itself 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?

No guidance on when to use this tool versus capture_search or capture_list, or versus read_lines/get_function_source for reading content. The agent must infer that 'id from search/list' means capture_get is the follow-up fetch step, but nothing states this explicitly.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description contributes one real behavioral fact beyond that (results are ordered newest first), but says nothing about default row counts, pagination, or what a capture record contains.

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?

A single front-loaded sentence with zero wasted words. It is efficient, though arguably too terse for a four-parameter tool whose filtering capabilities go unstated.

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 read-only list tool with no output schema, the annotations do carry the safety burden, but the definition still omits the three filter parameters and any return-shape or pagination detail. An agent could call it, but not correctly scope it.

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 only 25% — just the limit parameter is documented — yet the description mentions no parameters at all. The three filter parameters (tool_name, session_id, project_root) are undocumented in both the schema and the description, so an agent cannot learn from this definition that listing can be scoped at all.

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?

States a specific verb (List) and resource (captures) plus a meaningful ordering guarantee (newest first). However, it draws no boundary against the many sibling read tools (capture_search, capture_get, capture_aggregate), so an agent must infer the distinction from the name alone.

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?

There is no explicit when-to-use guidance and no mention of the alternatives: capture_search for filtered queries, capture_get for a single item, capture_aggregate for rollups. Usage is only implied by 'recent', leaving the agent to guess when this beats capture_search.

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the useful non-schema constraint that a filter is mandatory, but says nothing about irreversibility, scope of deletion, or whether results are recoverable — expected additions for a destructive purge.

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?

A single short sentence, front-loaded with the destructive verb and the resource, with the critical constraint tucked in parentheses. Nothing is wasted.

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 destructive tool with no output schema and no required parameters, the description covers the essential precondition but omits return information and the consequence of an over-broad filter. Combined with annotations that carry the destructive hint, it is adequate but not 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 coverage is only 33%, with just older_than_sec documented, so the description must compensate. 'by age/session/project' maps loosely onto older_than_sec, session_id and project_root, giving each filter a conceptual meaning, but it does not clarify whether filters combine as AND/OR or what a missing filter means.

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?

States a specific verb (Delete) and resource (captures) plus the three filtering dimensions (age/session/project), which is enough to distinguish it from sibling read tools like capture_list and capture_search. It stops short of naming a specific alternative, so it sits at a clear-but-undifferentiated 4.

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 parenthetical '(filter required)' is real usage guidance — it tells the agent a precondition that the schema does not enforce (0 required parameters). However, there is no when-to-use versus capture_get/memory_delete guidance and no indication of what happens if a filter is omitted despite the warning.

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?

Annotations already declare readOnlyHint=false and non-idempotent, so the write nature is covered structurally. The description adds value by disclosing the return payload ('returns id + preview') and the backing store (FTS5), but says nothing about durability, dedup, or how the id is later used with capture_get.

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?

A single front-loaded sentence with no wasted words, delivering action, destination, and return value in one pass.

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?

No output schema exists, so the description appropriately spells out the return (id + preview), and params are fully documented in the schema. Minor gap: no routing guidance to the retrieval siblings that consume the returned id.

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 100%, so the schema already documents all six parameters and the baseline is 3. The description adds no parameter-level detail (e.g., what 'preview' truncates or how tool_name keys retrieval) beyond what the schema provides.

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?

States a specific verb (sandbox/capture) and resource (verbose tool output) and names the destination store (FTS5) plus the return shape (id + preview). An agent can tell what it does, but it does not explicitly distinguish itself from the capture_get/capture_search family by name.

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 phrase 'sandbox a verbose tool output' implies the scenario, but there is no explicit when-to-use, no prerequisites, and no named alternative among the many capture_* and memory_* siblings. An agent must infer that this is the write side of the capture family.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the retrieval mechanism (BM25) and the result fields (id, snippet, bytes), which is useful behavioral context, but says nothing about ranking behavior, pagination, or what tokens the FTS5 query accepts.

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 short sentences, front-loaded with the mechanism and scope, and the return fields are stated compactly. Nothing is padded, though it is arguably terse to the point of leaving gaps rather than being efficiently complete.

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 no output schema, the description does useful work by naming the return fields. However, for a 5-parameter tool it omits how the capture store is populated, how session_id/project_root scope results, and how it relates to its capture_* siblings, leaving the definition only minimally 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 coverage is only 60%, and session_id and project_root have no schema descriptions at all. The description adds no parameter meaning and does not compensate for the undocumented fields, so an agent cannot tell how scoping by session or project works.

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?

States a specific verb and algorithm (BM25 search) and a scope (sandboxed tool outputs), which separates it from capture_get/capture_list. It does not, however, distinguish it from the other search siblings such as memory_search, search_codebase, or corpus_query, so an agent must infer which search corpus applies.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no reference to alternative tools. Given several search-shaped siblings (memory_search, corpus_query, search_codebase, ts_search), the absence of routing guidance is a real gap.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, yet the description lists 'delete' and 'prune' operations, which inherently remove data, and 'restore', which can overwrite project state. The description does not clarify this tension, nor does it say what a checkpoint contains, whether restore is reversible, or what compare returns. It adds essentially nothing beyond the operation names already in the enum.

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 short sentences, purpose front-loaded and the operation list compactly encoded. 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?

For a six-parameter multi-operation tool with no output schema, the description is too thin: it never explains what a checkpoint is, what restore/prune actually do to project state, or how compare differs from a diff. Annotations only cover the safety profile, so the behavioral burden falls on the description and is largely unmet.

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 100%, and the schema already documents each parameter's role and defaults (e.g., keep_last default 10, checkpoint_id for restore/delete/compare). The description repeats the operation set but adds no syntax, format, or interaction detail beyond the structured fields, so baseline 3 applies.

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?

States a specific verb+resource ('Unified checkpoint CRUD') and enumerates the six operations, so the agent immediately knows the domain. It is clear and self-contained, but it does not distinguish itself from any sibling tool or clarify scope beyond the name.

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 op enum and the '(default)' marker imply usage, and listing the operations gives a rough map of when each branch applies. However, there is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives among the many sibling tools.

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?

Annotations already declare this is a non-readOnly, idempotent, non-destructive, closed-world write, so the safety profile is covered. The description adds the scope of what is included (type/tags/symbol) but says nothing about persistence, what happens when the name already exists, or whether an existing corpus is overwritten or fails.

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?

A single front-loaded sentence with no wasted words. It is efficient, though arguably under-specified rather than merely concise given the five-parameter schema.

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 five-parameter write tool with no output schema and only 40% schema coverage, one sentence is thin. It omits how filters combine, the project/active-project prerequisite, error behavior on duplicate names, and any relationship to corpus_query, leaving an agent without enough to invoke it confidently.

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 only 40%: filter_tags, filter_type, and filter_symbol have no schema descriptions. The description partially compensates by mapping 'type / tags / symbol' to those three parameters, but it gives no combination semantics (AND/OR), value formats, or default behavior for the project 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?

States a specific verb ('Build') and resource ('thematic corpus'), plus its input source ('observations') and filter facets. It is distinguishable from the 'corpus_query' sibling by verb, though the description never explicitly contrasts the two.

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 filtering facets imply the context (create a corpus from filtered observations), but there is no explicit when-to-use guidance, no mention of the paired 'corpus_query' tool, and no prerequisites such as project context or required permissions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that the output is markdown context packaged with the question, hinting at the return shape, but says nothing about size limits, truncation, or what happens if the corpus is missing.

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?

A single compact sentence with the core action front-loaded and no wasted words. The phrasing 'markdown context + a question' is slightly informal but efficient and clear.

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 3-parameter read-only retrieval tool with no output schema, the description covers the essentials of what is produced. However, it leaves genuine ambiguity about whether the tool answers the question or merely assembles the context, which could mislead an agent about the result.

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 100%, with all three parameters documented including the corpus_build dependency and the project default. The description adds no parameter-level meaning beyond this, so the baseline 3 applies since the schema does the heavy lifting.

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 action (format observations of a named corpus as markdown context plus a question) and a clear resource. It implicitly separates this from corpus_build, which constructs the corpus, but never names that sibling explicitly. The 'ready for answering' framing usefully clarifies it prepares context rather than producing a final answer.

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?

There is no when-to-use or when-not-to-use guidance, and no exclusions or alternatives are named. The only hint of usage context is in the schema field ('previously built via corpus_build'), which is not part of the description. An agent gets no routing help from the description text itself.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully narrows behavior by enumerating the breaking-change classes detected, but says nothing about scan scope (whole project vs. changed files), output format, or how the git-ref comparison is performed.

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?

A single front-loaded sentence naming the operation, the comparison basis, and the detected categories. No filler, no repetition of the title, and the most decision-relevant information leads.

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 no output schema, the description should at least frame what comes back; it partially does by listing the change categories. However, it omits result scope (whole project vs. diff range), and any indication of how findings are grouped or surfaced, leaving the agent under-informed about the response for a diff-analysis 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?

Schema coverage is 100%, so both parameters (project, since_ref) are already fully documented in the schema, including defaults and accepted ref forms. The description's 'vs a git ref' phrase only loosely mirrors since_ref and adds no syntax or semantics beyond the schema; baseline 3 applies.

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?

States a specific verb+resource ('detect breaking changes') and enumerates the exact change categories it flags (removed funcs/params, added required params, signature changes), so the agent knows precisely what it returns. It does not, however, distinguish itself from close siblings such as get_change_impact or get_changed_symbols, so an agent still has to guess which of the several change-analysis tools applies.

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 no when-to-use guidance and names no alternative. Given siblings like get_changed_symbols, get_change_impact, and build_commit_summary, the absence of any routing cue (e.g. 'use this when you only care about API-breaking edits') leaves selection ambiguous.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral value by naming the data source (build files) and asserting nothing is executed, which matters given the adjacent runner tool. No permission, cost, or caching details are added.

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?

A single tight sentence with the action, source and constraint front-loaded. Zero filler and no 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?

For a single-optional-param, read-only discovery tool with no output schema, the description gives enough to call it correctly. It could hint at the shape of the detected actions (names/labels), but with no output schema that is not required.

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?

Only one parameter and schema coverage is 100%, so the schema already documents 'project' including the default-to-active behavior. The description adds nothing beyond it; baseline 3 applies when the schema does the work.

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?

Specific verb ('Detect') plus resource ('conventional project actions from build files'), with the enumerations (tests, lint, build, run) and the key qualifier 'without executing' that distinguishes it from the run_project_action sibling. An agent can tell it apart from the sibling without opening the schema.

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?

'Without executing' implies this is a dry discovery step that precedes execution, so the usage context is inferred rather than stated. It never names run_project_action or explicitly says 'use this first, then call the runner.' Adequate but leaves routing to 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered. The description adds meaningful behavior beyond that: exact old_string→new_string matching like Edit, scoping to a single symbol, and the replace_all semantics for multiple occurrences.

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?

Front-loads the key differentiator ('Edit code without reading the file first') and follows with the mechanism and the replace_all behavior. Every sentence earns its place with no 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 destructive edit tool with annotations covering safety, the description supplies usage, matching semantics, and scoping rules. No output schema exists, but an edit tool needs little return-value explanation. Minor gap: no mention of failure behavior when the symbol name is ambiguous or not found.

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 100%, so all six parameters are already documented, including old_string uniqueness within the symbol and replace_all defaults. The description reinforces the matching model but adds little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb (edit) and resource (lines inside a symbol/function/class), and explicitly distinguishes itself from the sibling Edit tool by noted scoping ('matched only inside one function or class'). An agent can tell it apart from replace_symbol_source and Edit without opening a schema.

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?

Names the alternative tool (Edit) and the condition that selects it: when a large file would otherwise require reading in full. It also clarifies the constraint that matching happens only inside one symbol. It stops short of stating when NOT to use it (e.g. multi-symbol or cross-file edits), so not a 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?

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description adds meaningful analytical context beyond annotations: what counts as dead (zero callers) and what is deliberately excluded (entry points, tests, route handlers). It doesn't mention cost or runtime, but this is useful transparency for a static analysis.

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?

A single front-loaded sentence with the core definition first and the exclusion scope in a tight parenthetical. Every clause earns its place; no waste.

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 read-only, two-parameter analysis tool with full schema coverage and no output schema, the description plus annotations give an agent enough to invoke it correctly. Only the absence of when-to-use routing against sibling analysis tools keeps it short of 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 100%, so both parameters (project default, max_results with 'header shows true total' note) are fully documented in the schema. The description adds no parameter detail beyond what the schema already provides, so baseline 3 applies.

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?

Names a specific analysis (audit of unreferenced functions/classes) with the defining criterion (zero callers) and explicit scope exclusions. An agent can distinguish this from siblings like find_semantic_duplicates or find_import_cycles without opening the schema.

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 it applies via 'project-wide audit' and the exclusions, but never states when to prefer this over related analysis tools (find_semantic_duplicates, find_import_cycles, get_entry_points) or any prerequisites. Usage is inferable but not guided.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, covering the safety profile. The description adds nothing behavioral on top of that: no indication of sort order, scoring basis, or scope of analysis. The one extra fact (language applicability per kind) is a validity constraint rather than behavior, so it is credited under parameter semantics.

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?

Extremely compact and front-loaded — the core action leads and the kind/language mapping follows. The pipe-delimited fragment is slightly cryptic and borders on under-specification rather than conciseness, which keeps it off a 5.

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 100% schema coverage, annotations, and no required parameters, the agent can invoke this correctly. Still missing for a ranking tool are the ordering of results (descending score?) and the analysis scope, which the description never addresses and the schema does not cover.

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 100%, so the baseline is 3, and the description genuinely adds meaning the schema lacks: it tells the agent that 'allocation' and 'performance' only apply to Java while 'complexity' spans all languages. That is a non-obvious constraint that prevents selecting an invalid kind for a non-Java project.

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?

States a specific verb (rank) and resource (functions) plus the hotspot categories that define the operation, so an agent knows this produces a ranked hotspot list. It is clearly distinct from siblings like get_functions or find_dead_code, though 'hotspot' itself is never defined beyond the enum values.

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 parenthetical language tags ('complexity (all langs)', 'allocation (Java)', 'performance (Java)') imply which kind to choose for a given codebase, which is real guidance. However there is no explicit when-to-use versus alternatives, no prerequisites, and no statement of when NOT to call it.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the word 'likely', which usefully signals a heuristic, non-exhaustive result, but says nothing about how inference is computed or what the response contains.

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?

A single front-loaded sentence with zero filler that states the action and the input sources immediately.

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 zero-required-parameter inference tool with no output schema, the description covers the essential 'what'. It is slightly thin on how likely-impact is determined and what the returned list looks like, but the model's read-only, heuristic nature is fairly communicated.

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 50%: project and max_tests are documented in the schema while symbol_names and changed_files are not. The description names 'changed files or symbols', partially compensating for those two undocumented parameters, but adds no format, precedence, or interaction detail.

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?

Specific verb ('Infer') and resource ('pytest files likely impacted') make the operation unambiguous. It does not, however, explicitly differentiate itself from the sibling run_impacted_tests, which an agent must infer runs rather than finds the files.

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 phrase 'changed files or symbols' implies the intended trigger context, but there is no explicit when-to-use guidance, no when-not guidance, and no reference to the closely related run_impacted_tests alternative. Usage is only inferable.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety is covered. The description adds no behavioral context beyond the algorithm name – it doesn't say how results are ordered, whether partial cycles are returned, or how max_cycles=0 affects output volume.

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?

A single front-loaded sentence with zero filler, correctly placing the verb and the clarifying parenthetical about SCCs and the algorithm.

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 two-param read-only diagnostic with no output schema, the description covers the what but not the output shape (list of cycles? nested structure?) or result ordering. Annotations handle the safety profile, so nothing critical is missing, but the return-value gap leaves the agent unsure how to consume the result.

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 100%, so baseline is 3. The description adds no parameter meaning beyond the schema's own documentation of 'project' and 'max_cycles' defaults and the unlimited-flag.

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?

States a specific verb (Detect) and resource (import cycles in the file-level import graph), plus names the algorithm (Tarjan's) and clarifies the output is strongly-connected components. This is much more specific than the sibling get_imports, though it doesn't explicitly contrast against it or find_dead_code.

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?

No guidance on when to use this tool versus siblings like get_imports, get_file_dependencies, or find_dead_code, which all touch the import graph. The agent must infer the diagnostic use case on its own.

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?

Annotations already declare this a safe, idempotent, non-destructive read. The description adds real behavioral texture: ast is hash-based copy-paste detection, embedding uses Nomic cosine conceptual matching, and results are tagged with a sim=min..mean range per cluster (an output-shape hint). The ~2min reindex cost for embedding lives in the schema rather than here, so it isn't double-credited.

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 tightly packed sentences, with the core purpose front-loaded and the mode comparison following. No filler, though the parenthetical enumeration is dense enough to require a second read.

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 no output schema, the description carries the burden of explaining what comes back. It hints that embedding clusters carry sim=min..mean tags but never describes the structure of a duplicate group, so an agent must infer the return shape. Safety is covered by annotations, so the gap is moderate rather than severe.

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 100%, so all five parameters are already documented with defaults and tradeoffs (min_lines applies to ast, min_similarity to embedding). The description only adds semantics for the method parameter, which the schema also explains; baseline 3 is appropriate.

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?

States a specific verb and resource ('Find duplicate functions') and immediately distinguishes the two detection modes. An agent can tell what it does without opening the schema, though it doesn't name a sibling it supersedes (e.g. find_dead_code) to sharpen the boundary.

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?

Gives clear guidance on choosing between method='ast' and 'embedding' (fast hash-based vs conceptual clones), which is the key decision. But it offers no tool-level when-to-use or when-not guidance relative to the many sibling analysis tools, and no exclusions or prerequisites at the description level.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered structurally. The description contributes result-shape context (file/line/signature/preview in one call, definition-only vs. all mentions) beyond the annotations, but adds nothing on truncation, limits, or failure behavior, so it stays at a minimum-viable 3.

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?

Essentially one dense, front-loaded sentence that leads with the core value proposition (definition location in one call) and then qualifies scope against Grep. Efficient with no filler, though the run-on structure makes it slightly harder to parse than a clean 5.

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 no output schema, the description does the work of describing the return payload (file, line, signature, preview) and result ordering, which is the right compensation for a 10-parameter tool. It is complete enough to invoke, though return-format absolutes and multi-result/pagination behavior remain unaddressed.

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 90% and the schema already documents name aliases, kinds, level, names batching, hints, project, and compress. The description adds no parameter-level meaning at all (nothing about the name-alias set or batch mode), so the baseline 3 applies for high-coverage schemas.

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?

States a concrete verb+resource ('where is X defined: file, line, signature and preview') and explicitly contrasts with Grep's every-mention behavior, so an agent knows this is a definition-locator, not a text search. It does not differentiate itself from close code-intel siblings such as search_in_symbols, get_class_source, or get_function_source, which caps it below a 5.

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?

Usage is implied rather than stated: it says results are ordered 'functions and classes first, then module constants and variables,' which hints at defaults, but there is no explicit when-to-use/when-not or named alternative (e.g., 'use get_function_source for the full body'). A 3 reflects adequate but inferential 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context by specifying BFS shortest-path semantics, but says nothing about result ordering, direction, or behavior when no path exists. Given the annotation coverage, a 3 is appropriate.

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?

A single front-loaded sentence with no wasted words, stating the operation and the algorithm. It is efficient, though arguably terse enough that it could have afforded one more clause on when to use it.

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 100% schema coverage, no output schema, and simple flat parameters, the definition provides enough to invoke the tool correctly. The main gap is the absence of usage/routing guidance relative to the many dependency-analysis siblings.

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 100%, so all four parameters (from_name, to_name, project, level) are documented in the schema itself, including the level enum semantics. The description adds no parameter-level detail, so the baseline 3 applies.

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 gives a specific resource ('dependency path between two symbols') and mechanism ('BFS through the dep graph'), which distinguishes it from siblings like get_dependencies and get_dependents that operate at a single level. It is clear what the tool computes, though it does not explicitly name an alternative for contrast.

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?

There is no guidance on when to reach for this tool versus get_dependencies, get_dependents, get_change_impact, or find_symbol. No prerequisites or exclusions are stated; the agent must infer usage purely from the one-line purpose.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds the worktree-vs-ref distinction but omits important behavior: whether results are truncated at max_files/max_symbols_per_file and what happens when limits are hit. Adequate but thin given the low annotation burden.

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?

A single tight sentence with the core concept front-loaded and no filler. It is efficient, though so terse that some behavioral context is lost rather than merely compressed.

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 no output schema, the description should carry more about the returned shape and truncation behavior implied by the max_files/max_symbols_per_file defaults. Annotations cover safety, but the agent still lacks enough to predict results for a 4-parameter analysis 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?

Schema coverage is 100%, so all four parameters are documented in the schema. The description only echoes the ref semantics ('HEAD vs ref') and clarifies nothing about max_files or max_symbols_per_file truncation, so it lands at the baseline for a fully-covered schema.

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?

States a specific verb+resource ('Symbol-level summary of ... changes') and even names the two comparison scopes (worktree, HEAD vs ref). The 'symbol-level' qualifier usefully distinguishes it from file-level siblings like get_git_status, though no sibling is named explicitly.

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?

There is no guidance on when to pick this over get_git_status, build_commit_summary, get_change_impact, or find_hotspots, all of which touch change analysis. The parenthetical 'or HEAD vs ref' hints at a mode but doesn't state when each is appropriate.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds the useful scope detail that results include transitive dependents, but says nothing about result shape, depth caps, or symbol-name resolution.

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?

A single front-loaded clause with zero filler; the scoping fact (direct + transitive) comes first. It is arguably undersized for a five-parameter tool, which keeps it from a 5.

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 read-only analysis tool with annotations covering safety and 80% schema coverage, the minimum is met, but with no output schema the agent gets no hint about return format, result volume, or how to identify the symbol by name. Those gaps leave it merely adequate.

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 80%, so the schema documents project, max_direct, max_transitive and max_total_chars; the description adds no parameter meaning beyond that. Baseline 3 is appropriate since the schema does the heavy lifting, though the required 'name' parameter's expected format (qualified name vs path) is undocumented anywhere.

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?

States a specific resource ('symbol') and analysis type ('direct + transitive dependents'), which is enough to separate it from the sibling get_dependents (direct-only) and get_call_chain. It is clear but terse, and does not explicitly name the sibling it is not, so it stops short of a 5.

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 phrase 'Impact analysis' implies the pre-change workflow (assess blast radius before editing), but there is no explicit when-to-use, no prerequisites, and no routing to alternatives like get_dependents or find_impacted_test_files. Usage is inferable rather than stated.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description's only addition is naming the returned fields, which is mildly useful given no output schema exists, but it adds no pagination or scope behavior of its own.

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?

A single compact sentence, front-loaded with the verb and resource, with zero wasted words. Field list is dense but earns its place by hinting at return shape absent an output schema.

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 read-only list tool whose annotations cover safety and whose schema covers every parameter, the description is nearly sufficient. The only shortfall is routing guidance versus sibling listing tools.

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 100%, so all five parameters are already documented in the schema (hints, project, compress, file_path, max_results). The description adds no parameter syntax or filtering semantics beyond what the schema provides, so the baseline 3 applies.

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?

States a specific verb+resource ("List classes") and even enumerates the returned fields (name, lines, methods, bases, file). However, it does nothing to distinguish itself from closely named siblings like get_functions or get_class_source, so an agent must infer the boundary.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_class_source (single-class detail) or get_functions (function listing). The agent must guess the selection criteria entirely.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the content-scope note '(including methods)' and says nothing about caching (relevant given force_full), level-based truncation, or batch return shape.

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?

A single, front-loaded sentence with zero filler. It is efficient, though arguably terse given the tool's complexity, so it stops short of a 5.

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 10-parameter tool with no output schema, aliases (class_name, symbol_name), a batch mode, caching bypass, and level-based line capping, the description is far too thin. It leaves the agent to infer most operational behavior from the schema alone.

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 70% with 10 parameters, and several key inputs ('name', 'level', 'file_path') carry no schema description at all. The description mentions none of the parameters, so it does not compensate for the coverage gap, particularly the mutually exclusive name/names batch behavior.

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?

States a specific verb and resource ('Fetch a class source body') and scopes the content with '(including methods)', which cleanly separates it from the sibling get_function_source. It does not name the sibling explicitly, but the class-vs-function distinction is inferable from the resource.

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?

There is no when-to-use guidance, no mention of when to prefer this over get_function_source or get_full_context, and no guidance on the batch 'names' mode versus the single 'name' mode. Usage is only implied by the verb.

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?

Annotations already declare readOnly=true, idempotent=true, non-destructive=true and closed-world, so the safety profile is fully covered. The description adds one useful behavioral fact beyond that: the data comes from migrations ('condensed SQL-migration snapshot') rather than live introspection, which affects staleness expectations. It does not disclose truncation, size limits, or cost of the call.

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?

A single front-loaded sentence that enumerates the return contents with zero filler. Every token 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?

With no output schema, the description carries the return-value burden and does so by listing the schema elements returned. Combined with complete parameter coverage and full annotations, an agent has nearly everything needed; only the migration-vs-live distinction and result size/pagination are unstated.

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 100%, with each of the four parameters (tables, dialect, project, migrations_dir) fully documented including defaults and the 'postgres only' constraint. The description adds nothing beyond the schema, so the baseline 3 applies.

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?

States a specific resource (database schema) and enumerates exactly what the snapshot contains: tables with columns/types/nullability/defaults, PKs, FKs, indexes, and RLS policies. None of the sibling tools return DB schema, so an agent can distinguish this from get_structure_summary or get_file_dependencies immediately.

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?

No when-to-use guidance, no mention of alternatives, and no stated prerequisites. The migration-derived nature of the snapshot is implied by 'SQL-migration' but never explained as a usage condition, and there is no hint that a live-DB variant might be the alternative.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the bar is low. The description adds the downstream semantics but says nothing about depth behavior, result volume, or truncation beyond what the schema already carries.

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?

A single front-loaded sentence with no filler; the core concept leads and the parenthetical gloss clarifies it. It is tight, though arguably too terse for a five-parameter graph tool.

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 graph-traversal tool with five parameters and no output schema, the description leaves return shape and traversal behavior to the schema and omits any routing against the many related dependency tools. Annotations cover safety and the schema covers params, so it is minimally viable but thin.

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 80%, with depth, project, compress and max_results all self-documented in the schema (including the truncation marker). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

States a specific verb+resource ('Outgoing deps of a symbol') and immediately glosses it as 'what X calls/uses (downstream)', which an agent can map to a concrete graph query. The 'outgoing/downstream' framing distinguishes it from the sibling get_dependents (incoming/reverse) without opening either schema.

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 directional framing ('outgoing...downstream') implicitly signals when to reach for this tool versus get_dependents or get_file_dependencies, but there is no explicit when-to-use, when-not, or named alternative. Usage is implied rather than stated.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety and repeatability are covered. The description's one additional behavioral fact is 'direct references only', which discloses the transitive-depth limit and is useful, but it says nothing about result shape or scaling/limits.

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?

A single compact fragment that front-loads the key information with zero filler. It is arguably under-specified rather than padded, so it earns its brevity but doesn't maximize the space.

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 no output schema and a required 'name' param undocumented in both schema and description, the definition leaves gaps. A 'direct references only' clause helps, but the return shape (callers/referrers list) is never described, so an agent must probe to learn the output.

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 80%, so the baseline is 3. The description implies the required 'name' parameter is a symbol ('who calls/uses X'), partially compensating for that parameter having no schema description, but adds no format or example detail beyond what the schema provides.

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 gives a specific verb-scope and resource: incoming dependencies, with the qualifier 'who calls/uses X' that makes the direction unambiguous. It implicitly contrasts with the outgoing-dependency sibling get_dependencies, though it never names it, so differentiation is inferable rather than 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 phrase 'direct references only' scopes the search to non-transitive references, which is a form of usage guidance. However, it offers no explicit when-to-use/when-not or alternatives (e.g. get_dependencies for the reverse direction, get_call_chain for transitive paths), leaving routing to 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: it reuses the project's declared checker (no new dependency) and that output is bounded with explicit truncation reporting.

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, purpose front-loaded, each carrying distinct information (what it returns, how it runs, when to use it). No filler or restated phrasing.

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 no output schema, the description usefully covers the return shape (grouped by file, mapped to symbol) and truncation behavior. It could say how to raise the bounds when output is truncated, but for a read-only diagnostic that 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 100%, so all six parameters are already documented, giving a baseline of 3. The description adds only marginal meaning ('runs the checker the project already declares'), which lightly contextualizes auto-detection but adds no format or syntax detail.

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?

States a specific verb and resource (type-checker errors) plus the output shape (grouped by file, mapped to enclosing symbol). This clearly distinguishes it from near-neighbors like get_git_status or run_impacted_tests, which report different things.

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 says to use it 'after an edit instead of shelling out to a build', which supplies both a trigger and an alternative. It does not state any when-not-to-use condition, so it falls just 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The description adds the useful fact that this is a composite/aggregated read rather than a single-resource fetch, but says nothing about cost, size limits, or truncation behavior of the bundle.

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?

A single front-loaded fragment with zero filler; the bundle contents are listed immediately. It is arguably too terse to stand alone, but no sentence is wasted.

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 read-only aggregator with no output schema and high schema coverage, the description adequately signals what comes back. The gaps are the alias-parameter semantics and any indication of bundle size or output shape, which are minor given the annotations.

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 83%, so the schema carries the parameter burden and baseline is 3. The description adds nothing about parameters, and notably does not clarify the name/symbol/symbol_name alias anyOf or how max_deps/max_callers shape the returned bundle.

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?

Names a specific artifact ('pre-edit bundle') and enumerates its five contents (source, direct deps, callers, same-file siblings, impacted tests), which is far more informative than a bare verb+resource. It distinguishes itself reasonably from siblings like find_impacted_test_files or get_dependencies, though it never explicitly says how it differs from get_full_context or get_change_impact.

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?

'Pre-edit' implies the trigger point (before making a change), but there is no explicit when/when-not statement and no named alternative. With get_full_context, get_change_impact and get_dependencies in the sibling set, the agent must guess which context-gathering tool to pick.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds real value by defining the scoring heuristic behind 'entry point', but says nothing about ordering of results or how scores are presented.

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?

A single front-loaded sentence with no filler; the enumeration of entry-point categories is dense and useful. It is arguably too terse for a scoring tool, but nothing is wasted.

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 no output schema, so the description carries the burden of explaining the return value; it implies scored functions but not the result shape or sort order. For a read-only heuristic tool with a fully documented schema this is adequate but leaves a real gap around output.

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 100% with only two parameters, both fully documented (project default, max_results default 20). The description adds no parameter semantics beyond the schema, so the baseline 3 applies.

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?

States a specific verb (score) and resource (functions by likelihood of being execution entry points), and enumerates the categories it recognizes: routes, handlers, main, exported APIs. That is clear enough to know what it returns, though it never explicitly distinguishes itself from siblings like get_functions or get_routes.

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?

No when-to-use guidance, no conditions, and no named alternatives. An agent must infer that this is for locating starting points rather than listing all functions, and cannot tell from the text why it should pick this over get_routes or get_functions.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds value by disclosing the search scope (three source types) and what the result reveals (defined/read/written locations), which goes beyond the 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?

Two tight sentences, zero filler. The scope is front-loaded in the first sentence and the return content follows immediately.

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 read-only query tool with full schema coverage and no output schema, the definition is nearly complete: it explains the scope and the nature of the output. It could note default project scoping or search limitations, but the schema already covers the project default.

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 100%, so all three parameters (project, var_name, max_results) are already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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?

States a specific verb (cross-reference) and resource (env var), and scopes the search across three concrete domains: code, .env files, and workflow configs. This distinguishes it from a generic config analyzer, but it never names or contrasts with the overlapping sibling 'analyze_config', so it stops short of full differentiation.

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 use case (locate where an env var is defined/read/written), so an agent can infer intent, but there is no explicit when-to-use guidance or exclusion relative to siblings like analyze_config or search_codebase.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so safety and side-effect profile is covered. The description adds that results include traced imports and role classification, useful output context, but says nothing about pagination, limits, or return shape.

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?

A single compact sentence with the key scope (keyword + traced imports) front-loaded. No wasted words, though it is a sentence fragment rather than a complete statement of 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?

With no output schema, the description carries return-value burden and does describe the shape (files + imports, classified by role). However, it omits how the keyword is matched and when to prefer it over search siblings, leaving a gap for a 3-param query 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?

Schema coverage is 67%; the description maps the 'feature keyword' to the required keyword param and hints at import tracing, but adds no format or syntax for project or max_results beyond what the schema supplies. Baseline 3 is appropriate.

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?

States a specific resource (files) and scope: files matching a feature keyword plus traced imports, with role classification. An agent can grasp the concept, though it doesn't explicitly differentiate from siblings like search_codebase or get_file_dependencies.

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?

No when-to-use guidance and no named alternatives among many overlapping siblings (search_codebase, find_symbol, get_file_dependencies). The agent must infer the scenario from the description alone.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's one contribution is defining 'dependencies' as file-level import edges, which distinguishes this from symbol-level relatives, but it discloses nothing about return shape, ordering, or recursion depth.

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?

A single front-loaded sentence with no filler; the direction qualifier arrives immediately. It is lean to the point of being undersized for the tool's role, but every word carries meaning.

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 no output schema, the description is the only place to explain what comes back, and it does not say whether results are paths, edge objects, or whether traversal is direct-only versus transitive. For a dependency-query tool sitting among several near-identical siblings, this leaves meaningful gaps.

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 100%, so project, file_path, and max_results are already fully documented. The description adds no parameter syntax, path semantics, or default behavior beyond what the schema provides, so the baseline 3 applies.

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 resource ('files imported by this file') and pins the direction with 'outgoing file-level import edges', which is the key ambiguity against siblings like get_file_dependents. It stops short of naming an alternative tool, so it is clear but not sibling-differentiating by name.

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?

There is no when-to-use statement, no exclusion, and no mention of the many overlapping siblings (get_imports, get_dependencies, get_file_dependents, find_import_cycles). The 'outgoing' qualifier is definitional rather than guiding, leaving selection entirely to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes only the scope detail that edges are file-level and incoming; it says nothing about truncation behavior despite a max_results parameter.

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?

A single front-loaded sentence with the core answer first and the parenthetical clarifying edge direction second. No words are wasted and there is no preamble.

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 read-only lookup with full annotation coverage and a fully described schema, the description identifies the return set adequately despite the absence of an output schema. It stops short of noting ordering, truncation, or empty-result behavior, which is a minor residual 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 100%, so all three parameters (project, file_path, max_results) are already documented in the schema, including the '0 = unlimited' default. The description adds no syntax, path-format, or defaulting detail beyond that, making the baseline 3 correct.

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 the returned resource and its direction precisely: 'Files that import this file (incoming file-level import edges).' That distinguishes it in spirit from the outgoing-edge sibling get_file_dependencies and the symbol-level get_dependents, but it never names those siblings explicitly, so the differentiation is inferential rather than stated.

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?

There is no when-to-use guidance, no mention of prerequisites such as the file being indexed, and no routing to the obvious alternatives (get_file_dependencies for outgoing edges, get_dependents for symbol-level callers). An agent must infer the choice from the name alone.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's contribution is the depth→content mapping, which is genuinely useful behavioral context but largely mirrors the depth parameter's own schema text, so it adds only modest value.

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?

A single front-loaded sentence with zero filler, though the telegraphic style ('Symbol bundle: location + source...') trades some clarity for brevity.

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 9-parameter tool with no output schema, the description is thin: it never addresses batch mode, the intent-ranking behavior, or what the bundle returns. The schema carries those details, so it is minimally viable rather than 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 100%, so the schema already documents mode, depth, intent, batch names, aliases and max_lines in detail. The description only restates the depth semantics, adding no syntax or format detail beyond the schema — baseline 3 applies.

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 composition (location + source + deps/dependents + change_impact) gated by depth, which is more specific than a tautology, but the shorthand 'location' is ambiguous and it does not distinguish this aggregate tool from the many sibling getters that supply the same pieces individually (get_function_source, get_dependencies, get_dependents, get_change_impact, get_edit_context).

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives. The depth parameter hints at escalating scope but the description never tells the agent when to reach for this bundle instead of the single-purpose sibling tools.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the file-vs-project scope but no further behavioral context (return shape, truncation semantics) beyond what the schema/annotations provide.

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?

A single front-loaded sentence with zero waste; the primary scoping distinction appears before the parenthetical detail.

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 read-only lister with 100% schema coverage and complete safety annotations, the definition is largely sufficient. Without an output schema, it could say what a function row contains, but that gap is minor for this tool class.

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 100% and every parameter is self-documented, so the schema carries the burden. The description only echoes file_path's scoping role already stated in the schema, adding no new syntax or meaning for hints, compress, project, or max_results.

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?

States a specific verb+resource ('List functions') and scopes it two ways: a single file via file_path, or project-wide. An agent can tell it is a lister rather than a source fetcher, but it does not name the contrasting sibling (get_function_source) explicitly.

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?

Usage is implied by the two scoping modes ('in a file ... or across the project'), which hints at when each applies. However, no explicit when-to-use/when-not guidance or alternatives (e.g. get_function_source for a single body) are 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds that lookup is symbol-based and path-free, which is useful context, but it omits notable behaviors such as batch mode, caching (force_full), and the level/hints output shaping.

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?

A single tight sentence with the key differentiator front-loaded and zero filler. It is efficient, though almost too terse relative to the tool's 10-parameter surface.

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 10 optional parameters and no output schema, the description covers only the single-symbol lookup path and never mentions batch mode ('names'), 'level', 'max_lines', or cache bypass. An agent cannot infer these capabilities from the description alone, leaving significant gaps.

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 80%, so most parameters are already documented. The description implies that 'name' drives lookup and file_path is unnecessary, but it adds no syntax, format, or relationship details (batch 'names', 'level', 'max_lines') beyond what the schema provides.

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?

States a specific verb+resource (retrieve full source of a function/method) and adds scope ('by name, no path needed'), which distinguishes it from whole-file reads. It does not explicitly differentiate from siblings like get_class_source or get_functions, so it falls short of a 5.

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?

'reads the symbol instead of the whole file' implies the use case (targeted symbol retrieval vs file-level reading) but names no explicit alternative (e.g. get_class_source, get_functions, read_lines) and gives no when-not guidance. Usage is implied rather than stated.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description's value-add is the field enumeration, which substitutes for the absent output schema but is not deep behavioral context (e.g., no mention of scope or working-directory assumptions).

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?

A single front-loaded sentence with zero filler; the return fields are listed compactly and every word carries 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?

For a simple read-only tool with full annotation coverage and a one-param schema, this is nearly complete; enumerating the returned fields compensates for the missing output schema. Only minor gaps (usage context) remain.

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?

Only one parameter and schema coverage is 100% – the schema already documents 'project' including its default. The description adds nothing beyond that, so the baseline 3 applies.

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?

States a specific verb+resource ('git status') and enumerates the returned fields (branch, ahead/behind, staged, unstaged, untracked), so an agent knows exactly what it produces. It doesn't differentiate from any sibling, but no sibling in the list overlaps with git status.

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?

No when-to-use, when-not-to-use, or alternative is given. The description only says what the tool returns, not when an agent should reach for it versus related tools like build_commit_summary or get_changed_symbols.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds nothing beyond that — truncation handling and defaults live in the schema, not the description — making this adequate but not value-adding.

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?

A single short sentence with zero waste and the key output fields front-loaded. It is efficient, though the extreme terseness leaves no room for the context that would make it more useful.

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 four optional params, no output schema, and annotations covering safety, the definition is minimally complete — the schema supplies defaults and filtering behavior. It stops short of explaining scope (whole project vs. file) or how results interact with truncation, leaving some inference to the agent.

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 100%, so project, compress, file_path and max_results are all documented in the schema itself (including the truncation marker and default semantics). The description contributes no additional parameter meaning, which is the expected baseline when the schema does the work.

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?

States a specific verb (List) and resource (imports) and even names the returned fields (module, names, line), so an agent knows exactly what comes back. It does not, however, differentiate itself from plausible siblings such as get_file_dependencies or find_import_cycles.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternative tools that also expose import information. The only routing signal is the file_path 'omit=all' note buried in the schema.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by enumerating the aggregated contents, which is useful for a summary tool, but it says nothing about cost, latency, or scope of aggregation (whole project vs. active project).

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?

A single compact sentence fragment that front-loads the resource ('Project overview') before the content list. No wasted words, though the telegraphic noun-list style sacrifices some readability.

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 no output schema, the description does the right thing by enumerating returned contents (counts, packages, top classes/functions, infra dirs), so return-value expectations are set. But in a 60+ tool set with multiple summary/stats siblings, it fails to establish when this tool is the right one, leaving a real gap for selection.

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 100% and the single 'project' parameter is fully documented in the schema, including its '(default: active)' behavior. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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?

States a specific resource ('project overview') and enumerates what it aggregates: file count, packages, top classes/functions, infra dirs. An agent understands the output shape. However, it does not distinguish itself from near-siblings like get_structure_summary or get_stats, which sound like they return overlapping structural summaries.

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?

There is no guidance on when to use this over get_structure_summary, get_stats, get_diagnostics, or discover_project_actions. No exclusions, no prerequisites, no alternatives named. The agent must infer usage purely from the tool name.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds the output fields, but says nothing about scanning behavior, recursion scope, or pagination that would enrich the agent's expectations.

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?

A single front-loaded sentence that names the verb, the project type, and the returned fields with zero filler.

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 two-optional-parameter read tool with full annotation coverage and no output schema, the description adequately covers purpose and return fields. Minor gaps remain around what 'type' and the routes-vs-pages distinction mean, but nothing blocks correct 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 100%, so both parameters ('project' with default active, 'max_results' with 0=all) are already documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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?

States a specific verb ('Detect') and resource ('API routes and pages in a Next.js App Router project') and even lists the returned fields (path, file, HTTP methods, type). Clear enough to distinguish, though no sibling overlaps this domain so explicit differentiation isn't demonstrated.

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 ('in a Next.js App Router project') but gives no when-to-use guidance, no prerequisites, and names no alternatives such as get_entry_points or list_files. An agent gets no routing signal about when this is the right tool.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not say whether category selection changes cost, whether results are cached/fresh, or whether project scoping affects output.

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?

It is short and front-loaded, but the second sentence is pure duplication of the schema enum and therefore does not earn its place. No wasted prose beyond that, but also no added value.

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?

This is a multi-mode dispatcher with four parameters and no output schema, so the description carries the burden of explaining the modes. It leaves every one of the nine categories undefined, so an agent cannot predict what any call returns.

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 100%, so the schema already documents project, category, context_type, and budget_tokens, giving a baseline of 3. The description merely re-lists the category enum values, which the schema already defines, and adds no per-category semantics (e.g., what tca or linucb report).

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?

"Unified stats dispatcher" largely restates the tool name (get_stats) without saying what statistics are produced, over what domain, or what each category means. The category list hints at breadth but none of the categories (tca, dcp, linucb, leiden, speculation, lattice) are explained, so an agent cannot tell what it will actually receive.

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?

No guidance on when to call this versus sibling reporting tools such as get_project_summary, get_diagnostics, or get_structure_summary, and no conditions distinguishing it from those. Only the default value of category is stated; the agent must infer all usage context.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the aggregation scope and the file-omitted behavior, but says nothing about output shape (names vs. full source, depth of detail), which matters for a summary tool with no output 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?

A single sentence with zero waste and the most important distinction (file vs. project scope) front-loaded. It is tight, though arguably too terse for the amount of sibling overlap it needs to resolve.

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 no output schema, the description should carry more of the burden of explaining what the summary actually returns. It enumerates the categories but not their form or granularity, and it leaves the relationship to the individual get_functions/get_classes/get_imports tools unexplained.

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 100%, so both parameters are already documented, including the 'omit for project-level summary' behavior that the description restates. No additional syntax, defaults, or path-format detail is added beyond what the schema provides.

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?

States a specific resource (file/project structure) and enumerates what it surfaces (functions, classes, imports, line counts), plus the scope switch when file is omitted. It does not distinguish itself from siblings like get_functions, get_classes, get_imports, or get_project_summary, which cover overlapping ground.

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 only usage cue is the parameter-driven 'or project-wide if file omitted', which is about scope rather than tool selection. With four closely related siblings (get_functions, get_classes, get_imports, get_project_summary), an agent gets no guidance on when this aggregate view beats calling the individual tools.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the mutation/safety profile is covered structurally. The description adds essentially nothing beyond that profile — it neither describes what happens to existing content, nor the before/after default, nor any project-scoping behavior.

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?

One sentence, front-loaded, with no filler — structurally clean. However, for a 9-parameter aliased mutation tool the size reflects under-specification rather than genuine conciseness.

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 accepts 9 parameters with a five-branch anyOf requirement structure and four aliases of content, and the description explains none of it. With no output schema and no annotation detail beyond hints, an agent is left guessing how to satisfy the required-argument branches and what position/project defaults do.

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 only 67%, and the description mentions no parameter explicitly. Half of the schema's own descriptions are Spanish-language alias notes (code/source/new_source = content), and key fields like symbol_name, content, and file_path have no description anywhere. The phrase 'before or after' loosely gestures at position and 'indexed symbol' at symbol_name, but the description does not compensate for the coverage gap or explain the anyOf alias pattern.

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 (Insert) and resource (content before or after an indexed symbol), which is enough to distinguish it from sibling editors like replace_symbol_source, edit_lines_in_symbol, and move_symbol. It does not explicitly name or route against those alternatives, so it stops short of a 5.

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?

There is no when-to-use guidance, no statement of prerequisites, and no reference to alternative tools. An agent must infer that this is the correct choice for inserting near a symbol simply from the name and one-line 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The word "indexed" adds a small but real signal that results come from a built index rather than the live filesystem (and may be stale), but no ordering, staleness, or pagination behavior is disclosed.

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