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

With NO annotations present, the description carries the full safety burden and delivers richly. It's transparent about behavior: it SURFACES signature+docs as 'inline context' (leaving judgment to the agent), it ASSERTS a `deprecated` verdict only when docs mark it, and it explicitly lists error/edge statuses (`NoOracleRun` / `NoExternalSymbols`). Most notably, it proactively discloses a potential misconception by stating it does NOT handle arity or drift checks and explains the reason ('not instrumented / needs a cross-version baseline').

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?

Structurally dense with zero wasted words. The multi-sentence description front-loads the core purpose, uses parentheticals to pack secondary details, and leverages bold/uppercase formatting effectively. Every clause earns its place (e.g., '(judge arity / misuse yourself)' is a compact, high-value instruction). It's information-dense but easily skimmable.

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, filterable tool with no output schema and a fully-documented parameter set, the description is exceptionally complete. It covers the key user-facing details: call context (external symbols), filtering, output semantics (deprecated verdict), and preconditions (oracle run). The worktree caveat is a nice touch that saves a user from confusion about which index the tool reads from. The explicit non-coverage of arity/drift is exactly the kind of boundary definition that prevents LLM confusion. I can't identify a meaningful gap for a tool of this scope.

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 good inline docs for each parameter. The description adds value by conceptualizing them (`Filter by path, package, deprecated_only`), and it clarifies the return semantics (`limit` vs summary counts) that isn't obvious from the schema. It doesn't deeply re-explain each parameter but correctly treats the schema as authoritative, using the description solely to illuminate the filtering access 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?

Vividly clear: 'Dependency-contract check for the code's EXTERNAL library calls, from the SCIP oracle's external symbol info' immediately establishes the specific verb (check), resource (external library calls), and scope (vs. internal call graph). It explicitly names what it does NOT assert (arity or removed/renamed drift), effectively distinguishing itself from siblings like `find_callers` or `trace_callees`. This goes beyond a generic restatement of 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 description weaves in critical usage guidance: filter options (`path`, `package`, `deprecated_only`), the `oracle run` prerequisite, and explicit non-goals ('To filter by user/workspace, use search_calls_extensive' style contrast is absent, but it clearly warns about what it does NOT do (arity checks) which a user might otherwise assume). A clear when/why-not is implied rather than contrasted against a specific sibling by name, hence a 4.

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

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

No annotations are provided, so the description carries the full burden. It discloses return values (candidate class or null) and conditions, but omits details on error handling, precedence of parameters, or whether it is a read-only operation. It adds some transparency but not comprehensive coverage.

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

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

A single sentence that front-loads the purpose and includes all key conditions. Zero wasted words; every phrase contributes to understanding the tool's behavior.

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 no output schema, the description explains the return type (candidate class or null) and conditions. However, it does not describe the structure of the candidate class, parameter interaction details, or edge cases. Adequate for a simple tool but leaves gaps given five parameters.

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 20%, so the description must compensate. It mentions id, ref, and path+line as input forms, giving meaning to four parameters, but does not explain how they relate (alternatives vs combined) or the worktree parameter. Partial compensation for the low schema coverage.

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

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

The description clearly states the tool returns the clone class for a symbol, specifying input forms (id/ref/path+line) and conditions (fingerprinted, has siblings). It distinguishes from sibling tools like find_clones by focusing on a single class result, but does not explicitly contrast 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 guidance on when to use this tool versus alternatives like find_clones, nor exclusions. The description implies usage (for getting a clone class of a symbol) but offers no context about prerequisites or comparisons.

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

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

With no annotations, the description carries the transparency burden. 'Full-text search' strongly implies a read-only operation, and 'historical commit subjects and bodies' clarifies scope, but the description does not disclose ordering, result shape, limitations, or behavior around options like include and worktree. It is minimally transparent but not rich.

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

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

The description is two concise sentences with the main verb and object front-loaded. Every word contributes to clarifying the tool's purpose, and there is no filler or repetition.

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

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

The description is adequate for core invocation since query is the only required parameter and the rest have defaults. However, with seven parameters, no output schema, no annotations, and low schema coverage, the description leaves several behavioral and selection-relevant details unexplained, especially relative to many sibling search and commit-related 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 description coverage is only 29%, and the description only adds meaning for the query parameter by framing it as a keyword. It does not help with limit, explain, include, worktree, graph_limit, or include_graph, all of which require inference from names or schema defaults.

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 identifies the action as full-text search over historical commit subjects and bodies and ties it to the use case 'find when/why something changed by keyword.' It is specific about resource and scope, though it does not explicitly contrast with sibling search tools like semantic_search or rationale_search.

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 tool versus alternatives such as semantic_search, rationale_search, commits_touching_query, or git_history_for_path. The phrase 'find when/why something changed by keyword' implies a use case, but no exclusions or alternative recommendations 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?

No annotations are provided, so the description carries the burden. It mentions combining evidence but does not disclose behavioral traits like whether it performs read-only operations, potential side effects, or performance implications. It adds some context about the query scope but lacks depth for a complex tool.

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

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

The description is a single sentence that is concise and front-loaded with the core purpose. It earns its place by explaining the combination of evidence types, though it could be slightly more structured with a second sentence for usage context.

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

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

Given the tool's complexity (7 parameters, no output schema, no annotations), the description is minimal. It does not explain return values, pagination, or how the graph modes affect output. The schema provides some parameter details, but the description leaves gaps for a tool that likely returns complex 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 only 29%, so the description should compensate. It does not explain parameters beyond the schema, but the schema itself has descriptions for 'include' and 'worktree'. The description adds no additional parameter semantics, so it relies on the schema, which is partially covered.

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

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

The description clearly states the tool combines commit-message matches with file-change evidence for a query, which is a specific verb+resource+scope. It distinguishes from siblings like commit_search and semantic_search by emphasizing the combination of messages and file changes, though it doesn't explicitly name alternatives.

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 for 'what work relates to X?' but does not explicitly state when to use this tool versus alternatives like commit_search or semantic_search. It provides a clear context but lacks explicit exclusions or alternative guidance.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the prerequisite oracle data, the no-data behavior (reports nothing), and the diagnostic nature of the tool. It doesn't discuss side effects, but the tool is framed as a read-only cross-check/report.

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: it states the core action and resource in the first clause, then adds prerequisite and edge-case behavior. Every sentence contributes necessary information without redundancy.

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

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

Given the tool has one well-documented parameter, no annotations, and no output schema, the description covers purpose, prerequisite, and empty-result behavior. It could mention the return format or ordering of edges, but for a diagnostic tool the description is adequately 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% for the single worktree parameter, and the schema already explains absolute path, linked worktree overlay, default behavior, and silent ignoring of non-linked paths. The tool 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?

The description uses a specific verb ('Cross-check') and names the exact resources involved (tree-sitter graph vs SCIP compiler oracle). It also states what the tool reports (edges where they disagree on callee resolution), which clearly distinguishes it from sibling tools like compare_graph_to_text.

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

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

The description gives clear usage context: it's a resolver-debugging diagnostic and requires 'rag-rat oracle run' to have been executed first. It does not explicitly name alternative tools or exclusions, but the intended scenario is evident.

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

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

With no annotations provided, the description bears full responsibility for behavioral disclosure. It describes the tool's action (cross-checking, surfacing, flagging) but does not clarify side effects, auth requirements, rate limits, or whether it is a read-only operation. The description is partially informative but lacks important behavioral context.

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

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

The description is composed of two concise, front-loaded sentences. The first sentence captures the core functionality, and the second provides usage guidance. No redundant or filler content.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers only the core concept and usage hint. It omits details about return format, parameter meanings, and prerequisites, leaving significant gaps for an agent to use it correctly.

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

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

