trace-mcp

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

Beyond the readOnly/idempotent annotations, the description explains that the tool delegates to other tools, can invoke deferred tools without load_tools, enforces tools.exclude as a hard restriction, and documents the JSON return shape. This adds meaningful behavioral context not present in 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?

Three dense sentences cover purpose, use case, restrictions, read-only behavior, and return shape. Every sentence earns its place and key information 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?

Despite having no output schema, the description provides the return format. The schema covers parameter validation, annotations cover safety, and the description covers usage, restrictions, and batching intent. Nothing essential for an agent to call this 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?

The input schema already fully documents the 'calls' parameter with item schemas and min/max constraints, so the baseline is 3. The description adds value with concrete usage examples and clarifies that deferred tool names are acceptable, going slightly beyond schema-only information.

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 states a specific verb ('Execute multiple trace-mcp tools in a single MCP request') and distinguishes itself from siblings by enabling batched dispatch, including deferred tools. It is immediately clear what this tool does and how it differs from individual tools like get_outline or 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?

Explicitly says 'Use to reduce round-trips when you need several independent queries,' gives concrete examples, and clarifies when a tool is still not callable ('tools.exclude stays a hard restriction'). This gives clear when-to-use and when-not-to-use 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behaviors: read-only status, the JSON return shape, the 50-item page cap, total counting, truncation, and the phantom-god-node filtering semantics. This is much richer than merely repeating annotation flags.

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

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

The description is compact and front-loaded, with every clause earning its place. It covers purpose, alternatives, edge-case filtering, read-only status, and return shape without fluff or redundant schema 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?

For a read-only query tool with no output schema, the description compensates fully by specifying the response structure, pagination behavior, and filtering caveat. It also names the relevant sibling tools, making it complete for an agent deciding whether and how to call it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains the ambiguous-filter behavior, the token savings of detail_level='minimal', and the default/limit semantics. It does not clarify how fqn, file_path, and symbol_id interact (e.g., mutual exclusivity), but overall it meaningfully extends 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 opens with a specific, unambiguous definition: 'Find all references to a symbol or file (imports, calls, renders, dispatches).' It also distinguishes itself from Grep and sibling tools by emphasizing semantic vs text matches, so an agent can clearly tell this tool apart from search_text and get_call_graph.

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 routing guidance: 'Use instead of Grep for symbol usages — semantic, not text matches. For raw text use search_text; for a bidirectional call graph use get_call_graph.' This tells the agent both when to use this tool and which alternatives to choose in different situations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces 'Read-only'. More importantly, it adds non-obvious behavior: branches keep their direction, depth 2 means callers of callers and callees of callees, and the JSON response shape is provided. A small gap is unspecified behavior when neither fqn nor symbol_id is provided.

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 opens with the core behavior, immediately explains depth semantics, provides an explicit alternative, and closes with output format. Every sentence earns its place with no redundancy or 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?

The tool is well covered: purpose, usage alternative, depth behavior, read-only safety, and return structure are all present, and annotations cover the safety profile. The main omission is that no parameter is required in the schema while the description assumes a symbol is centered, leaving the fqn-or-symbol_id contract implicit.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by explaining what depth means concretely ('callers of callers, callees of callees') and reinforcing the bidirectional traversal. It does not clarify how fqn and symbol_id relate or take precedence, but the main parameter semantics are enriched.

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 is specific: it names the exact operation ('Build a bidirectional call graph centered on a symbol'), clarifies both call directions, and explains depth semantics. It also distinguishes itself from find_usages, making the tool's unique purpose immediately clear.

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 states when to use the tool ('Use to understand control flow through a function') and when not to, directing the agent to the correct alternative ('For flat list of all references use find_usages instead'). This is strong routing guidance among sibling tools.

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

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

Annotations already mark the tool read-only and idempotent, and the description explicitly states 'Read-only.' It adds useful behavioral detail beyond annotations: paging via compact, bundle recall semantics, and the returned JSON shape. It doesn't overstate side effects or contradict the safety hints.

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 and front-loaded; the first sentence states the core value, and later sentences cover usage, alternatives, paging, and output. Minor terseness like 'compact pages results; bundle recalls' could be clearer, but there is 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 complex 9-parameter tool with no output schema, the description does enough by summarizing the report contents and the main return fields. It does not fully explain how the multiple locator params (fqn, symbol_id, file_path, symbol_ids) interact or what happens with no params, leaving a small gap in an otherwise complete 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 description coverage is 100%, so the structured parameters already define fqn, depth, bundle, symbol_ids, max_dependents, decorator_filter, etc. The description adds guidance for symbol_ids as a diff-aware scope and mentions compact/bundle, but it does not materially enrich the parameters beyond the schema, so the 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 defines a concrete deliverable ('Full change impact report') and enumerates its contents: risk score, mitigations, breaking-change detection, enriched dependents, module groups, affected tests, and co-change hidden couplings. It also contrasts itself with get_call_graph, so an agent can distinguish it from the closest sibling.

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

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

