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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered structurally. The description adds the non-obvious fact that results are compressed (and that a token budget applies), but says nothing about irreversibility, confirmation needs, or what happens when the target tool 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?

Two short sentences with no padding, but the cryptic bracketed notation and unexplained 'compressed' term trade clarity for brevity rather than earning it. Front-loading the mutation semantics is correct.

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 open-world dispatcher with a nested arguments object and no output schema, the description omits argument forwarding, error behavior, and compression/budget semantics. An agent cannot reliably call this without inspecting atr_find_tools or guessing.

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%, and only the budget parameter is documented in the schema. The description never explains that 'tool' expects a name from atr_find_tools or that the nested 'arguments' object is forwarded as the target tool's arguments — the single most important thing to know for this dispatcher.

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 tool dispatches another tool that mutates state, which distinguishes it from atr_read in principle. But 'Run a tool that changes something' is loose, and the '[w] in atr_find_tools' notation is unexplained jargon an agent must guess at.

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

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

It hints that mutation targets come from atr_find_tools marked [w], but never states when to use this versus atr_read, atr_run, or atr_query. There are no explicit exclusions or decision criteria despite nine siblings.

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?

While annotations confirm safety (readOnlyHint: true), the description adds critical behavioral details beyond the structured data, such as its output format ('1 line of context') and specific filtering behavior for non-source files ('lockfiles/generated/binary files listed but not shown').

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

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

The description is extremely concise and efficient. It manages to convey the core function, formatting constraints, and usage context in a single, punchy sentence.

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

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

Given the tool's function as a specialized git diff utility, the description is highly complete. It addresses both the functional behavior and the constraints (like context lines and file type filtering).

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?

With 80% schema coverage, the input parameters are mostly well-defined in the schema itself. The description focuses heavily on behavioral context (the diff output style and scope) rather than defining individual parameters.

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

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

The description clearly defines the tool's purpose as performing a 'compact git diff'. It distinguishes itself by specifying formatting constraints (1 line of context) and explicitly stating its intended role (Use instead of `git diff`).

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

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

The description provides clear guidance on usage by defining the default state ('Default: uncommitted changes') and explicitly directing the user to replace the standard 'git diff' command with this 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?

The annotations already establish that this is a non-destructive, read-only, non-open-world operation. The description adds scope (connected servers) and return format details (compact signatures with * marking required parameters), but does not cover rate limits, pagination, or other behavioral context.

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

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

Two short sentences with no wasted words, and the main purpose is front-loaded. The return-format note is compact and 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?

Given that the schema is fully documented and annotations cover safety, the description is nearly complete for this simple discovery tool. It could better explain how the tool relates to atr_call or what 'compact signatures' look like, but it gives enough context to invoke and interpret results.

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 parameter semantics are adequately documented in the schema itself. The description does not add meaningful detail about query, k, or detail beyond what is already structured.

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

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

The description states a specific verb and resource: finding tools on connected servers for a task. It is clear enough to distinguish discovery from execution tools like atr_call, but it does not explicitly name or differentiate itself from any sibling.

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 'for a task' implies the discovery use case, but the description does not say when to use this instead of atr_call or other siblings. No explicit prerequisites, exclusions, or alternatives are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description is consistent and adds that it reads 'part of a stashed result,' but it does not disclose behavior around invalid refs, pagination, or result size.

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

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

The description is compact and front-loaded, with clear Data/Text labels. The fragmentary style is efficient but slightly cryptic, which keeps it from being a perfect 5 on structure.

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

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

For an eight-parameter tool with only 25% schema coverage and no output schema, the description is too thin. It omits pagination semantics (limit/offset), ref behavior, group_by details, and sibling differentiation from atr_read.

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 only 25%, so the description must compensate. It names five of eight parameters and categorizes them as data-oriented (path, where, fields, group_by) or text-oriented (search regex), but it leaves limit, offset, ref, and group_by semantics unexplained.

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

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

The description states a specific verb and resource: 'Read part of a stashed result by ref.' That is clear enough to distinguish it from generic read tools, but it does not explicitly differentiate it from the sibling atr_read, which likely also reads stashed results.

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 'Data: path/where/fields/group_by' and 'Text: search (regex)' labels imply how to choose parameters for structured vs. text queries. However, there is no explicit guidance on when to use this tool instead of atr_read or atr_search_code, and no exclusions are 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior — results are compressed and large ones are stashed — but leaves the critical follow-up unexplained: how or where an agent retrieves a stashed result.

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 compact clauses with no filler, and the read-only constraint plus the atr_find_tools pointer come first. It is arguably over-terse given the tool's dispatch complexity, 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?

With a nested 'arguments' object, a low parameter coverage, and no output schema, the description carries most of the burden and falls short. It never explains how arguments are forwarded, what the compressed result looks like, or how to unpack a stashed result, all of which an agent needs to use this dispatch tool correctly.

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

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

Schema description coverage is only 33%: only 'budget' is documented. The description adds no meaning for 'tool' (presumably a tool name from atr_find_tools) or for the nested 'arguments' object, which is almost certainly a pass-through payload to the target tool — a semantics gap with real invocation consequences.

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: it runs a read-only tool (marked [r] in atr_find_tools), returning compressed results. This distinguishes it from atr_find_tools, but it never contrasts itself with atr_call, atr_query, or other siblings that an agent might pick instead.

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 '([r] in atr_find_tools)' implies a discover-then-read workflow, but the description never states when to use atr_read versus atr_call (presumably for write tools) or atr_query. Usage is inferable from the sibling naming convention 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 establish read-only, non-destructive, closed-world behavior. Beyond that, the description usefully discloses the non-obvious default that large code files may return an outline instead of full text when only a path is supplied.

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 written sentences front-load the main action and key usage modes. There is no redundant restatement of annotations or schema details.

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

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

