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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful framing (retrieval of prior outputs, no regeneration cost) but says nothing about failure behavior for a missing or expired ID, which is the main behavioral risk 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?

A single front-loaded sentence with no filler; the retrieval purpose and the regeneration-avoidance rationale both earn their 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 two-parameter read tool with complete annotations, full schema coverage, and no output schema, the description gives enough to call it correctly. Only the missing-ID behavior is arguably left unaddressed, a minor gap.

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

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

Schema description coverage is 100%, with artifact_id documented as coming from repo_map, search, task_pack, change_impact, edit_scope, or decision_brief, and root explained for worktrees. The description only echoes the 'by ID' idea, adding no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Load a previously generated context artifact by ID') and explains the artifact kinds involved (task packets, repo maps, decisions). It implicitly separates itself from generators like task_pack or repo_map, though it never names 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?

The phrase 'so agents can reuse ... without regenerating them' implies the when: call this instead of re-running a generator. However, no sibling is named and there is no explicit exclusion or precondition (e.g., what to do when the artifact_id is unknown or stale).

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add what they cannot. It does: it discloses that matching is textual rather than semantic and that same-name symbols are included, warning the agent about false positives — a genuinely useful caveat beyond structured fields.

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 short sentences, front-loaded with the core purpose, then the kind hint, then the sibling routing. No filler and no repetition of schema 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?

With no output schema, the description partially compensates by mentioning counts by kind and totals behavior. It leaves the summary-vs-detailed output shape to the schema, which is acceptable, but a mutation-free read tool with 5 params could say slightly more about result 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 coverage is 100%, so the baseline is 3, but the description adds real semantics: it explains what kind:call actually selects (call-containing lines) and that totals aggregate across all kinds. Mode, root, and file_context meaning come entirely from 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 first sentence states a specific verb and resource ('find textual usage candidates with counts by kind'), which disambiguates the metaphorical tool name. It explicitly distinguishes itself from exact_references. It does not, however, differentiate from the grep/search siblings, which do similar textual lookups.

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 names an alternative (exact_references) with the exact condition that selects it — binding-resolved TS/JS rename checks — and gives a concrete usage hint ('use kind:call for call-containing lines'). No guidance on when this tool is the wrong choice versus grep/search, so not a 5.

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

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

Annotations already indicate the tool is not read-only and not destructive. The description adds useful context by clarifying that enabling affects the session catalog and that the fallback `call` path runs only supported read/index tools, never source edits.

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 short and front-loads the main capability. The second sentence is dense but still earns its place by covering the fallback behavior and edit exclusion.

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

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

For a five-parameter discovery tool with a nested object and no output schema, the description covers the core behavior, fallback execution, and edit exclusion. It could be more explicit about return shape, but the schema carries most parameter detail.

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

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

Schema description coverage is 100%, so the schema already explains each parameter thoroughly. The description reinforces the `call` and `enable` semantics but does not add substantial meaning beyond the schema.

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

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

The description names specific actions (discover, enable, return schemas) and the resource (experts/tools), making the tool's role understandable. It does not explicitly distinguish itself from siblings like search or grep, so it stops short of a 5.

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

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

It provides a conditional for the nested `call` parameter and a clear exclusion ('never source edits'), but gives no explicit guidance on when to use `discover_tools` versus alternatives such as `search`, `grep`, or `status`. Usage is implied rather than fully stated.

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

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

Even with read-only annotations already present, the description adds important behavioral context: history stores numeric metrics only and never prompts, source code, response bodies, or file paths, and token savings are estimates rather than billing data. This gives an agent the privacy and accuracy caveats needed to invoke and interpret it correctly.

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

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

It is two sentences with no wasted language, leading with what the tool reports and then immediately covering privacy and estimate caveats. Every sentence earns its place.

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

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

For a reporting tool with full parameter documentation and reliable safety annotations, the description covers purpose, privacy guarantees, and estimate caveats. The main remaining gap is that no output schema exists and the description does not explain the return structure or finalSummary output, though the schema partially mentions it.

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

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

Schema description coverage is 100%, and the parameter descriptions already explain scope windows, formatting, history limits, and cost inputs in detail. The description adds no additional parameter semantics beyond what the schema provides, so the baseline 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 states a specific verb and resource: reporting ContextPro's persistent, auditable context-compression estimates by tool. It is clearly distinguishable from all sibling tools, which are code-search/indexing utilities rather than reporting 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 purpose implies the usage context—auditing or reporting compression estimates—but the description does not explicitly say when to call it, when not to call it, or what alternatives exist. The schema adds a useful hint to call at task completion, but the description itself provides only implied 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?