Schema description coverage is only 11%, meaning the description should compensate by explaining key parameters. However, the description does not mention any parameters except implicitly 'regex text search' (which relates to 'pattern'). Parameters like 'symbol', 'include', 'edge_kinds' remain unexplained, relying on the sparse schema descriptions.

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

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

The description uses specific verbs ('cross-check', 'surfaces', 'flags') and resources ('graph caller edges', 'regex text search of indexed source'), clearly distinguishing the tool from siblings like compare_graph_to_scip. The purpose is immediately clear: compare graph edges to text search to find missed call sites and false edges.

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

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

The description explicitly advises using the tool 'when you suspect graph coverage gaps', providing a clear use case. However, it does not mention when not to use or suggest alternatives like compare_graph_to_scip, which could be a similar tool for SCIP-based comparison.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions a preference for local context but does not explain what that means, nor does it describe side effects, permissions, or return formats (no output schema). The lack of detail leaves the agent uninformed about how the tool behaves beyond the vague preference.

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

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

The description is a single, front-loaded sentence with no wasted words. However, it is overly terse and sacrifices critical content for brevity. It is concise but not appropriately structured for a tool of this complexity.

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 9 parameters, no output schema, and no annotations, the description is drastically insufficient. It does not explain how to specify the symbol, what the limit or include flags do, what edge_kinds and resolution mean, or what the returned documentation looks like. This is a severe gap for a tool with such rich schema.

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 22%, and the description adds minimal meaning beyond the schema. It implies the 'symbol' parameter but does not clarify the roles of id, ref, limit, include, worktree, edge_kinds, resolution, or allow_ambiguous. With 9 parameters, the description must compensate for the low schema coverage but fails to do so.

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

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

The description clearly states the tool finds documentation for a symbol, specifying it covers markdown chunks and doc comments. The phrase 'preferring local context before broad docs' adds a scoping nuance. It distinguishes itself from sibling tools like memory_for_symbol or symbol_lookup by focusing on documentation retrieval.

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 explicit guidance on when to use this tool versus alternatives. It does not mention other tools like memory_for_symbol or find_callers, nor does it provide exclusions or prerequisites. The 'preferring local context' note is about internal behavior, not usage selection.

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

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

With no annotations, the description carries full burden and does exceptionally well. It discloses that the tool recomputes findings on each call (implying side effects), explicitly excludes the model/compaction passes, clarifies that persisted findings from prior runs still surface, and mentions the stable `id` for review. This gives the agent a clear picture of behavior and side effects.

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 well-structured and front-loaded with the core return value, but it's slightly verbose with the 'pull surface' metaphor and a bit of redundancy between 'deterministic' and 'Recomputes the deterministic findings'. Still, every sentence adds meaningful context, so it earns a 4 rather than 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?

The tool has no output schema and no annotations, so the description must explain return value, behavior, and limitations. It covers the worklist composition (coverage gaps + stale references), ranking, stable IDs, the recompute side effect, the exclusion of model passes, and the fact that prior persisted findings surface. It also points to dream_review for follow-up, making it complete for an agent to decide when to invoke.

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 description is not required to explain parameters. The description adds no parameter-specific semantics beyond the schema, which already covers `all` and `limit` with descriptions. 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?

The description clearly states the tool returns a deterministic memory-maintenance worklist of coverage gaps and stale references, ranked with stable IDs. It distinguishes itself from the sibling tool dream_review by pointing to it for reviewing findings, and differentiates from the broader read/memory tools.

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

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

The description explicitly identifies this as the 'pull surface' for burning down the worklist, explains it recomputes deterministic findings on each call, and clearly states it does NOT run the opt-in model verdict/compaction passes (those stay on CLI/cron). It also directs users to dream_review for reviewing findings, providing clear when-to-use and alternative 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?

No annotations provided, so description carries full burden. Discloses that tool applies a human verdict (write/mutation), that the verdict survives future dream runs, and explains each verdict's effect. Does not explicitly state it's a write operation, but clear enough.

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 concise sentences with no fluff. Front-loaded with the core action. Each sentence earns its place.

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

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

For a simple tool with 2 params and no output schema, description covers purpose, usage, persistence, and relationship to dream. Could mention return value but not essential for correct usage.

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

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

Schema coverage is 100%, baseline 3. Description adds value: explains finding id can be a prefix, summarizes verdicts with context (e.g., 'clear a prior accept/dismiss' for reset). Adds clarity beyond schema descriptions.

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?

Clearly states the verb 'apply', specific resource 'dream finding' by id, and the three verdicts accept/dismiss/reset. Distinguishes from sibling 'dream' by noting 'Dream only proposes; this is how the reviewer confirms.'

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

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

Provides explicit context: 'Dream only proposes; this is how the reviewer confirms.' Implies usage after dream runs. Mentions verdict persistence. Does not explicitly state when not to use, but context is clear. Reference to CLI command helps.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains the detection mechanism ('detected by path') and the key edge case ('Empty in repos without FFI'). It could further describe output format or ordering, but the essential behavioral traits are disclosed.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the action, scope, detection heuristic, and an important empty-result caveat in under 25 words.

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

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

For a simple read/search tool with no output schema, the description explains what is returned and the empty-case behavior. The worktree parameter semantics are covered in the schema, and the tool's scope is narrow. A fully complete description might also describe result shape or ordering, but the current level is sufficient for selection and basic 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?

The description adds no meaning to the parameters. Schema coverage is 50%: 'worktree' is well documented in the schema, but 'limit' has no description and the tool description does not mention either parameter. The description misses an opportunity to clarify how 'limit' affects results or how 'detected by path' relates to the worktree scope.

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

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

The description uses a specific verb ('Find') and identifies a well-scoped resource ('the FFI surface') while enumerating exact constituents: '#[uniffi::export] items, exported impl members, and generated binding artifacts (detected by path)'. It clearly differentiates this from sibling tools like symbol_lookup or impact_surface by describing a distinctive FFI-specific surface.

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

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

The description gives clear context: it is for locating FFI-related declarations and artifacts, and it notes that results are empty in repositories without FFI. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the intended use case is clear.

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

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

No annotations are provided, but the description explains what the tool returns (call sites with confidence, completeness risk, repo memories) and notes synthesized dispatch edges. It also describes the worktree parameter's behavior (silent ignoring). Does not explicitly state side effects, but as a query tool this is largely covered.

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

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

The description is three sentences and information-dense, covering key behaviors, alternatives, and edge cases. It is slightly long but not wasteful; every sentence adds 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?

No output schema exists, so the description must explain return content. It mentions call sites with confidence, completeness risk, repo memories, and dispatch edges. Covers worktree behavior. Reasonably complete for a query tool, though it could clarify the exact return structure.

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 low (22%), with only worktree and include having descriptions. The text mentions resolving symbols and include flags, but many parameters (id, ref, limit, edge_kinds, resolution, allow_ambiguous) lack explanation. The description adds some meaning but not enough to fully compensate for the schema gaps.

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

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

The description clearly states the tool's purpose: 'Find what calls a symbol (reverse call graph)' with a specific verb and resource, and distinguishes it from grep-based approaches. It is unambiguous and differentiates from sibling tools like trace_callees.

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 explicitly says 'instead of grepping for call sites' and advises resolving ambiguous symbols with symbol_lookup first, giving clear when-to-use and alternative guidance. Also mentions include/edge options and worktree scoping.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses the ROI sorting formula, the unrefined-vs-refined semantics, the cap/clamping behavior, the completeness provenance block, and input validation ([0.5,1.0], out-of-range rejection). This is rich behavioral disclosure for a search tool; only missing details like auth or error behavior, which are less critical here.

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

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