It gives an explicit trigger ('Use before modifying code'), scoping advice ('Pass symbol_ids to scope to changed symbols'), and routes quick risk checks to assess_change_risk and call-graph queries to get_call_graph. However, assess_change_risk is not present in the provided sibling list, which slightly weakens the referral; still, the conditions of use are 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?

Annotations already carry readOnlyHint=true and idempotentHint=true, and the description's 'Read-only' agrees with them rather than contradicting them. The description adds genuine behavior beyond annotations: token-budget packing, shared-import deduplication for batch queries, and the exact return shape (primary, imports, token_usage). It loses a point because the 'Returns JSON' claim ignores the markdown output_format option, and truncation/error behavior when the budget is exceeded is undisclosed.

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 tight sentences, each earning its place: function, batch/dedup semantics, routing to the sibling tool, and return shape. The core capability is front-loaded in the first clause with zero filler.

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

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

For a 6-parameter read-only tool with no output schema, the description covers the essentials: return shape, token budget behavior, batch semantics, and the lighter alternative. Gaps remain at the edges — the interplay between fqn/symbol_id/symbol_ids and behavior when the token budget is exceeded — but the per-parameter schema descriptions and rich annotations carry much of that load.

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; the schema already documents all six parameters. The description earns an extra point by adding intent behind key parameters: 'packed within a token budget' clarifies the purpose of token_budget, and 'batch queries with shared-import deduplication' gives symbol_ids behavioral meaning beyond its bare listing.

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-object pair — 'Get a symbol's source code + its import dependencies + optional callers' — making the tool's function unmistakable. It also explicitly differentiates itself from get_symbol, its closest sibling, by describing what this tool bundles that get_symbol does not.

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 routing rules: 'Use instead of chaining get_symbol calls' for import-heavy or batch needs, and 'For a single symbol without imports, use get_symbol — lighter' as the exclusion condition with the alternative named. This is exactly the when/when-not guidance this dimension 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description adds value by specifying the data source (manifests), the read-only nature, and the exact return shape { detected, covered, gaps }. This goes beyond the structured annotations without contradicting them.

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

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

The description is compact and front-loaded with the core purpose, followed by the read-only trait and return shape. Every sentence earns its place, with no redundant elaboration.

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

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

For a zero-parameter, read-only report with no output schema, the description is complete: it explains what data is gathered, from where, and what the JSON response contains. An agent has enough information to invoke and interpret 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?

The tool has zero parameters, so the baseline is 4. The description provides enough context about the returned fields to make the no-argument call understandable, and there is no parameter documentation 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 identifies the tool as producing a technology profile with detected frameworks/ORMs/UI libs and coverage gaps, which is specific and not a tautology. It distinguishes the report's focus on plugin coverage from siblings like get_optimization_report or get_usage_trends, though it does not explicitly name any sibling.

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

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

Usage context is implied rather than stated: an agent can infer this tool is for inspecting project technology coverage and gaps, but there is no explicit 'use when' guidance or mention of alternatives. No exclusion criteria are provided.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing that external type-checkers are executed and that results are mapped to enclosing AST symbols. It also explicitly repeats the read-only trait, consistent with 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?

The description is a single sentence with no filler. Every clause carries meaning: the action, the specific checkers, the result transformation, and the safety characteristic.

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 no output schema, the description gives a useful sense of what happens and what the result is about (errors mapped to AST symbols). Parameter details are fully covered by the schema. It stops short of describing the exact return shape or the effect of reduce_output, but it is adequate for selection and invocation.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description adds minimal parameter meaning beyond listing the same type-checker names found in the enum, so the 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 uses a specific verb and resource: execute type-checkers (tsc, mypy, pyright) and map errors to enclosing AST symbols. It clearly identifies what the tool does, even though it does not explicitly contrast itself with 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?

Usage context is implied: an agent can infer to use this tool when type-checking diagnostics are needed. However, there is no explicit guidance about when to choose this over alternatives like get_index_health, get_coverage_report, or get_optimization_report, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so that baseline is covered. The description adds valuable non-obvious behavior: timeout behavior ('Capped by memory.recall.timeoutMs (default 5000ms); on timeout returns { items: [], token_usage, degraded: true }'), which is not present in annotations or schema. It also states read-only and return format, adding context 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?