The description adds real behavioral context beyond the read-only annotations: Python results are heuristic, imported SCIP index freshness is unverified, and callers should inspect scope, ambiguity, and warnings. These accuracy caveats are exactly what an agent needs to interpret results; it stops short of describing failure modes or fallback behavior.

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

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

Four efficient sentences with the core purpose front-loaded and no repetition. The phrasing is somewhat telegraphic ('Check scope, ambiguity and warnings'), which costs a little clarity but wastes no space.

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

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

With six parameters and no output schema, the description does a good job covering accuracy expectations, result labeling, per-file totals, and warnings. It is nearly complete for calling the tool correctly, missing only explicit sibling routing and return-shape detail.

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 83%, so parameter documentation is already handled by the schema, which is the correct baseline of 3. The description adds only indirect meaning ('per-file call totals before limits' touches on the limit parameter) and no syntax or format details beyond structured fields.

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

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

The opening sentence states a specific verb and resource: 'Find who calls or references a symbol.' The clause about TS/JS compiler bindings excluding same-named unrelated symbols implicitly distinguishes it from text-search siblings like grep/search, though none are named explicitly.

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

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

Usage guidance is implied rather than explicit: 'Check scope, ambiguity and warnings' and the mention of Python being heuristic hint at when to trust results, but the description never states when to choose this over grep or search, nor any preconditions. Most disambiguation guidance lives in the schema, not the description.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context: symbol extraction returns code plus called functions, file mode returns a structural overview, and neither requires reading the entire file. It does not cover batch behavior or token-budget truncation, but the schema covers those 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?

The description is three tight sentences with the core purpose front-loaded and no wasted phrasing. It has minor redundancy with the schema's file and symbol descriptions, but overall it is efficiently structured.

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

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

For a seven-parameter tool with batch mode, depth, format, and worktree-root requirements, the description covers only the two primary modes. The schema and annotations carry much of the burden, but an agent still lacks description-level guidance on batching and sibling alternatives.

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

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

Schema description coverage is 100%, so the schema already documents file, root, depth, format, symbol, symbols, and max_tokens. The description adds mode meaning for symbol versus file, but does not explain depth, format, root requirements, batch symbols, or max_tokens beyond what the schema provides.

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

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

The description states a specific verb and resource: extract a function/class body plus dependencies without reading the whole file. It clearly distinguishes the symbol mode from the file-overview mode. It does not differentiate from siblings such as skeleton or exact_references, so it stops short of a 5.

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

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

It explains how to trigger the two main modes: provide a symbol for code plus called functions, or provide a file path for a structural overview. It implies this is preferable to reading an entire file, but it does not give explicit when-to-use/when-not guidance against sibling tools or mention the batch symbols mode.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds real value by disclosing that binary files are skipped and that .gitignore is honored through the indexed walker — scope limits an agent cannot infer from annotations. It stops short of describing how results are shaped or truncated, which leaves a small 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?

Four compact sentences, front-loaded with what the tool does, then when to use it, then the sibling alternative, then the behavioral caveat. Nothing is repeated from the schema and no sentence is filler.

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

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

For an 11-parameter tool with no output schema, the description covers scope, filtering rules, and the alternative tool, which is most of what is needed. The remaining gap is return-value shape — the description never says results come back as file/line/column hits, leaving that to the context_lines schema text.

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

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

Schema description coverage is 100%, so the schema already explains glob, root, regex, context_chars, context_lines, and the match caps in detail. The description only reinforces literal-vs-regex matching and adds no format, interaction, or defaulting guidance beyond the structured fields, so baseline 3 applies.

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

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

Names a specific verb (search) plus the resource (indexed file set) and the two matching modes (literal or regex). It also explicitly separates itself from the semantic sibling by saying to use 'search' for intent queries, so an agent can choose without opening either schema.

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

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

Gives concrete use cases (log-message lookups, config-key searches, error-message tracing) and the decision rule: exact characters here, semantic intent in 'search'. That is both a when-to-use and a named alternative with the condition that selects it.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write with closed-world scope. The description reinforces the persistence intent and lists the types of content stored, but it does not add operational details such as whether records can be updated, how supersession works, or what the tool returns. With annotations covering the safety profile, 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 well-formed sentence with no wasted words. The core action and content are front-loaded, making it easy to parse quickly.

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

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