The description is a dense paragraph of about 70 words with zero fluff — every sentence earns its place (sorting, provenance, validation, cap behavior). It's front-loaded with the primary purpose. It could benefit from structural separation of the parameter constraints, but the information density is high and well-ordered.

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 4 well-documented params (100% schema coverage) and no annotations, the description covers the key behavioral gaps: return semantics without an output schema (ROI sort, provenance block, refine budget field). It's reasonably complete for a search tool that requires no parameters and has no output schema — the main omission is explicit differentiation from clones_for_symbol.

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 schema already fully documents all four parameters (limit cap, worktree fallback behavior, min_copies default, min_similarity range). The description mostly restates this (limit clamped at 50, min_similarity range/default) while adding only the ROI context and the completeness.refine_budget_clamped field. That's marginal added value over the schema, matching the baseline 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?

The description clearly states the tool returns ranked candidate clone classes sorted by ROI, with a completeness provenance block. It's a specific verb+resource (return/find clone classes) with quantifiable scope. It distinguishes implicitly from the sibling clones_for_symbol (global vs per-symbol) but does not name the distinction explicitly, 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?

The description gives substantial procedural context: the limit cap at 50, the refine budget behavior, and the min_similarity range enforcement. However, it provides no explicit when-to-use vs alternatives guidance, no exclusions, and never contrasts with the obvious sibling clones_for_symbol — so the tool-selection guidance is missing.

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

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

With no annotations, the description carries the burden. It discloses 'computed lazily and cached' and 'hash-bound', but doesn't mention read-only nature, potential cost, or what happens on missing chunk. It's some transparency but not comprehensive.

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 purpose. Loses a point for being slightly vague in wording (hash-bound, lazily) but overall efficient.

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?

Tool is simple (2 params, 1 required), but no output schema and description doesn't explain return format or caching lifetime. Meets minimal bar but has 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 has 50% coverage (worktree has a description). The description doesn't explain chunk_id beyond 'one chunk'. Baseline 3 for high coverage, but here coverage is 50% and description adds nothing about params, so it's below baseline.

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

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

The description clearly states the verb+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?

The description implies it is for a single chunk via 'for one chunk', but gives no guidance on when to prefer this over other tools like git_history_for_path or commit_search, and no mention of exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It conveys read-only intent via 'List' and specifies ordering (newest first) and returned fields, but does not mention side effects (non-destructive), error behavior, or permission requirements. For a simple read operation, this is adequate but not rich.

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

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

The description is a single, compact sentence that delivers the core functionality without redundant words. It front-loads the purpose and key details, exemplifying 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?

For a tool with 3 parameters and no output schema, the description is brief but covers primary purpose, ordering, and output highlights. It does not elaborate on output structure, pagination, or edge cases, leaving room for ambiguity. Adequate for a simple listing tool but not comprehensive.

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 33% (only worktree is described). The description only references 'path' vaguely as 'current path' and does not explain the limit parameter, its default, or the worktree parameter beyond the schema. It adds minimal value for the undocumented parameters, failing to compensate for the low coverage.

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

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

The description uses a specific verb 'List' and resource 'commits' with clear scoping to 'a current path', and notes ordering and output content (additions/deletions, subjects). It clearly distinguishes from siblings like git_history_for_symbol, which targets symbols rather than paths.

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 for path-based commit history, providing clear context about what it does. It does not explicitly state when not to use it or mention alternatives, but the sibling names (git_history_for_symbol, commits_touching_query) suggest differentiation. Lacks explicit exclusion clauses but has a clear 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?

No annotations are present, so the description must fully disclose behavior. It mentions the two-step process (resolve symbol, list commits) but omits critical behaviors such as read-only status, error handling on unresolved symbols, handling of ambiguity (despite allow_ambiguous parameter), output format, or pagination. This is a significant gap for a read operation with no safety 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?

A single, front-loaded sentence that efficiently conveys the core action and differentiator. There is no fluff, and every word contributes to understanding.

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 7 parameters, no output schema, and no annotations, the description is far too sparse. It lacks information on return value structure, parameter interactions, error scenarios, and how limit or allow_ambiguous affect behavior. Even for a simple tool, the description leaves too much unspecified.

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 14%, with only worktree having a description. The tool description adds minimal parameter context: it mentions symbol-scoped history and not needing the path, which hints at symbol and worktree, but leaves id, ref, lang, limit, and allow_ambiguous unexplained. This does not compensate for the low schema coverage.

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?

Clearly states the tool resolves a symbol then lists commits touching its file, explicitly highlighting the distinction from path-based history via 'without needing the path'. This precisely defines the resource and action, distinguishing it from siblings like git_history_for_path.

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

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

The description implies when to use it (when you have a symbol, not a path) but does not explicitly state when not to use it or name alternatives. It provides context but lacks direct exclusionary guidance or comparison to sibling tools like git_history_for_path or papertrail_for_symbol.

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

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

With no annotations, the description carries full burden. It clearly states that the tool writes only to the index and never to source, and that it re-indexes stale files. This adequately discloses the key behavioral traits, though it could mention side effects like temporary index inconsistency.

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, no wasted words, front-loaded with the core action. Every sentence adds essential 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?

Covers purpose and write behavior but omits parameter documentation and does not describe return values or error conditions. For a simple tool with one parameter and no output schema, the missing parameter explanation is a notable 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 has one parameter (limit) with 0% description coverage. The description does not mention or explain the 'limit' parameter at all, failing to compensate for the schema's lack of documentation.

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?

Description clearly specifies the verb (re-index, refresh, repair) and resource (stale already-indexed files, FTS), and distinguishes from sibling tools by indicating it is a maintenance/repair operation rather than a read or search tool. The phrase 'repair when reads report drift' uniquely identifies the tool's purpose.

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

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

Provides explicit usage context ('repair when reads report drift') and a behavioral boundary ('Writes only to the index, never to source'). However, it does not explicitly state when not to use or compare to alternatives like index_status or memory_doctor.

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

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

No annotations are provided, so the description must carry the burden. It discloses the return components (completeness/risk summary, distilled_records with a cap and truncation signal) and notes that include flags default to all. It does not mention side effects, costs, or resolution modes explicitly, but the read-only nature is inferable. Overall, it gives meaningful behavioral context beyond a bare enumeration.

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

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

The description is two sentences, front-loaded with the core purpose and a secondary note about distilled records. It is tightly written with no fluff, and each sentence earns its place by adding distinct, valuable 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 complex tool with 10 parameters, no output schema, and no annotations, the description is insufficiently detailed. It mentions distilled_records and completeness_and_caveats.truncated_sections but does not describe the overall return structure or how parameters affect results. The lack of explanation for id/ref/query/symbol/resolution leaves significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is only 30%, with few parameters (include, worktree, full_memories) having descriptions. The tool description does not explain any of the 10 parameters (id, ref, query, symbol, limit, resolution, allow_ambiguous, etc.) and does not clarify how they interact. The description fails to compensate for the low schema coverage, leaving parameter meaning ambiguous.

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

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

The description clearly states it computes the 'blast radius' for a symbol or path, enumerating specific types of impact (callers/callees, tests, docs, git history, papertrail, memories) and includes a completeness/risk summary. It is distinct from sibling tools like find_callers or trace_callees by being a comprehensive pre-edit graph, and the imperative 'Run this before changing anything non-trivial' reinforces its purpose.

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 an explicit recommendation to run before non-trivial changes, and mentions distilled decision records, but does not explicitly contrast with alternatives like find_callers or git_history_for_symbol. It implies a holistic pre-edit check without stating exclusions or specific scenarios where a more targeted tool might be preferred.

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

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

With no annotations provided, the description correctly carries the full burden, and it delivers: it discloses the auto-seeding default from git diff, the teleport-bias semantics, silent skipping of ambiguous/missing entries ('never fatal'), the 'global' escape hatch, and even the exact return shape (mode, seed_source, symbols). It would only be perfect if it hinted at whether the results are deterministic or ordered beyond 'ranked', but for a read-only analysis tool this is exemplary disclosure.

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

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