The description is efficient: first sentence states purpose, second gives usage and alternatives, third states read-only and return format, fourth adds output_format nuance, fifth covers timeout behavior. Each sentence earns its place, though the timeout detail adds length. It is appropriately sized for the tool's complexity and well 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?

With no output schema, the description must explain return values, and it does: 'Returns JSON (default) or Markdown: { items: [{ symbol_id, name, file, source, score }], token_usage } | { content: "...markdown..." }.' It also covers the timeout degraded response. It doesn't mention rate limits or permissions, but those are not critical given read-only annotations. The description is complete enough 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 100% (all 4 parameters have descriptions), so the baseline is 3. The description does mention token_budget ('token budget') and output_format ('toon'), but these are already fully documented in the schema with comparable detail. It adds no new semantic meaning for parameters 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 opens with a specific verb and resource ('Search code by keyword/topic → returns ranked source snippets within a token budget'), making the core function immediately clear. It also differentiates from siblings by naming get_task_context and search with their distinct use cases, so an agent can tell them apart without opening schemas.

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 states when to use this tool ('when you need to READ actual code for a concept or feature') and gives alternatives with guidance: 'For structured task context with tests and entry points use get_task_context instead; for symbol metadata without source use search.' This satisfies the explicit when/when-not/alternative criterion.

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 carry readOnly/idempotent/destructive safety, and the description reinforces this and adds genuinely new behavioral context: the empty-index next_steps behavior, the projectRoot inclusion, and the exact JSON envelope. No contradiction with 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?

The description is two sentences: a front-loaded purpose statement and a state-sensitive behavior note, plus a compact return-shape hint. Every sentence contributes information relevant to correct invocation.

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 full burden of explaining return values, and it enumerates the JSON fields. It also explains empty-index behavior and provides follow-up tool names, making it complete for a zero-parameter read-only health check.

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

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

The tool has zero parameters, so the schema leaves nothing to document and the baseline is 4. The description correctly adds no parameter syntax and instead uses the space to describe the return payload.

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 action-resource pair ('Get index status, statistics, health, and pipeline progress') and spells out the payload, so an agent knows exactly what the tool reports. It is distinct in subject matter from siblings like get_session_stats, but it does not explicitly name or contrast those alternatives, so it stops just short of top 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?

It gives a clear invocation condition: 'Use to verify the index is ready before running queries.' It also hints at routing to list_projects and call_project_tool when the index is empty. No explicit when-not-to-use or alternative health tools are named, so it misses the top criterion.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety type is covered. The description adds value beyond annotations by describing the JSON return format ({ patterns: [{ type, description, savings_estimate }], total_waste }) and stating it 'Provides savings estimates.' No contradiction with 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?

Three sentences, each earning its place: the first names specific waste patterns, the second covers read-only safety and savings estimates, the third gives the return shape and sibling routing. 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?

For a simple one-optional-parameter tool with no output schema, the description provides the return JSON structure, the tool's scope, and explicit sibling alternatives. Nothing needed to invoke it correctly is missing.

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

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

The input schema covers 100% of the single parameter, including enum values and default. The description does not add any parameter-level detail, so the schema carries the full burden. 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 opens with a specific verb and resource: 'Detect token waste patterns in AI agent sessions,' then lists concrete pattern types (repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools). It also provides the return shape and distinguishes itself from siblings by naming their use cases.

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 to alternatives with conditions: 'For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings.' This tells the agent when not to use this tool and which sibling to pick instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral value beyond annotations: the nesting expansion semantics (parentId + depth, max 3, default ≥100 LOC), the 'Read-only' confirmation, and the explicit return JSON shape. No contradiction with 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?

Purpose is front-loaded in the first sentence. The description is dense but every clause earns its place: cost comparison, follow-up workflow, nesting behavior, return format, and toon support. Slightly long but structured well with a clear return-shape example that helps an agent parse the output.

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 outline tool with 5 parameters and 2 enums, the description covers the core purpose, cost benefit, follow-up routing, nesting semantics, return structure, and output formats. Minor gaps: no mention of error behavior (e.g., file-not-found or unsupported language), but for a non-destructive tool with strong annotation coverage this is reasonably complete.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema carries the parameter documentation. The description adds some marginal value — clarifying the toon output format support, nesting depth cap, and default LOC threshold — but these mostly restate or lightly extend what the schema already covers. Does not fully compensate beyond the 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?

States a specific verb+resource ('Get all symbols for a file') with a precise scope qualifier ('signatures only, no bodies'), and distinguishes itself from the sibling get_symbol by naming the follow-up workflow. An agent can immediately tell what this does and how it differs from its sibling.

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

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