For a write tool with 11 parameters, including supersession and source-evidence linkage, the description is minimal. The schema covers parameter details and annotations cover safety, but the description does not explain the tool's return behavior or how features like supersedes and validation_refs should be used in practice. It is adequate but leaves meaningful gaps for an agent trying to use the tool correctly.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description names several key inputs (files, assumptions, evidence, open risks) but omits others such as supersedes, source_evidence, validation_refs, root, and format. Baseline 3 is appropriate when the schema carries the parameter 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?

The description states a specific verb ('Persist') and resource ('useful task outcomes') along with the kinds of content captured (files, assumptions, evidence, open risks). It is clear what the tool does, though it does not explicitly differentiate itself from any sibling tool, likely because none of the listed siblings directly overlap.

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

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

The phrase 'for future sessions' implies this should be used to record outcomes that later sessions will need, but there is no explicit when-to-use or when-not-to-use guidance. No alternatives or prerequisites are mentioned, leaving the agent to infer appropriate usage.

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?

Goes well beyond the annotations by disclosing incremental behavior via content hash, the embedding side effect and its cost implications, the two env-var overrides, and a downstream dependency (import graph for related/test_map). It does not state what happens to stale entries or what the call returns, which keeps it from a 5.

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

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

Four front-loaded sentences, each carrying distinct information (action, incrementality, embedding side effect, when to call). Slightly dense with env-var asides but 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?

No output schema exists, but the description covers the mutation semantics, cost model, and triggering conditions adequately for call. It omits what the call reports back (e.g., changed-file counts) and any runtime expectations, which would complete the picture.

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 already 100%, so the baseline is 3; the description earns a notch above by explaining the no_embed flag's interaction with CONTEXTPRO_REINDEX_NO_EMBED and clarifying the default embedding behavior. The other four parameters add no extra meaning in the description beyond their schema text.

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

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

Uses a precise verb sequence (re-walk, re-parse, re-index) against a specific resource (project files into the database), leaving no ambiguity about what the tool does. It does not directly name or contrast with the listed siblings (search, status, grep), so it stops short of full sibling differentiation.

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

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

Gives concrete trigger conditions: 'Use after git pull, branch switch, or external edits,' which is exactly the kind of context an agent needs. It lacks an explicit when-not-to-use or a pointer to an alternative tool for lighter-weight checks.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is free. The description adds real behavioral context: the hybrid scoring architecture (embeddings + keyword overlap) and the cost/coverage tradeoff implied by fast vs exhaustive presets. It doesn't discuss latency or cost per call explicitly, but it goes beyond annotation restatement.

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

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

Four sentences, no filler, and the core purpose plus the mode taxonomy lead. The long final sentence carries the competitive-alternative guidance, so its length is earned rather than padding.

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 19-parameter, no-output-schema tool, the description covers the decision-relevant surface: what it searches, how modes differ, and when another tool wins. The remaining gap is that output behavior (inline code spans, dependency pointers, result shape) is left entirely to the schema field descriptions.

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

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

Schema description coverage is 100%, so all 19 parameters are already documented and the baseline is 3. The description adds a conceptual model for the scoring (embeddings + keyword overlap) that makes fusion/weights/min-score parameters meaningful, but it says nothing about root/worktree handling, include_dependencies, or the inline_code output 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 opens with a specific verb and resource ('Search the codebase by MEANING') and immediately enumerates the three modes with what each matches. It conceptually separates itself from exact-symbol lookup, though it never names its actual siblings (grep, exact_references, skeleton) — it references an external LSP-backed MCP instead.

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

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

Clear routing guidance: prefer an LSP tool for a known symbol name, and use this tool for 'meaning-based / fuzzy discovery across the whole repo.' Mode selection guidance is present. What's missing is exclusion guidance against the concrete siblings in this server (grep, exact_references, skeleton), which would make the choice trivial.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add behavior it can't infer — and it does: signatures are normalized summaries, line ranges are included, and the output is explicitly not safe as an exact edit anchor. It doesn't cover failure modes (unsupported file types, missing paths) or output size limits, so not a 5.

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

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