The description is long but earns its length: purpose, use-case, default behavior, customization, and output format are each covered in turn. The heavy em-dash usage makes it slightly dense to read, and the 'Result is a labeled object' section could be tightened, but every sentence carries unique information with 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 tool with 3 params, no output schema, and no annotations, the description covers all critical ground: it resolves the three-mode complexity, documents graceful degradation, and describes the top-level result structure. The only real gap is that with no output schema present, the shape of the `symbols` array elements is never described — for a ranking tool, knowing what fields each ranked symbol has would complete the contract.

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% with rich parameter docs already, which sets the baseline at 3, and the main description genuinely adds value on top by weaving the params into a coherent behavioral model (explaining what changing `personalize` actually does to the random-surfer teleportation and how the default differs from explicit input). Slightly redundant with the parameter descriptions themselves, but it earns the extra point by clarifying the interplay between modes.

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

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

The description uses a specific verb+resource+method: 'Rank the most load-bearing symbols by weighted PageRank over the call/type/import edge graph'. It goes beyond a plain definition by clarifying the outcome ('the spine you shouldn't reinvent or break') and disambiguating from sibling graph-traversal tools like find_callers or impact_surface through its emphasis on dependency importance rather than simple connectivity.

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 imperative 'Run before editing' provides clear, actionable timing for when to use the tool, and the three-fold mode explanation (diff auto-seed, explicit personalize, 'global') gives concrete usage context. However, it does not explicitly name alternatives to use instead (e.g., when to reach for impact_surface or symbol_lookup over this), leaving a small gap in the when-not-to guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions what status categories are reported and even notes the silently-ignored worktree edge case via the schema, but it does not explicitly state whether the operation is read-only, what conditions indicate parser or FTS failure, or how return values are structured. It discloses a non-obvious behavior, which raises it above a bare description.

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, front-loaded with the core purpose, and uses a clean list to enumerate the reported status categories. There is no filler, redundant schema repetition, or wasted clauses.

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 status/read tool this is reasonably complete: it lists the main status dimensions and the only parameter is fully documented in the schema. However, since there is no output schema and no annotations, describing the return shape or how to interpret 'freshness' would materially improve the agent's ability to use the 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% for the single optional worktree parameter, including default behavior and the silent-ignore edge case. The tool description itself adds no param-specific semantics, so the schema's high coverage keeps this at the baseline without needing extra compensation.

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 identifies the tool as an index-status readout, enumerating the exact facets it exposes (git/indexed head, file counts, parser failures, FTS sync, schema version). It is not a tautology and is easy to distinguish from sibling tools like heal_index, though it lacks an explicit verb such as 'show' or 'read'.

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 is provided about when to use this tool versus alternatives such as heal_index, memory_validate, or papertrail_sync_status. The only usage hint is 'status' in the name, which weakly implies it is a read-only health check, but no explicit 'use when' or 'use instead' guidance exists.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not state whether the operation is read-only, mentions side effects, auth requirements, or return format beyond the listed fields. It is a status tool, but the lack of explicit safety or behavioral notes weakens transparency.

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

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

The description is a single sentence that front-loads the key purpose and lists the specific outputs. It is concise with no redundant or vague wording, making it efficient and easy to parse.

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

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

For a simple status tool with one optional parameter and no output schema, the description adequately covers what the tool returns (model, install state, counts). It does not explain the effect of the worktree parameter, but the schema covers that, so completeness is reasonable.

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 worktree parameter is fully described in the schema. The description adds no extra semantic detail about the parameter beyond what the schema already provides, earning the baseline score.

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

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

The description clearly states the tool reports embedding status, including model, install state, and counts of embedded/missing/skipped chunks. It uses specific context (local vs remote/Ollama) that distinguishes it from sibling status tools like index_status or papertrail_sync_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?

The description implies usage for checking embedding status but does not explicitly state when to use this tool versus alternatives like index_status or papertrail_sync_status. No exclusions or alternative references 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'durable' and 'source-anchored' and says rationale 'resurfaces' later, but it does not state whether creation is idempotent, what response is returned, what side effects occur (e.g., graph changes), or any prerequisites such as index health. This is a significant gap for a create operation.

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

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

Two sentences, zero waste. The first sentence front-loads the purpose and scope, and the second is a direct action call. Every phrase earns its place, and the length is appropriate for the complexity.

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 complex tool with 9 top-level parameters, a nested bind object, and no output schema. The description explains the high-level purpose but omits the return behavior and workflow guidance (e.g., how the memory will be retrievable via memory_search or memory_for_*). The schema carries much of the parameter detail, but the missing usage and output context leaves 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 only 44%, so the description must compensate. It does add conceptual meaning by mapping kinds (Invariant, Decision, Risk) and binding targets (symbol, chunk, path, call-path, commit, tracker) to the schema. However, it does not clarify other parameters like tags, source, created_by, or payload beyond what the schema already states.

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

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

The description uses a specific verb ('Record') with a clear resource ('durable, source-anchored repo memory') and enumerates distinct kinds and binding targets. This clearly differentiates it from siblings like memory_update, memory_search, and memory_for_symbol, which focus on other operations.

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 'Capture non-obvious invariants and decisions as you discover them' implies the trigger for using this tool (during exploration when you find non-obvious knowledge), but it does not explicitly state when NOT to use it or which sibling tools to prefer for editing/searching. No exclusions or alternatives are 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?

With no annotations, the description carries the full transparency burden. It discloses read-only behavior, that status is from the last validation, the special semantics of pending anchors on in-flight branches, and the silent ignore behavior of the worktree parameter via 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?

The description is dense but well-organized, with each clause adding necessary operational detail: what it lists, what pending means, the read-only caveat, the prerequisite validation step, and the rebind action. 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 tool with one optional parameter and no output schema, the description covers purpose, usage, prerequisites, exclusions, and behavioral nuances. It is fully actionable without missing context.

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% for the single worktree parameter, including default behavior and silent ignore semantics. The tool description adds no additional parameter detail, but the baseline of 3 is appropriate because the schema fully documents the parameter.

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

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

The description clearly states the tool lists repo memories with stale, gone, or pending anchors and provides suggested re-anchor targets. It explicitly distinguishes itself as the actionable companion to memory_validate, making its purpose and scope unambiguous.

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

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

The description gives explicit usage direction: run memory_validate first for a fresh check, use memory_rebind for stale/gone entries, and do NOT rebind or mark pending anchors obsolete. This clearly differentiates when to use this tool versus 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?

With no annotations, the description adds some behavioral context: it adds an edge with a specific relation and target. But it does not disclose side effects, uniqueness constraints, permissions, or error conditions.

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

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

The description is two sentences, front-loading the core action and then listing relations and target options concisely without extraneous words.

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

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

For a 7-parameter tool with no output schema, the description covers the main inputs and target selection but lacks return value details, error handling, or edge cases. It is adequate but has 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 0%, so the description compensates by explaining the relation enum and the target options (node vs. GitHub issue). It adds meaning beyond the schema's field types and requiredness.

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

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

The description clearly states the tool adds a typed graph edge from a source node to a target (another node or GitHub issue), and lists the possible relations. This distinguishes it from siblings like memory_edge_remove or memory_edges.

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

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

The description explicitly says 'Give exactly ONE target' and explains the two options (target_node_id or GitHub fields), providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

No annotations provided, so description must carry the burden. It does not disclose side effects, permanence, error states, or required permissions beyond the basic 'remove' action.

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

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

Single sentence with no wasted words, directly front-loading the action and key parameter.

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 tool with one parameter and no output schema, the description is adequate but lacks context about graph behavior, error handling, or relationship to other memory 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 0%, but the description adds that edge_key is 'stable', implying it is a persistent identifier. This adds some meaning beyond the schema, but no further detail on format or constraints.

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

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

The description clearly states the action ('Remove a graph edge') and the identifier used ('stable edge_key'), distinguishing it from siblings like memory_edge_add and memory_edges.

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 alternatives, no prerequisites, and no mention of when not to use it. The description is purely operational.

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

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

With no annotations, the description carries the full burden. It explains the two traversal modes and provides examples, but does not disclose whether the operation is read-only, error behavior for missing node_id, or any side effects. It's adequate for a simple listing operation but lacks explicit safety or precondition details.

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 that are front-loaded with the core intent and immediately give directional semantics. No wasted words; every phrase adds 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?

For a tool with 6 parameters and no output schema, the description is minimal. It explains the core directional logic but omits details like node_id requirements (though the schema's top-level description covers that), how to use github_repo/owner/number, and what happens if node_id is null. It's adequate for a simple read operation but leaves ambiguity for edge cases.

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 17%, so the tool description should compensate for undocumented parameters. It adds meaning for 'direction' with detailed explanations, but leaves node_id, worktree, and github_* parameters unexplained in the description itself (though worktree has a schema description). This is partial compensation, not sufficient for a 6-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?

The description clearly states it lists a node's typed edges, with explicit differentiation between outgoing (from) and incoming/reverse (into) directions. This is specific and distinct from sibling tools like memory_for_symbol or memory_edge_add, so an agent can immediately identify its purpose.

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 concrete examples for each direction ('deps / links / tracks' for from, 'tasks that track an issue' for into), which helps the agent know when to use it. However, it doesn't explicitly state when NOT to use it or contrast with alternatives like memory_edge_add/remove, so it's clear but not exhaustive.

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

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

With no annotations, the description must disclose behavioral traits, but it only states a simple return operation. It does not mention side effects, auth requirements, rate limits, or the silent worktree behavior (which is only in the schema). This insufficiently informs the agent about the tool's safety and constraints.

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

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

The description is a single, front-loaded sentence with no redundancy. It efficiently states the core purpose without wasting words, though it omits important details that are penalized in other dimensions.

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 has three parameters, no annotations, no output schema, and only 33% schema description coverage, the one-sentence description is grossly incomplete. It does not clarify the meaning of edge_sequence_hash, the behavior of limit, or the return format, making it insufficient for 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 only 33% (worktree), and the tool description adds no parameter explanations. edge_sequence_hash and limit remain undefined, and the description fails to compensate for the low coverage, leaving the agent without crucial parameter context.

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

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

The description clearly states the tool returns repo memories bound to a specific call-path edge sequence, using a specific verb and resource. It distinguishes itself from siblings like memory_for_symbol and memory_for_path by focusing on call-path edge sequences.

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 is given on when to use this tool versus alternatives. The description does not mention any conditions, exclusions, or alternative tools, leaving the agent to infer usage 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?

No annotations are provided, so the description carries full responsibility. It only states the function without disclosing any behavioral details such as whether it's read-only, permission requirements, rate limits, or side effects. Even basic characteristics like read-only nature are not mentioned, leaving a significant gap.

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

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

The description is a single, direct sentence with no fluff. It is efficiently worded and front-loaded with the core action. However, given the missing information, it could have included more in the same concise style, so it doesn't fully earn 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 3 parameters, low schema coverage, no output schema, and no annotations, the description is insufficient. It does not specify the return format, how limit affects results, or any ordering/pagination behavior. The worktree parameter has a schema description, but the tool description omits mentioning it entirely, making the overall context incomplete.

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 worktree has a description). The tool description adds no information about the path or limit parameters, failing to compensate for the low coverage. The meaning of 'limit' and required 'path' are not clarified beyond their names.

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

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

The description clearly states the tool returns repo memories associated with a path. It uses specific verb 'Return' and resource 'repo memories bound to a path', effectively distinguishing it from siblings like memory_for_symbol or memory_for_call_path.

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 purpose implies usage for path-based memory lookup, but it does not explicitly state when to use this tool versus alternatives like memory_for_symbol or memory_search. No exclusions or alternative guidance are provided, though the context of sibling tools makes the intended usage somewhat clear.

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

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

With no annotations, the description must disclose behavioral traits. It only states the return operation, implying a read-only action, but provides no details on side effects, error handling, or limitations. There is no mention of how the logical-symbol group behaves or any special cases, falling short of even minimal disclosure.

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

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

The description is a single, succinct sentence that states the core purpose without any fluff. It is perfectly concise and front-loaded, earning a full score despite its 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?

Given six parameters, no annotations, and no output schema, the one-line description is highly insufficient. It does not explain the logical-symbol group concept, return format, parameter interactions, or any edge cases. This leaves the agent without essential context for correct usage.

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

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

Schema description coverage is only 17%, so the description must compensate for undocumented parameters. It mentions 'symbol' explicitly but does not explain id, ref, limit, or allow_ambiguous. The worktree parameter already has a schema description, but the others remain unexplained, leaving a substantial gap.

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

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

The description clearly states the tool returns repo memories bound to a symbol, with a mention of a logical-symbol group. It uses specific language ('Return memories bound to a symbol') and distinguishes from siblings like memory_for_path (path-based) and memory_search (search-based), though it doesn't explicitly name alternatives. The resource (symbol) and verb (return) are clear, earning a 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?

No guidance is provided on when to use this tool versus alternatives like memory_for_call_path or memory_search. The description only states the function, offering no context on selection criteria, prerequisites, or exclusions. This is a clear 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the post-condition: the memory is kept for audit and hidden from active recall. However, it does not mention reversibility or side effects, which would have made it more complete.

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

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

The description is a single sentence that is front-loaded and contains no filler. Every word earns its place, efficiently communicating the action and consequence.

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

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

For a tool with one simple parameter and no output schema, this description is complete. It covers what the tool does and the behavioral outcome. No additional context is necessary for an agent to invoke it correctly.

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

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

Schema coverage is 0% and the description does not explicitly explain the memory_id parameter. However, the single parameter is self-explanatory given the tool name and description. The description adds no meaning beyond the schema, but the parameter is trivially clear, so a baseline of 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?

The description clearly states the action ('Mark a repo memory obsolete') and the resource (repo memory). It also distinguishes this from sibling tools by specifying the outcome: 'kept for audit, hidden from active recall.' This is specific and unambiguous.

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

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

The description implies when to use this tool (when a memory should no longer be actively used but must be retained for audit). It doesn't explicitly name alternatives or exclusions, but the context is clear enough to differentiate from memory_update or memory_rebind.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it replaces the binding and refreshes the source_text_hash, but does not mention side effects, reversibility, or permissions. This is adequate but not fully transparent.

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

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

The description consists of two concise sentences: the first states purpose and usage context, the second explains the effect. No redundant words or information.

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

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

The description covers the core purpose and when to use, but given the tool's complexity (many optional binding parameters) and lack of output schema, it does not explain how to specify the new binding or what happens if the memory doesn't exist. This leaves some gaps for an AI 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 0% based on context signals, and the description only vaguely references 'symbol, chunk, path, or other source location' without mapping these to specific parameters like chunk_id, path, etc. The description does little to clarify the meaning of the many optional parameters, leaving the agent to infer from names alone.

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

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

The description uses specific verb 're-anchor' and resource 'existing repo memory', clearly stating the tool updates a memory's binding after symbol moves/renames, distinguishing from obsoleting and recreating.

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

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

The description explicitly says 'use this after a symbol moves or is renamed rather than obsoleting and recreating the memory', providing clear when-to-use guidance. It does not explicitly name alternative sibling tools like memory_create or memory_update, but the context is clear enough.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It only mentions 'active (or stale)' when referring to memories, but does not disclose whether the operation is read-only, what results are returned (sorting, pagination), or any side effects. It also omits permission requirements. The worktree behavior ('silently ignored') is described in the schema, not the description, so it doesn't count here. This leaves significant gaps.

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

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

The description is a single, well-formed sentence that is immediately clear and front-loaded with the core action. There is zero redundancy or filler. Every word contributes to meaning, making it highly efficient.

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 three parameters, no output schema, and no annotations, the description is far too brief. It does not explain the result format, ordering, what constitutes 'memories', or how to interpret 'active' vs 'stale'. It also lacks integration of the worktree parameter's behavior, which is only in the schema. The tool would require the agent to make many assumptions, making it incomplete for a production context.

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 33% (only worktree has a description). The description adds minimal value: it implies that 'query' is the keyword for search, but provides no additional context for 'limit' or 'worktree' beyond what the schema already offers. The description does not clarify defaults, formats, or edges cases, failing to compensate for the low schema coverage.

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

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

The description clearly states the verb 'search' and the resource 'repo memories' with a qualifier 'full-text' and 'by keyword', distinguishing it from semantic_search and symbol-specific lookups. It also notes the 'active (or stale)' scope, which adds specificity. This is a strong, specific purpose statement.

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 for keyword-based full-text search but provides no explicit guidance on when to use this tool over alternatives like semantic_search or memory_for_symbol. There is no mention of exclusions, prerequisites, or alternative tools, leaving the decision to the agent's inference from sibling names. This is minimal implicit guidance, not explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose key behavior: it always returns the full body and works independently of the rendering surface. However, it does not cover failure modes (e.g., invalid/obsolete memory_id), error behavior, or how the full body is returned — leaving noticeable gaps for a read/expand operation.

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

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

The description is three sentences with no filler: the first sentence states the core behavior, the second gives the concrete invocation scenario, and the third reinforces surface-independence. Every sentence adds distinct value and the key phrase 'the expand path for a compact summary' is front-loaded.

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

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

For a fairly simple two-parameter tool, the description covers what the tool is, when to call it, and what it returns ('the complete original', 'full body'). The only notable gap is that it does not describe the shape of the returned full body or error conditions, and since there is no output schema, a brief return-shape note would improve completeness.

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% and memory_id has no schema-level description; the tool description compensates by explaining that memory_id should come from the attachment's summary rendering. The worktree parameter is fully documented in the schema already, so the description does not need to repeat it, and the description's context about the 'expand path' gives memory_id meaningful semantics it would otherwise lack.

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

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

The description uses a specific verb+resource combination: 'Expand ONE repo memory to its FULL body by memory_id' — this clearly identifies both the action and the target. It also distinguishes itself from sibling memory tools by labeling itself as 'the expand path for a compact summary'.

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 an explicit when-to-use scenario: when a `[memory] surface = "summary"` renders drive-by attachments, call this tool with the attachment's `memory_id`. It also clarifies the tool is 'surface-independent' and 'always the full body', but does not explicitly state when-not-to-use or name alternative tools for other scenarios.

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

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

No annotations provided; description only says 'update', implying mutation. It does not disclose whether it replaces or merges fields, authorization requirements, whether it returns the updated object, or any side effects.

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?

Single sentence, no fluff. All words contribute to the 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?

No output schema, 8 parameters with limited schema coverage. Description does not explain return value, error handling, or behavior when updating multiple fields. Incomplete for a mutation 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 description coverage is 38% (only body and title have descriptions). The description lists the fields but adds no extra meaning beyond the schema. It doesn't explain payload or memory_id semantics, but listing fields provides some guidance.

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 'Update a repo memory's text, status, confidence, kind, or tags by id.' It specifies the verb (update), resource (repo memory), and lists modifiable fields. However, it does not differentiate from siblings like memory_rebind or memory_create, which may also modify memories.

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 alternatives such as memory_rebind or memory_show. There is no mention of prerequisites or when not to use 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?

No annotations provided, so description carries full burden. It mentions re-anchoring and marking, but does not disclose side effects, destructive nature, permissions, or idempotency. Minimal 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 concise sentences, each adding value: first explains action and categories, second gives timing. No wasted words.

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

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

Lacks details on output schema and meaningful descriptions of the status categories. With no annotations, more context on side effects and return values would improve completeness.

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?

Input schema has zero parameters, so schema coverage is 100% trivially. Description adds no parameter details, but baseline for no parameters is 4.

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?

Description clearly states the verb 're-anchor' and 'mark', the resource 'repo memory', and the outcome (current/relocated/stale/gone/pending). It distinguishes from sibling tools like memory_create or memory_update.

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?

Description implies it runs automatically after indexing, but does not explicitly state when a user should invoke it manually or provide alternatives. No guidance on when-not-to-use.

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

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

With no annotations, the description carries the full burden. It discloses that tracker items are cached (implying potential staleness), which is a useful behavioral trait beyond the schema. However, it does not explicitly state read-only behavior or describe output format/pagination.

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

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

The description is a single, tightly worded sentence that front-loads the core concept ('why behind a chunk') and then specifies the exact contents returned. No filler or redundancy.

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

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

The description adequately conveys the tool's main output but omits usage context, alternative tool differentiation, and parameter nuances (e.g., worktree behavior). Without an output schema, more detail on return structure would be valuable.

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 worktree has an inline description). The tool description adds no details for chunk_id or limit, so the agent must rely on parameter names and defaults. This is insufficient for a 3-parameter tool with low schema coverage.

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

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