Explicitly positions the tool: 'cheaper than Read for understanding a file before editing' tells when to prefer it, and 'Follow up with get_symbol to read one symbol's source' defines the recommended workflow. The detail_level schema description also guides when to use 'minimal' ('Use to pick a candidate before get_symbol'). Clear usage context with no ambiguity.

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 read-only, idempotent, and non-destructive behavior. The description reinforces this with 'Read-only' and adds the return JSON shape (active_preset, registered_tools, etc.), disclosing what the agent will receive. This extra context goes beyond the annotations.

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

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

Two concise sentences, front-loaded with the core purpose and followed by a compact JSON key listing. Every sentence adds value; 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?

For a zero-parameter read-only introspection tool, the description is complete: it states what the tool reports, the read-only nature, and the exact response fields. There is no output schema, so the description carries the burden of return-value disclosure and does so adequately.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Baseline for zero-parameter tools is 4; the description need not document parameter semantics because there are none.

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 ('Show') and enumerates the exact resources: active tool preset, available presets, registered tools, and deferred tools. It clearly differentiates this introspection tool from the many sibling get_* tools and explicitly connects deferred tools to load_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 makes the tool's context clear: use it to inspect tool registration and preset state. It mentions that deferred tools are loadable via load_tools, providing adjacent guidance, though it does not explicitly state when not to use it or name a directly competing alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond that: it confirms 'no side effects', suggests a cheap orientation call pattern, and specifies the return shape. This exceeds the annotation baseline without contradicting it.

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 concise sentences front-load the core behavior and return shape. The 'Read-only, no side effects' clause is slightly redundant with annotations, but the rest earns its place by adding usage guidance and output fields.

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 complete for a simple, optional-parameter read-only tool. It names the return JSON fields, gives a recommended invocation, and explains the tool's role. It could mention symbolCount semantics or potential costs, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents the only parameter. The description adds the session-start use case for summary_only=true, which is helpful, but it does not add meaning beyond what the parameter description already conveys.

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 ('Get') and resource ('project map') and enumerates contents (frameworks, languages, file counts, structure). It does not explicitly distinguish itself from sibling tools like get_outline or get_context_bundle, but the term 'project map' combined with the described fields is clear enough for an agent to understand what it returns.

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 clear usage context: call at session start with summary_only=true to orient before diving into code, and use instead of manual ls/find. It does not discuss when not to use it or name alternative tools, but the intended scenario is explicit and actionable.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the description does not need to repeat safety traits. It adds useful behavioral context by describing the exact return shape: files with raw_tokens, compact_tokens, savings, and total_savings. This is valuable because there is no output schema.

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

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

The description is compact and front-loaded with the core purpose, then clearly differentiates the tool from a sibling, and finishes with the return JSON shape. Every sentence earns its place 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 simple read-only tool with one optional parameter, the description is complete: it explains what the tool does, when to use it, what it returns, and how it differs from the closest sibling. No important context is missing.

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

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

Schema coverage is 100%, and the only parameter, period, is fully documented in the schema with an enum and default of 'week'. The description does not add parameter-level meaning beyond the schema, which is expected given high 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's purpose with a specific verb and resource: 'A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads.' It also specifies the per-file breakdown, making it easy to distinguish from other reporting tools like get_optimization_report.

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 directs when to use this tool versus an alternative: 'For pattern-based waste detection use get_optimization_report instead.' This provides a clear exclusion and alternative, so an agent can route correctly without opening the schema.

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

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

Annotations already mark it read-only and idempotent; the description adds beyond that by noting it 'Parses Claude Code JSONL logs automatically' and specifies the exact return shape. It does not over-disclose or contradict 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?

Four short, information-dense sentences. The main action is first, then a behavioral note, then alternative routing, then the return format. 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?

For a read-only analytics tool with no output schema, the description compensates by stating the return JSON structure and parsing behavior. It lacks explicit prerequisites like 'log files must exist,' but the parameters and routing are sufficiently covered.

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 both 'period' and 'session_id' described in the schema. The description does not add parameter-specific semantics, but the schema fully covers it, so a 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 uses a specific verb ('Analyze') with a clear resource ('AI agent session logs') and enumerates the concrete outputs (token usage, cost breakdown, top files, models). It also distinguishes itself from sibling tools by naming what it is not for.

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 states when to use alternatives: 'For waste detection use get_optimization_report; for cost trends use get_usage_trends.' This gives clear routing guidance and prevents mis-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?

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description is not burdened with those disclosures. It adds valuable behavioral detail by specifying the returned JSON structure—session with latency_per_tool, cumulative, dedup_saved_tokens, and report—which is especially useful given there is no output schema.

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

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

