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

Annotations already declare readOnly, idempotent, and non-open-world, so the safety profile is covered. The description adds real context beyond that: the failure condition (errors if the repo is not enrolled) and a definition of what counts as drift.

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 dense sentences, front-loaded with the output definition and then the three invocation modes. No filler or redundant restatement of the tool name.

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

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

With no output schema, the description compensates by describing the returned content (added/removed/body-hash-changed files and symbols) and the error case. It stops short of describing output shape or ordering, but is adequate for a 5-param read 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 baseline is 3, but the description goes further by explaining the pairwise relationship of a+b, the standalone meaning of since, the default fallback with no parameters, and the session pinning modifier. That interaction logic is not fully captured by the per-property schema text.

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 computation (structural drift) and enumerates the exact output domain: files and symbols added, removed, or whose body hash changed. An agent can tell this apart from hash/structure siblings, though the description does not explicitly name when those siblings are preferable.

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?

Spells out three distinct calling modes: a+b diffs two snapshots, since=label diffs a labeled snapshot vs live code, and the default diffs latest snapshot vs live code. This is genuine mode-selection guidance, but it does not address when to reach for this tool over a sibling.

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 cover the safety profile (readOnly, idempotent, closed-world), so the description's job is to add beyond that. It does: determinism guarantees identical hashes across machines for identical code, and it discloses the failure mode (errors when the repo is not enrolled). It does not cover latency or hashing scope limits, but the added context is substantial.

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 tight sentences, front-loaded with what is returned before the usage guidance and the error condition. No sentence is 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?

There is no output schema, so the description carries the return-value burden and does so ('root hash + file count'), plus the determinism contract and the not-enrolled error. For a single-param, read-only tool, nothing needed to call it correctly is missing.

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

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

Only one parameter, fully documented in the schema (100% coverage), so the schema does the heavy lifting. The description only implicitly clarifies that `repo` must be enrolled ('an enrolled repo', 'Errors if the repo is not enrolled'), adding marginal value over the schema's 'name of an enrolled repo'.

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: computes a deterministic root hash plus file count for an enrolled repo's current code. It also names the sibling it relates to (`status`'s stored hash), so an agent can distinguish it from `diff`, `structure`, `health`, or `locate`.

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 explicit when-to-use conditions: to confirm two machines/checkouts hold identical code, or that code changed since a stored hash. It also names the alternative source of comparison (`status`'s latest stored hash), which is exactly the routing information an agent needs.

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 the safety profile is covered. The description adds real value by enumerating the returned fields (schema version, integrity, enrolled repos, db path) even though there is no output schema, and confirms it takes no arguments.

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 resource scope, then the usage routing. Every clause carries information; no 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 parameterless read-only diagnostic tool with no output schema, the description is complete: it says what it checks, what it returns, when to use it, and which sibling to use instead.

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 is nothing for the description to disambiguate beyond confirming 'Takes no arguments,' which matches the empty schema. Baseline 4 applies for a no-parameter tool.

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 ('Store-wide health') and enumerates exactly what it reports: schema version, integrity check, enrolled repo names and count, db path. It also explicitly distinguishes itself from the sibling `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?

Gives explicit when-to-use ('check the store itself is sound... or to list what is enrolled') and names the alternative with its condition ('for one repo's freshness use `status`'). Nothing is left 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 closed-world, so safety is covered. The description still adds real behavioral context beyond them: determinism from the live AST, that a zero-match result is definitive, that unfiltered results are capped and paginated, and that the default kind set is func+class. It stops short of detailing result size or latency, but that is a minor gap.

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

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

Front-loaded: the core operation (name → file:line) comes first, then parameter behavior, then the verification rationale. It is dense but nearly every clause carries information; the grep contrast runs slightly long, keeping it just under 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 no output schema, the description carries the return-value burden and does so: it specifies the file:line plus short body hash output and the next_offset pagination contract. For a read-only, four-parameter lookup tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: a named lookup ignores the kind narrowing and searches every kind, and the unfiltered list defaults to functions+classes. It also reinforces the capped/paginated behavior of `offset`, which is genuinely useful for interpreting 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 precise verb+resource: deterministically locate symbols in an enrolled repo, returning name → file:line plus a body hash. It distinguishes itself from grep explicitly and from siblings like hash/structure/diff by emphasizing deterministic AST-parsed lookup. An agent can identify exactly what this tool produces 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?

Gives explicit conditional usage: pass `symbol` for a named lookup that searches every kind, omit it to list all with pagination. It also states the purpose-level trigger (verify a symbol exists before claiming it does) and contrasts with the grep alternative, which is exactly the routing guidance an agent needs.

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 only declare readOnly/idempotent/openWorld=false, so the burden is on the text, and it delivers: it discloses the error condition (repo not enrolled), explains that coverage below 100% means files other tools never see, and clarifies that the file cap affects live-parse tools while staleness does not. That is real behavioral context beyond the annotations rather than a restatement of them.

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-loaded with the payload of returned fields, then the decision guidance. It is information-dense and every clause is load-bearing, though the middle sentence is long enough that a reader must parse it carefully rather than skimming.

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 enumerates the returned fields so the agent knows what to expect, and it covers the error case plus cross-tool implications for diff, structure, locate and health. Nothing needed to call this single-parameter, read-only tool correctly is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains that `repo` names an enrolled repo. The description reinforces this indirectly via the 'not enrolled' error but adds no format or naming detail beyond the schema, making the baseline 3 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+resource combination (per-repo index health) and enumerates exactly what it reports: last indexed, staleness, parse errors, coverage %, snapshot count, hash, file cap. It explicitly distinguishes the repo-scoped tool from its sibling `health`, which covers the store as a whole, so an agent can pick the right one 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?

Gives explicit when-to-use guidance tied to concrete decisions: judge the stored index that `diff`'s default baseline and the guard read from, check coverage before trusting a `structure`/`locate` miss. It also states when NOT to worry (staleness doesn't affect live parse tools, but the file cap does) and names the alternative (`health`) for store-wide questions.

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 the safety profile (read-only, idempotent, closed-world), so the bar is lower. The description adds real value beyond them: determinism, the ~2.5x token cost of `hashes`, and the important caveat that the `doc` field is the one field NOT verified against the code.

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 tight sentences, front-loaded with the purpose and followed by usage and scoping. Dense but every clause carries information; no filler or restated title.

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 sketches the return shape (files + per-file symbols with name/kind/line, refs, hashes) and the cost implications of each level. That is nearly enough for correct invocation, though exact response nesting is left implicit.

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 the baseline is 3, but the description reinforces the cost/verbosity tradeoff across `detail` levels and the glob semantics of `paths` ('`**` matches across directories'), which is meaning an agent can act on when choosing arguments.

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: a deterministic files+symbols structure of an enrolled repo's current code, which an agent can distinguish from mutation or diff tools. It does not explicitly name siblings (hash/diff/status) as things this is *not*, but the scope is concrete and unambiguous.

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

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

Gives a clear when-to-use: 'ground claims about what functions/types/exports exist', plus scoping advice (paths globs) and guidance on selecting a detail level. It even routes a sub-case away ('body-level drift, which hash/diff/status answer far more cheaply'), but stops short of stating when not to use this tool at all.

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