The description clearly states the tool returns a chunk's current text plus cached tracker items and review comments referencing it. This specific scope distinguishes it from sibling papertrail tools like papertrail_for_symbol or papertrail_for_commit.

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 is provided on when to use this tool versus alternatives such as papertrail_refs_for_path or papertrail_for_symbol. The description only defines what the tool does, not the appropriate usage context or 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?

The terms 'Cached' and 'historical' hint that this is a read-only, potentially stale lookup, which is useful given there are no annotations. However, the description does not disclose synchronization requirements, failure behavior, or output shape, so transparency is only partial.

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 terse sentence with no filler; it front-loads the core meaning ('Cached tracker items') and usefully enumerates the item types. Every word contributes to the tool's 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 and no annotations, the description should explain more about returned items, limit semantics, and how this tool differs from the many papertrail_* siblings. The current description provides only a minimal purpose statement and leaves important context unresolved.

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 50%: include and worktree are described, while limit and commit_hash are not. The description adds only the 'historical commit' nuance to commit_hash and says nothing about limit, so it does not compensate enough for the undocumented 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 identifies what the tool provides: cached tracker items (issues/change requests/reviews) associated with a given commit. It distinguishes from sibling papertrail_for_chunk/symbol/path by the commit scope, though it lacks an explicit retrieval verb like 'list' or 'fetch'.

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 tool versus papertrail_for_symbol, papertrail_for_chunk, papertrail_issue_search, or other related siblings. The phrase 'historical commit' implies a context, but no explicit when-to-use or when-not-to-use information is provided.

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

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