The description is a single, front-loaded sentence that leads with the purpose and follows with a compact return layout. It contains no filler, though the inline JSON example is somewhat dense and could be slightly clearer as a structured list.

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

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

For a no-parameter, read-only metrics tool, the description covers purpose, scope, and output shape adequately. It does not clarify how 'session' is defined or when a sibling analytics tool would be more appropriate, leaving a small but meaningful gap for an agent selecting among similar 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?

There are zero parameters and the schema coverage is trivially complete, so the baseline is 4. The description reinforces that the tool is parameterless by scoping everything to 'this session,' but it does not need to add more parameter-level meaning.

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 identifies the resource ('this session') and the concrete purpose ('Token savings stats'), and enumerates the metrics returned: per-tool call counts, token savings, reduction percentage, dedup savings, and latency percentiles/error rate. It is clear and specific, but it does not explicitly distinguish itself from overlapping siblings like get_session_analytics.

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 this session' implies that the tool should be used when an agent wants token-savings metrics for the current session, which provides some usage context. However, the description gives no explicit guidance about when not to use it or how it compares to alternatives such as get_session_analytics, get_optimization_report, or get_real_savings.

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 readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: it returns only the symbol rather than the whole file and provides the response shape. It does not mention the verify_against_git comparison behavior or git_mismatch in the return payload, though that is documented in the parameter schema, so this is a minor omission rather than a contradiction.

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

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

The description is compact and front-loaded with the core purpose. It packs usage guidance, behavioral scope, read-only information, and return shape into three sentences with 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?

The description provides a return shape despite the lack of an output schema and clearly routes between siblings. However, it does not explicitly state that exactly one of symbol_id or fqn is required, and the verify_against_git behavior only lives in the schema. These are real but minor gaps given the otherwise rich annotation and schema 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%, so the schema already explains each parameter. The description reinforces that either symbol_id or fqn can be used, but it does not add significant meaning beyond the schema for max_lines or verify_against_git. This matches the baseline for fully covered schema 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 opens with a specific verb and resource: 'Look up a symbol by symbol_id or FQN and return its source code.' It clearly distinguishes the tool from Read and get_context_bundle, so an agent can immediately understand what it does and which sibling it is not.

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: 'Use instead of Read when you need one specific function/class/method' and 'For multiple symbols at once, prefer get_context_bundle.' This tells the agent when to select this tool and when to select a sibling.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: outputs are adapted by task type, it returns JSON or Markdown, and it consolidates what would otherwise require multiple tools. It doesn't go into response structure or cost details, but it meaningfully exceeds what annotations alone provide.

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

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

Four tightly packed sentences with zero filler. The most actionable instruction ('Use as your FIRST call') is front-loaded, and both the sibling differentiation and return format are stated in a single breath.

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, a rich annotation set, and no output schema, the description covers nearly everything an agent needs: purpose, timing, alternatives, content delivered, and output format. It would be complete with a hint about response fields beyond 'execution paths, tests, entry points', but the schema covers the parameters and the description covers usage 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%, so the schema already documents all six parameters thoroughly in terms of enums, defaults, and token impact. The description only lightly references output_format ('Returns JSON (default) or Markdown') and the task type adaptation, adding marginal value beyond the schema's own param 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 opens with a concrete, specific purpose: 'All-in-one context for starting a dev task' and enumerates the included content (execution paths, tests, entry points). It explicitly differentiates from the sibling tool get_feature_context, making the intent unmistakable against the surrounding toolset.

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 when-to-use guidance: 'Use as your FIRST call when beginning any new task.' It even names the workflow it replaces ('search → get_symbol → Read') and points to the correct alternative for narrower lookups (get_feature_context). This is model behavior for routing an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only nature disclosed in the description is consistent but not new. The description adds value by revealing the exact return shape (JSON with days, daily array, totals) and the daily time-series granularity, which the annotations do not convey.

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

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

Three dense sentences with no fluff. The main purpose is front-loaded, the use case and alternative follow immediately, and the return format is compactly summarized. 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?

The tool has only one optional parameter, no output schema, and low complexity. The description covers the purpose, the use case, the alternative tool, the safety profile is in annotations, and the return JSON shape is fully specified. There is nothing an agent needs to call this correctly that is missing.

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

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

Schema coverage is 100% with the parameter description already stating it is the number of days and the default of 30. The tool description adds no additional semantics for the 'days' parameter, but it does corroborate that the output contains a 'days' field, which is minimal extra context. Baseline 3 is appropriate.

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

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