Three tight sentences: what it returns, what it returns alongside (line ranges), and the critical caveat plus alternative. The most decision-relevant constraint (not an edit anchor) is front-and-center rather than buried.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does reasonably well (signatures, methods, type definitions, line ranges). Minor gaps remain around output shape details and behavior on unsupported languages or empty files, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so all three parameters (root, file_path, exported_only) are already documented, including the worktree caveat for root. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get detailed function signatures, class methods, and type definitions of a specific file') and adds a clear scope qualifier ('WITHOUT reading the full body'). An agent can distinguish this from body-reading siblings like search/grep/exact_references purely from the description.

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

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

Explicitly routes the agent: this tool is for API surface, and 'use context(targets:[{file,start,end}]) for source text before editing' names the alternative and the condition that selects it. It also warns against using the output as an edit anchor, which is a concrete when-not rule.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to restate the safety profile. It adds real context beyond them by showing that this is a composite aggregation across the index, memory graph, and git working tree, so the agent knows one call replaces many. It does not address staleness, cost, or whether reading git state affects anything, which keeps it below a 5.

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 short sentences, front-loaded with the purpose, then the payload, then the usage trigger. No redundant or filler text.

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

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

There is no output schema, so the description's enumeration of returned data carries the return-value burden well. Parameters are covered at 100% in the schema, and the annotations cover safety, so nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100%, and both parameters (root, format) are already documented in the schema, including the nuanced guidance for linked worktrees and subagents. The description adds nothing about parameters, so the baseline 3 applies.

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

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

The description names a specific verb ("Returns") and enumerates the exact resources: file counts, index state, memory graph stats, git branch, uncommitted changes, recent commits. That enumeration clearly separates it from siblings such as efficiency_report or reindex, which cover subsets of these areas.

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?

"One call for complete situational awareness at the start of a session" gives a clear trigger context for calling it. It does not name a when-not condition or point to alternatives, so it falls short of the explicit routing that a 5 requires.

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 description adds substantial behavioral flavor by detailing the complexity of the output (e.g., 'ranked files,' 'risks'). This context goes beyond the basic safety guaranteed by the annotations (readOnlyHint: true) and gives the agent a better idea of the internal data aggregation occurring.

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 definition is a single, highly dense sentence that front-loads the entire value proposition. There is zero wasted language, and the structure is maximally 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 100% schema coverage, the description provides the necessary conceptual framework and intent. It tells the agent *why* all those complex parameters (like `preset` or `graph_hops`) exist, making the definition functionally 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?

Since the schema description coverage is 100%, the schema itself defines the semantics of the parameters (e.g., max_tokens, graph_hops). The description doesn't add critical meaning beyond what is structurally defined in the input 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 clearly defines the tool's function as assembling a complex, multi-component 'working set' (files, tests, memory, risks). It immediately distinguishes itself from granular sibling tools like search or grep by describing a holistic context-gathering operation.

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 sets a high-level context for usage, implying this tool is meant for high-level planning or synthesis before diving into granular tasks. While it doesn't explicitly state 'do not use search for this,' the scope of the description strongly guides the agent toward this specific, comprehensive use case.

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

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

Annotations already declare readOnly/ idempotent/ non-destructive/ closed-world, so safety is covered. The description adds genuine behavioral context beyond them: the files-vs-task precedence rule and the post-edit sequencing. It is silent on output shape and on rate/cost characteristics of inspecting up to max_files files, which keeps it below 5.

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 filler, with the workflow trigger front-loaded before the parameter-selection rule. Every clause carries decision-relevant 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 read-only recommender with no output schema, this is nearly sufficient: the agent knows when to call it and how to bias it. The gaps are minor but real — it never describes what a 'validation check and command' result looks like, and it omits the required context that subagents must pass their own worktree root.

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

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

Schema description coverage is 100%, so the baseline is 3; the description's only parameter guidance (files precedence over task inference) is a near-restatement of what the files property already documents. Neither 'root' (worktree requirement) nor 'max_files'/'format' get added meaning in 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?

States a concrete verb+resource: 'recommend the most relevant validation checks and commands', which correctly frames this as a recommender rather than an executor despite the 'validate' name. It also anchors itself in the workflow ('After edit_scope'). It does not distinguish itself from siblings like blast_radius or explain, which could plausibly overlap.

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

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

Gives clear trigger context ('After edit_scope') and a selection heuristic for the ambiguous case ('Pass files when you already know what changed; they take precedence over task inference'). No explicit when-not-to-use or named alternative sibling, so it stops short of a 5.

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