No annotations are provided, so the description must carry the burden. It mentions 'current context' and 'cached tracker rationale' but does not detail what 'current context' includes or what 'cached' implies regarding fresh data.

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

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

The description is concise at one sentence, but the structure is a bit dense. It could be improved by breaking into two sentences for clarity, but it's still efficient.

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 7 parameters and no output schema, this description is incomplete. It doesn't explain return values or how parameters interact, leaving significant gaps for the agent to interpret.

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 7 parameters and only 14% schema description coverage, the description does not compensate. It doesn't explain key parameters like 'id', 'ref', 'lang', 'limit', or 'allow_ambiguous', leaving the agent without crucial usage details.

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

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

The description clearly states the primary action: 'Resolve a symbol' suggests ambiguity, but the description could be more specific about the external process that is not present in the text. The description is fairly adequate, but can be improved.

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 mentions 'resolve a symbol' but does not specify when to use this tool versus alternatives in the sibling set. It lacks explicit guidance on when to prefer this tool over similar ones.

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

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

With no annotations, the description must carry the transparency burden. It discloses that hits may include a `record` field with root-cause/decision/outcome and that issue↔PR pairs are coalesced. This adds useful behavior beyond the schema, though it omits any side effects, error conditions, or read-only guarantees.

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 purpose, no fluff. Efficiently conveys the key behavior and additional nuances without wasting words.

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

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