States a specific verb and resource: produces a daily token usage time-series with sessions, tokens, estimated cost, and tool calls. The phrase 'For spotting cost spikes' clarifies the intended use, and it explicitly differentiates itself from get_session_analytics, so an agent can distinguish it from siblings without opening schemas.

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 an explicit use case ('For spotting cost spikes') and names the alternative when a different need exists ('For detailed session breakdown use get_session_analytics instead'). This gives clear selection criteria with no inference required.

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 discloses key behavioral traits beyond annotations: the decision remains for historical queries, is excluded from active queries, mutates the decision store, and is idempotent. It also specifies the return shape. This adds meaningful context beyond the annotations.

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

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

Four short sentences, each carrying useful information: the action, the historical/active distinction, the usage condition, and the return format. No filler or redundancy; the most important purpose 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?

Given the absence of an output schema, the returned JSON is explicitly stated. The mutation, idempotency, and retention behavior are all covered. The tool's effect on the knowledge graph and query behavior is clear, making it complete for the agent to invoke 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 both id and valid_until are documented there. The description itself does not add much parameter-level meaning beyond the schema, but it correctly implies valid_until is part of the return object. 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 uses a specific verb ('Mark as no longer valid'), names the resource ('decision'), and clearly defines the outcome: the decision stays in the knowledge graph for historical queries but is excluded from active queries. This differentiates it from siblings like remember_decision and query_decisions.

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 states when to use the tool: 'Use when a decision is superseded or reversed.' It does not name alternative tools or give when-not-to-use guidance, but the usage context is clear enough for an agent to select it correctly.

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 discloses behavior beyond the annotations: it emits notifications/tools/list_changed, returns loaded tools' schemas, and remains usable even if the client ignores the notification (via batch). It also lists the exact JSON response fields, giving the agent a clear model of side effects and results.

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 efficient: it front-loads the core purpose, then covers invocation modes, side effects, and return shape in a few sentences. No sentence is filler, and the structure makes the most important information immediately visible.

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

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

Despite having no output schema, the description names all return fields and explains the notification behavior and batch fallback. Combined with the annotations signaling read-only/idempotent behavior, the description gives the agent enough context to invoke the tool correctly and interpret its response.

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

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

The input schema already describes both parameters with 100% coverage, including the union behavior between `tools` and `preset`. The description adds value by specifying the no-arguments listing behavior, which is a parameter-level semantic not captured by the schema 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 a specific verb ('load') with a clear resource: deferred tools for the session's preset, by preset name and/or explicit names. It also distinguishes the no-argument listing mode, making the tool's purpose unambiguous and distinct from siblings like get_preset_info.

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: call with no arguments to list deferred tools, or pass preset/tool names to load them. It does not explicitly mention alternatives or when-not-to-use conditions, but the provided context is sufficient for typical invocation.

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 explicitly states "Mutates the decision store; idempotent," and "Skips already-mined sessions unless force=true." This adds meaningful behavioral context beyond the annotations, specifying exactly what side effect occurs, the idempotency guarantee, and the skip behavior. It aligns with idempotentHint=true and readOnlyHint=false, with no contradictions.

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 dense: two sentences carrying purpose, strategy tradeoffs, behavioral notes, and return shape. It front-loads the core purpose, uses structured lists for strategies, and contains no filler. Every clause 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 tool with 7 optional parameters, no output schema, and moderate complexity, the description supplies the return JSON structure, strategy cost/recall tradeoffs, mutation behavior, and skip logic. Combined with 100% schema coverage, an agent has everything needed to select and invoke 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 coverage is 100%, and the schema already documents all 7 parameters with detailed descriptions, including enum choices, thresholds, and the incremental_cursor override. The description merely summarizes strategy and force, adding no new semantic information beyond what the schema already provides. 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 opens with a specific verb and resource: "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences." This clearly distinguishes it from sibling read/query tools like search and query_decisions by stating it processes session logs and mutates the decision store. The purpose is unambiguous.

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

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

The description gives concrete guidance on strategy selection (regex vs llm vs hybrid) and explains the skip-already-mined behavior with force=true. However, it never explicitly names alternatives or states when NOT to use this tool (e.g., "use query_decisions instead to read stored decisions"). Context is clear but exclusions are absent.

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 mark this read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It adds behavioral context by explaining the tool's combined search/journal/risk mechanism and its role in preventing empty-result hallucinations, going beyond what annotations alone convey.

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 information-dense and mostly front-loaded, starting with the primary purpose and usage call-to-action. The long enumeration of combined capabilities and the slight redundancy between 'Returns...' and 'Returns JSON: {...}' keep it from being perfectly concise, but every sentence contributes needed 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?