The description covers the core read behavior, partial-read modes, and outline fallback, which are the main things an agent needs. Without an output schema, it could say more about return formats and the undocumented budget parameter, but overall it is sufficiently 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 67%, and the description adds meaning for lines, search, and the path-only outline behavior. It still leaves budget undocumented in both schema and description, and context is only explained in 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?

The description states a specific verb and resource: read part of a local file. It clarifies scope through lines/search/outline behavior, but it does not explicitly differentiate this tool from sibling file-search or read tools such as atr_read or atr_search_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?

It gives practical usage hints, such as passing lines from a search hit or using search to narrow results. However, it does not state when to use this tool versus siblings like atr_read, atr_search_code, or atr_query, nor does it give explicit exclusions.

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, openWorldHint:false, and destructiveHint:false, so safety is fully covered structurally. The description adds no behavioral context of its own — nothing about output size, truncation, or what the budget parameter does to the result. With annotations doing the work, this is adequate but thin.

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, zero waste, with the highest-value routing cue ('Start here') placed where the agent will see it. Nothing extraneous to trim.

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 tool with no output schema, the description covers purpose and entry-point role but leaves the result shape vague (tree? flat list? per-file) and the budget parameter unexplained. An agent knows when to call it but not what it will get back or how to size the response.

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 50%: 'path' is documented in the schema, but 'budget' has no description anywhere. That is the single most consequential parameter here (it presumably controls output volume for a tool that returns an entire repo layout), and the description never mentions it, 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 resource and payload: 'Project layout with each code file's top-level functions/classes.' An agent can distinguish it from atr_read_file or atr_search_code because it declares structure-level (symbol outline) output rather than raw file contents. Lacks an explicit verb and no sibling is named, 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?

'Start here in a codebase' is an explicit routing instruction that tells the agent this is the entry point before drilling into files. It gives clear positive context but contains no exclusions — nothing says to prefer atr_search_code when the agent already knows the symbol 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 flag this as open-world and destructive, and "run a shell command" is consistent with that. The description adds genuinely new behavioral context — that output is filtered so only failures are kept — but omits that arbitrary commands execute with side effects, that output may be lossy, and how the compression budget behaves.

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 use-case examples and the output guarantee are both packed in, and nothing is 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?

For an open-world command executor with no output schema, the description does well to characterize the returned output. But with a destructive, side-effecting tool and an entirely undocumented `budget` parameter, an agent still lacks enough to call it confidently or predict the full 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 coverage is only 50%: `cwd` and `timeout` are documented in the schema, but `command` and especially `budget` are bare. The description never explains what `budget` controls, even though "compressed output" strongly implies it caps the returned size — the one place the description could have added real value.

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?

"Run a shell command" is a specific verb+resource, and the parenthetical (tests, build, lint) plus "compressed output: failures kept, noise cut" tells the agent exactly what it gets back. It is clearly distinct from every sibling (read/find/query/diff/stats tools), though it never says so 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?

The examples (tests, build, lint) imply the intended context, but there is no explicit when-to-use vs. when-not, no mention of the sibling tools it might be confused with, and no guidance on when to prefer atr_read_file or atr_search_code over shelling out.

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

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

Annotations already declare readOnlyHint and non-destructive, so the description doesn't need to re-establish safety. It adds real value by disclosing the output shape (grouped by file, path:line: text) and how context expands results, though it says nothing about regex dialect, match limits, or what budget does.

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 with the primary action and the read-avoidance rationale front-loaded; every clause carries information an agent needs.

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?

Covers purpose, output format, and the key context tactic despite there being no output schema. The main gap is the undocumented budget parameter and any hint about result caps or regex flavor.

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 60%; 'Regex' clarifies that pattern is a regular expression rather than a literal string, which is useful. The context explanation largely restates the schema text, and budget has no description in either place.

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 where something is defined or used. The phrase 'before reading any file' implicitly contrasts it with atr_read/atr_read_file, but no sibling is named directly, so differentiation is inferred 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?

'before reading any file' gives clear situational guidance and 'often enough to answer' tells the agent it may not need a follow-up read. No explicit exclusions or alternatives are named beyond that implication.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description does add one useful non-obvious fact — that the figures are scoped to the current session rather than lifetime totals — but it says nothing about units, aggregation window, or whether the value resets.

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 no filler, and the session scoping is stated immediately. It is slightly under-specified rather than padded, with undefined jargon (ATR) consuming part of an already tiny budget.

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 no-param, read-only counter this is close to sufficient, especially since annotations carry the safety profile. However, no output schema exists and the description doesn't indicate the shape of the result (a single number, a breakdown by tool, units), leaving the agent guessing about the return value.

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

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

The tool takes zero parameters, so there are no parameter semantics to document and the baseline is 4. Nothing in the description contradicts or confuses the empty 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?

The description names the reported resource (tokens saved) and the scope (this session), but it is a noun phrase with no verb and never explains what "ATR" is, so an agent must infer that this is a session-metrics reporting tool. It also does nothing to separate it from siblings such as atr_query or atr_run, which could plausibly return stats too.

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, when not to, or which sibling to use instead. The only hint is the phrase "in this session", which implies scope but not a selection rule.

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