Despite the tool having 7 parameters and no output schema, the description only covers general behavior and the `record` field. It omits parameter explanations (e.g., `limit`, `graph_limit`, `include_graph`, `explain`), return structure, and any usage caveats. This is insufficient for reliable agent 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 only 29% (only `include` and `worktree` have descriptions). The description itself adds no parameter meaning; it does not explain `query`, `limit`, `explain`, `graph_limit`, or `include_graph`. Given the low coverage, the description should compensate but fails to do so.

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

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

The description clearly states it performs full-text search across cached tracker issue and change-request titles and bodies, which is specific and differentiates from sibling tools like semantic_search (semantic) and commit_search (commits). The mention of distilled records and coalesced PR pairs further clarifies its unique scope.

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

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

The description implies usage for searching issue text but does not explicitly state when to prefer this over alternatives like semantic_search or papertrail_for_symbol. No exclusions or special conditions are given, leaving the agent to infer applicability.

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

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

No annotations are provided, so the description must carry the burden. It implies reading cached data but does not disclose read-only nature, side effects, error conditions, or limitations. It is silent on behavior beyond the basic listing.

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

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

The description is a single, succinct sentence that immediately states the primary function. No filler or redundancy.

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

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

The description lacks details on output format, what 'cached tracker items' are, how path and worktree interact, and any constraints. Given the schema has three parameters and no output schema, the description is insufficient for full understanding.

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

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

The description does not clarify the meaning of 'path' or 'limit' beyond the schema's type. The 'worktree' parameter has a schema description, but the tool description adds no extra context. 'Current path' is ambiguous.

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

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

The description clearly states the action (list), the object (cached tracker items), and the scope (referencing a current path). It is distinct from sibling tools like papertrail_for_chunk or memory_for_path.

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 is provided on when to prefer this tool over the many similar sibling tools. It does not explain use cases, prerequisites, or alternatives.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does not state whether the tool is read-only, whether it triggers a sync, or any side effects. The term 'status' implies a read-only query, but this is not explicit. It also does not describe what happens if the cache is stale or whether it accesses the live system. This minimal disclosure falls short, especially for a tool whose name suggests a possible side-effect (sync).

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

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

The description is a single, well-structured sentence that front-loads the purpose ('Papertrail cache status') and then enumerates the returned items (counts, last sync time). There is no fluff or redundancy, making it highly concise and easy to parse.

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

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

For a simple status tool with one optional parameter and no output schema, the description provides the essential return contents. However, it lacks context about the scope (e.g., whether counts are for the entire repo or the specified worktree) and does not explain what 'Papertrail cache' refers to or when data might be stale. While not severely incomplete, it leaves some gaps for an agent to infer.

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

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

The input schema has 100% coverage for the single optional 'worktree' parameter, which is fully described in the schema. The tool description does not mention this parameter at all, adding no semantic value beyond the schema. Since schema coverage is high, the baseline score of 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?

The description clearly states the tool's purpose: reporting Papertrail cache status with counts of issues, change requests, comments, refs, and last sync time. This is a specific verb-resource combination ('status' of 'Papertrail cache') that distinguishes it from sibling tools like papertrail_for_chunk or papertrail_issue_search, which access specific data rather than overall cache health.

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 for checking cache sync status but does not explicitly state when to use this tool over siblings. It lacks alternatives or exclusions (e.g., no mention of using papertrail_for_chunk for detailed data). The context is clear enough but not explicitly framed as 'use this when you need to verify sync state.'

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

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

With no annotations available, the description carries the full burden. The conditional `record` field disclosure ('A hit whose thread has a distilled decision record carries it as `record`') is genuinely useful and reveals result-shape behavior beyond a naive reading. However, the 'cached' aspect isn't qualified (staleness, when to trust vs refresh), and the `worktree` edge case ('silently ignored') only appears in schema, not description. Core search behavior covered, supporting details absent.

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, roughly 50 words, and both earn their place. The purpose is front-loaded in sentence one, and the second sentence delivers a valuable behavioral nuance. Slight deduction for the second sentence's convolution ('carries it as `record`' has an awkward antecedent) and the nested parenthetical, but overall this is tight, effective prose.

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 7 params, no annotations, and no output schema, the description covers only the core search contract and the `record` field. Missing: semantics of the graph output params (which appear to control some graph-return mode), what 'cached' means for result freshness, behavior on empty results, and how this output's graph mode relates to `compare_graph_*` siblings. The description would be sufficient for a simpler tool, but not this one.

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 29%, putting the burden on the description to compensate. It doesn't: the description's only param-relevant contribution is 'by keyword' (qualifying the query param) and mentioning `record`, which is an output field, not a parameter insight. The opaque `graph_limit` and `include_graph` params (with only the cryptic McpGraphMode enum 'compact'/'full'/'none') remain completely unexplained by the description.

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+resource: 'Search cached tracker rationale snippets... by keyword' clearly identifies the search target and scope. Parenthetical '(review comments, issue / change-request discussion)' and the keyword-vs-semantic implication distinguish it from many siblings. However, it doesn't explicitly differentiate from closely related search tools (`semantic_search`, `memory_search`, `papertrail_issue_search`), so what exactly makes this corpus distinct from those is left implied.

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 source specification gives clear context about what content is covered, which implicitly signals when this tool applies. However, there are no explicit when/when-not-to-use instructions, no named alternatives, and no distinction from sibling search tools. For an agent choosing among `rationale_search`, `semantic_search`, `memory_search`, or `commit_search`, no decision support is offered.

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

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

With no annotations, the description carries the burden of disclosing behavior. It reveals validation logic (relocates/stale/gone), the inclusion of call-graph context and memories, and the attachment of distilled decision records (labeled unreviewed, capped at 2). It does not mention side effects (though read-only is implied) or error handling specifics, but overall it provides substantial behavioral context beyond the schema.

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

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

The description is three sentences, front-loaded with the primary purpose and usage. Each sentence adds distinct value: purpose, usage, and a specific behavior (distilled_records). No redundancy or fluff, though it could be slightly more compact.

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 5 parameters, no annotations, and no output schema, the description covers core behavior but gaps remain: it does not explain worktree semantics, graph_limit constraints, or how to suppress memories (though schema covers include). The description is adequate for basic usage but not fully comprehensive given the complexity.

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

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

The description mentions the chunk_id and 'bound repo memories' (tied to the include parameter) and the compact call-graph context (related to include_graph), but does not explain parameters like worktree or graph_limit explicitly. Schema coverage is only 40%, so the description partially compensates but leaves several parameters under-explained. The distilled_records mention is output, not parameter semantics.

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

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

The description opens with a specific verb and resource: 'Read the current source text for one chunk id', immediately clarifying the tool's core function. It also includes validation specifics ('validated against HEAD (relocates or flags stale/gone)') and context features (call-graph, memories) that distinguish it from sibling tools like git_blame_chunk or papertrail_for_chunk.

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

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

Provides an explicit usage scenario: 'Use to read exact text after a search returns a chunk_id.' This clearly indicates when to invoke the tool, though it does not explicitly mention when not to use it or point to alternative tools. The context is clear enough for straightforward selection.

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

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