Despite the absence of an output schema, the description states the JSON shape, the verdict values, the provenance of ranked targets, scaffold hints, and recommended next steps. Combined with the explicit usage instruction and alternative tool pointer, an agent has what it needs to invoke the tool correctly on a new task.

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 each parameter already has a clear description with defaults and constraints. The tool description does not meaningfully add parameter-level guidance, so it meets the baseline but does not exceed it.

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 'Opening-move router for new tasks' and lists a concrete deliverable set: verdict, confidence, ranked targets with provenance, scaffold hints, and recommended next tool calls. It also explicitly distinguishes itself from get_task_context, so an agent can select it correctly among siblings.

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 states exactly when to use it: 'Call this FIRST on a new task to break the empty-result hallucination chain.' It also names the alternative, get_task_context, and the condition for preferring that instead ('broader task context with source code'), giving clear, actionable routing 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 annotations already declare read-only, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavior: defaults to approved decisions, returns JSON with specific fields, supports the 'toon' output format for token savings, and explains the verify flag's effect on stale rows. It could further clarify the interpretation of 'active' for as_of and the fallback behavior of 'heat', but these are minor.

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 paragraph that front-loads the purpose and key filters, then covers defaults, output format, and read-only nature. It is fairly concise, but the field list in the output JSON is a bit dense and could be trimmed without losing value. Still, it earns its sentences with concrete details.

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

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

For a complex tool with 17 parameters, the description effectively summarizes the major filter categories, defaults, output format, and read-only nature. The schema covers individual parameter semantics, so the description need not repeat every detail. The mention of the toon format is a nice touch, given the presence of output_format. Complete for the intended use.

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 has 100% coverage, so the baseline is 3. The description adds context beyond the schema: it explains that decisions are part of a knowledge graph, mentions the 'toon' output format's benefit, and clarifies that 'verify' defaults to true (schema only lists the flag). This goes slightly beyond the schema, justifying a 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?

The description clearly states the tool queries the decision knowledge graph, lists the filter dimensions (type, subproject, code symbol, file path, tag, time), and explains the core use case (answering 'why was this architecture chosen?'). It is specific about the resource and distinguishes it from siblings like search, get_symbol, and remember_decision.

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 (querying decision records) and mentions defaults (approved decisions, include_pending/review_status for other tiers), but it does not explicitly state when not to use it or name alternative tools for similar purposes. The 'read-only' note and the output format hint provide context, but exclusions are 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?

Annotations already carry idempotentHint=true, readOnlyHint=false, and destructiveHint=false; the description confirms these ('Mutates the index; idempotent') without contradicting them. It adds real value beyond annotations: search-cache invalidation, duplicate-symbol flagging, the once-per-file reporting constraint, and the exact JSON return shape. Minor gap: no mention of error behavior when the file path is invalid.

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

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

Front-loaded with the core purpose, then usage guidance, then the duplication caveat, then the return format. Each sentence earns its place and the information is ordered by importance. Slightly dense, but not padded — no redundancy with the schema or annotations.

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?

Complete for a single-parameter mutation tool: it covers what happens (reindex, cache invalidation), when to use it (after Edit/Write, lighter than full reindex), its idempotency, a caveat (duplication warnings, reported once per file), and the return structure in the absence of an output schema. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% — the single parameter file_path is fully documented as 'Relative path to the edited file.' The description references the file only implicitly through the return JSON ({ file }), adding no semantic detail beyond the schema. Baseline 3 is appropriate since the schema carries the parameter meaning.

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 ('Notify trace-mcp that a file was edited'), and precisely scopes what happens: reindex the single file and invalidate search caches. It clearly differentiates from the read-oriented siblings (get_index_health, get_symbol, search) by being a mutation, and positions itself as the lightweight single-file counterpart to a full reindex.

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

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

Gives explicit when-to-use guidance: 'Call after Edit/Write to keep index fresh — much lighter than full reindex.' It names the alternative (full reindex) and the deciding condition. It also routes a follow-up question to a sibling ('check_duplication re-asks'), so an agent knows which tool to pick next.

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

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

Annotations only cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description goes well beyond them: confidence-based routing with three explicit outcomes (immediate graph entry, human review queue, silent drop without persistence), plus per-session dedup and rate limiting. This is exactly the behavioral detail an agent needs before writing.

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

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

Front-loaded with the core action, then routing behavior, then constraints, then alternatives, then return shape. Dense but every sentence carries distinct information with no 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?

For a 9-parameter mutation tool with no output schema, the description supplies the missing return shape ({ id, review_status, confidence, deduplicated? }), the persistence semantics, and the dedup/rate-limit constraints. An agent has everything needed to call it correctly and predict the outcome.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters including session_id's dedup/rate-limit role. The description restates session-level dedup but adds no new syntax or meaning for tags, file_path, symbol_id, git_branch, or service_name, so the baseline 3 applies.

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

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

States a specific verb+resource ("write into the decision knowledge graph") and immediately scopes it as a live, in-session write. It explicitly distinguishes itself from the two nearest siblings, add_decision and mine_sessions, so an agent can route without opening schemas.

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

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

Gives explicit when-to-use ("during a session to capture decisions in real time") plus named alternatives for the two adjacent cases: add_decision for manual high-confidence writes, mine_sessions for post-hoc log extraction. Nothing is left to inference.

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

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

Annotations already convey read-only/idempotent/non-destructive traits. The description adds value by disclosing the JSON return shape, mode-specific shape when mode!=single, and the toon output format. This goes beyond annotation coverage and helps the agent understand what to expect.

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: purpose, exclusions, and return shape in three sentences. Minor redundancy exists, such as restating 'Read-only' despite annotations and noting output_format already in the schema, but the overall size is appropriate.

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 20-parameter tool with no output schema, but the schema itself is richly documented and annotations cover safety. The description supplies the missing output contract and key routing guidance, leaving only deeper mode-selection advice to the schema's own explanations.

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 adds minimal per-parameter meaning beyond the schema—mainly highlighting output_format toon—but the schema already documents all parameters thoroughly.

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 states a specific verb and resource: 'Search symbols by name, kind, or text.' It explicitly distinguishes the tool from Grep and names the sibling alternatives search_text and find_usages, so an agent can tell them apart immediately.

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

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

Description gives explicit when-to-use guidance: use instead of Grep for functions, classes, methods, variables; use search_text for raw text/comment search; use find_usages for references to a known symbol. This clearly routes the agent to the correct alternative.

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

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

Annotations already declare read-only and idempotent, but the description adds substantial behavioral detail: it skips .env files (secrets never searched/returned), describes the return JSON shape and grouping behavior, and mentions the timeout parameter's purpose (caps catastrophic-backtracking regex). This goes beyond the annotations and provides context an agent needs.

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?

Although the description is lengthier than average, every sentence earns its place. It front-loads the purpose, then usage, then behavioral and return details, with no redundancy. The structure is logical and each sentence adds substantive information, making it efficient despite its length.

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 is remarkably complete. It covers the return JSON shape (since no output schema exists), usage scenarios, exclusions, alternatives, and even explains grouping and timeout behavior. An agent can confidently invoke this tool correctly without additional 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the 'grouping' parameter's trade-off ('hits grouped per file, so a long path is paid once') and the 'timeout_ms' rationale (caps catastrophic-backtracking regex). While not all parameters get extra semantics, the added context is valuable, earning a 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?

The description states a specific verb and resource ('Full-text search across all indexed files') and explicitly differentiates from the sibling 'search' by stating 'For symbol search (functions, classes) use search instead.' It also enumerates the types of content it targets (strings, comments, TODOs, config values, error messages), 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?

It gives explicit usage guidance: 'Use for finding strings, comments, TODOs, config values, error messages — anything not captured as a symbol.' It also specifies when not to use it (symbol search) and directs the agent to 'get_env_vars' for environment keys, covering exclusions and alternatives clearly.

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 confirms read-only behavior, consistent with the readOnlyHint/idempotentHint annotations, and adds a concrete response shape even without an output schema. It does not mention edge cases like rate limits or authentication, but these are less critical for a read-only onboarding helper.

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?

Every sentence earns its place: the onboarder identity is front-loaded, usage timing is clear, the alternative is named, and the JSON return shape is compactly listed. There is no filler or redundant schema 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?

For a zero-parameter read-only tool with no output schema, the description covers purpose, output fields, usage timing, and the relevant sibling. Nothing an agent needs to call this 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?

The tool has zero parameters, so schema coverage is trivially 100% and the baseline is 4. The description adds no parameter details because there are none; instead it clarifies what the no-input call returns, which is sufficient.

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 ('shows') and names the resource types it exposes: top imported files, connected symbols, language stats, and example tool calls. It also explicitly differentiates from get_project_map, so an agent can distinguish it from siblings without opening schemas.

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 states the exact condition for use — 'Call this first when exploring an unfamiliar project' — and names the alternative, get_project_map, for a structured project map. This gives clear when-to-use and when-not-to-use guidance with an explicit replacement.

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