With no annotations, the description carries the behavioral burden, and it does so reasonably well: it says the tool ranks files, supports four modes, reports several signals, and suggests next steps. It does not explicitly state that it is read-only or discuss stale-index/performance caveats, but the orientation framing makes the non-mutating nature clear.

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

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

Two compact, front-loaded sentences say what the tool does, how it ranks files, what signals are included, and when to invoke it. Every clause carries useful information; there is no fluff.

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

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

Given that the output schema is absent and there are no annotations, the description is fairly complete: it communicates the purpose, modes, result ingredients, and suggested next tools. It could be slightly more specific about how the limit, include flags, and worktree interact with the summary, but the schema already documents those.

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

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

The description adds useful meaning to the main 'mode' parameter by explaining that 'spine' means central coupling and that the other modes are churn, god_modules, and refactor_candidates. The include and worktree parameters are already well described in the schema, so the description's additional mode semantics meaningfully improve parameter understanding.

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 says this is an orientation tool for an unfamiliar repo, what it does (returns ranked files by mode), and what the output contains (size/coupling/churn/memory signals and suggested next tools). 'Start here when you don't know the codebase' helps separate this from more targeted sibling tools.

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

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

It explicitly tells the agent when to use it: 'Start here when you don't know the codebase.' It doesn't name specific alternative tools and say when not to use it, but the starting-point framing provides enough context for this orientation 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?

No annotations are provided, so the description carries the full disclosure burden. It discloses the clustering methodology and implies a read-only, low-cost operation via 'cheap', but it does not disclose default behaviors (limit=10, min_cluster_size=2), how the memories/generated include flags alter results, or any failure modes.

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 stays on-topic. Every phrase contributes (methodology, cost profile, output shape), with no wasted words. It is appropriately compact for a mapper-style tool, though it could arguably have folded in a usage pointer.

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 and no annotations exist, making the description the agent's sole source of behavioral truth. Given the 4 parameters and no return-shape information, the description is incomplete — it omits result format, default limits, and the important memories-on-by-default include behavior.

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

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

The description adds no parameter-level meaning at all — it never mentions limit, min_cluster_size, include, or worktree. With schema description coverage at only 50%, the description fails to compensate for the two parameters (limit, min_cluster_size) left undocumented 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 uses a specific verb ('Map') with a clear resource (the repo) and names both the methodology (path proximity, graph edges, git co-touch) and the expected output (subsystems and their representative files). It clearly differentiates from the search/view/memory siblings, but it does not distinguish itself from the closely-related repo_brief tool, which the schema explicitly references.

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 explicit when-to-use or when-not-to-use guidance is provided. The phrase 'a cheap overview' weakly implies a fast-orientation use case, but no alternatives are named and no exclusions are given — particularly problematic given the near-identical repo_brief sibling exists on the same enum.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It transparently explains scoring (blended BM25+vector), the explain flag, retrieval_mode field, fallback to BM25-only, validation against current source, and the distilled_records behavior with caps and labels. This is unusually thorough and exceeds typical 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?

The description is a single dense paragraph but packs numerous details without fluff. It is not excessively long for the information conveyed, though it could benefit from structured sections (e.g., bullet points) for readability. The front-loaded purpose sentence is clear, and every clause contributes meaningful behavioral or output context.

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

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

Given the tool's complexity (7 parameters, no output schema, no annotations), the description covers the most important behavioral aspects (scoring, retrieval_mode, fallback, validation) and relies on the schema for worktree and include. However, parameters like limit, graph_limit, and include_graph remain unexplained, and the description does not describe default behaviors for these. Overall, it is largely complete but misses some parameter context.

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 29%, so the description must compensate for undocumented parameters. It explains the 'explain' parameter explicitly and touches on 'include' indirectly (via fallback), but leaves limit, worktree, graph_limit, and include_graph unexplained. The output semantics (score, retrieval_mode) are covered, but input semantics beyond explain are not addressed, leaving a significant gap.

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

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

The description clearly states the tool's purpose: 'Search indexed source and docs.' This is a specific verb plus resource, and it distinguishes from other search tools like memory_search or rationale_search by focusing on source code and documentation. It also adds detail about scoring and retrieval modes, making the purpose unambiguous.

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

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

The description does not explicitly indicate when to use this tool versus alternatives. It describes behavior (scoring, fallback) but offers no guidance on when semantic_search is preferred over sibling tools like commit_search or memory_search. There is no mention of when not to use it or which alternative 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?

With no annotations, the description carries the full burden and delivers: it discloses the default exclusion of generated bindings, the effect of include, and the distilled_records field's labeling, cap of 2, and typical emptiness. This goes well beyond a terse summary, adding meaningful context about what the agent will observe.

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 front-loaded with purpose and each sentence adds a distinct piece of information: purpose, return contents, usage timing, include behavior, and distilled_records caveat. The final clause about distilled_records is slightly verbose for an edge case, but the overall structure is efficient.

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 complex 8-parameter tool with no output schema, the description covers purpose, return contents, usage context, and one include behavior, and it differentiates from siblings. It lacks full return shape or error/edge-case details, but these may be better left to schema or additional docs.

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

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

The schema already documents include and worktree, and the prose adds the critical include syntax and rationale. However, with only 25% schema coverage, the description leaves most parameters (id, ref, lang, limit, symbol, allow_ambiguous) to be inferred, missing an opportunity to clarify their interactions and defaults.

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

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

The description opens with a specific verb and resource: 'Resolve a symbol name (or ref/id) to its definition(s)' across multiple languages, with exact or fuzzy matching. It enumerates return contents (signatures, locations, cfg grouping, bound memories) and explicitly frames its role to disambiguate before graph/read calls, distinguishing it from sibling tools like semantic_search or find_callers even without naming 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?

It gives concrete when-to-use guidance: 'Use to disambiguate before a graph or read call' and explains the default exclusion of generated bindings with the exact include flag syntax to override. However, it stops short of naming alternative tools or stating when NOT to use it, so it misses the full 'when-not/alternatives' bar.

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

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

With no annotations provided, the description must disclose behavior itself. It does so by explaining the default filtering of 'unresolved std/common-method noise' and how to opt back in via the include array. This gives actionable behavioral context beyond a simple read query. It does not mention side effects or authorization, but the tool appears to be a read-only graph query, so this level 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?

The description is two sentences, front-loaded with the core purpose ('Find what a symbol calls (forward call graph)') and immediately follows with the most important behavioral nuance (noise filtering) plus a pointer to a sibling tool's semantics. No wasted words; each sentence carries meaningful 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?

Given the tool has 9 parameters, no output schema, and no annotations, the description is sparse. It explains the overall purpose and one filtering behavior, but omits details about return shape (beyond 'same evidence shape as find_callers', which is not elaborated), default limits, or the meaning of edge_kinds/resolution. A user would need to consult the schema or other tools to fully understand usage. This is insufficient for a tool of this complexity.

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 22% (only include and worktree have descriptions in properties). The description adds detail about the include parameter's behavior (default filtering and how to override), which is valuable. However, it does not explain the remaining 7 parameters (id, ref, limit, symbol, edge_kinds, resolution, allow_ambiguous), leaving them underdocumented. The description fails to compensate for the low schema coverage, so the score is low.

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

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

The description clearly states 'Find what a symbol calls (forward call graph)', which is a specific verb+resource combination, and explicitly differentiates from the sibling find_callers by specifying direction ('forward') and noting 'Same evidence shape as find_callers'. This leaves no ambiguity about the tool's core function.

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

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

The description implies when to use it (for forward call graph exploration) and contrasts with find_callers via the phrase 'Same evidence shape as find_callers', hinting at a sibling relationship. It also explains a filtering behavior that affects usage (default noise filtering, adjustable via include). However, it does not explicitly state when not to use it or recommend an alternative for other cases, so slightly less than excellent.

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