trace-mcp

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

Annotations already signal readOnly and non-destructive. The description adds useful behavioral context beyond that: it delegates to other tools, is read-only, and returns a JSON structure of batch_results. This informs the agent of the delegation behavior and output shape without contradicting 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?

Three sentences, each earning its place: purpose, when to use, and return format. It is front-loaded and avoids fluf 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 tool with no output schema, the return JSON is described well, and the read-only/delegation behavior is stated. The description could also cover per-call error propagation or ordering guarantees, but these are minor given the tools's simple batch semantics and strong annotations.

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 satisfied; the description goes further by showing what kinds of calls to batch with examples like 'get_outline for 3 files' and 'search + get_symbol together.' This makes the calls parameter more tangible without repeating the schema details.

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

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

The description states a specific verb and resource: 'execute multiple trace-mcp tools in a single MCP request.' It clearly identifies the tool as a batching/composite operation, distinguishing it from the individual sibling tools by its aggregation behavior.

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 it: 'reduce round-trips when you need several independent queries' and gives concrete examles such as 'get_outline for 3 files, or search + get_symbol together.' It does not explicitly mention when not to use it, so it stops short of a 5, but the context is clear.

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

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

Annotations already declare read-only/idempotent behavior, and the description adds meaningful operational detail: the default dropping of weakly-grounded text_matched edges with the phantom god-node rationale, plus the exact JSON return shape. This goes well beyond 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?

The description is compact yet information-dense, front-loading the core purpose and usage guidance before behavioral details and return format. Every sentence adds operational value; there is no filler or repetition of schema content.

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

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

For a complex reference-finding tool with no output schema, the description supplies the return JSON shape, keys, optional ambiguity filter, and clear sibling differentiation. All five parameters are covered in the schema, and the description fills the remaining behavioral gaps needed 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 coverage is 100%, so baseline is 3. The description adds semantic context for include_ambiguous_text_matched ('weakly-grounded', 'phantom god-node filter') beyond what the schema states, and clarifies the intent of the return fields. It does not need to restate every parameter.

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

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

The description names a specific verb and resource ('Find all places that reference a symbol or file') and enumerates reference kinds ('imports, calls, renders, dispatches'). It distinguishes itself from sibling tools like Grep and get_call_graph without requiring schema inspection.

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

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

It explicitly says to use this tool instead of Grep for semantic symbol usages and directs users to get_call_graph for bidirectional call graphs. It also explains when to pass include_ambiguous_text_matched, leaving no ambiguity about tool 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's 'Read-only' is redundant but not harmful. The description adds genuine value by disclosing the bidirectional nature of the graph and the exact JSON return shape, which the annotations and schema do not convey. It does not go further to mention traversal cost or default depth behavior, but the schema already documents depth limits.

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 with no fluff: the first states the core function, the second gives the use case and alternative tool, and the third confirms read-only status and return format. Every sentence carries useful information and the key distinction from find_usages 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?

The tool has moderate complexity (two required identifiers, one optional depth parameter, no output schema), and the description provides the missing return format while the schema documents depth. The only notable gap is not explaining why both symbol_id and fqn are required or how they interact, which could leave an agent uncertain about how to populate both parameters. Overall, enough is present for confident invocation, but this small ambiguity prevents a perfect score.

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 does not add parameter-specific meaning beyond what the schema already provides for symbol_id and fqn. It implies the result centers on a symbol, but the relationship between symbol_id and fqn (both required) is not clarified in either the description or the schema, so it neither improves nor worsens 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?

The description uses a specific verb ('Build') and resource ('bidirectional call graph centered on a symbol'), and immediately clarifies semantics with the parenthetical 'who calls it + what it calls'. It also distinguishes itself from the sibling find_usages by describing the alternative as a flat list of all references, 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?

It states a clear purpose ('Use to understand control flow through a function') and gives an explicit when-not-to-use instruction with the named alternative ('For flat list of all references use find_usages instead'). This is direct routing guidance that leaves no ambiguity about tool 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 mark the tool as read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It adds behavioral value by describing diff-aware mode via symbol_ids and the top-level JSON return shape, helping the agent anticipate output and scope.

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, opening with 'Full change impact report' and then listing concrete outputs. Every sentence carries distinct signal: purpose, mode, usage timing, alternative, safety, and return shape, 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 complex analysis tool, the description covers purpose, when to use, alternative, read-only behavior, diff-aware mode, and a summary of the JSON response. It doesn't document every returned field, but the listed keys plus full schema coverage give enough context for correct invocation and interpretation.

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

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

Input schema coverage is 100%, so the schema already documents all 7 parameters. The description's mention of symbol_ids for diff-aware analysis adds slight context, but the schema already describes this behavior, so the description does not significantly elevate parameter understanding.

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

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

The description clearly states the tool produces a full change impact report, enumerating risk score, mitigations, breaking changes, enriched dependents, module groups, affected tests, and hidden couplings. It also explicitly distinguishes itself from assess_change_risk, making its purpose unmistakable even among sibling tools.

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

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

It gives an explicit usage directive: 'Use before modifying code to understand blast radius.' It also names a lighter alternative, assess_change_risk, for quick risk assessment, so an agent can decide when this heavier tool is warranted.

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 'Read-only' and adds useful context about shared-import deduplication, token-budget packing, and the JSON shape. It does not explain truncation or error behavior when the token budget is exceeded, but this is a minor gap given the annotation coverage.

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

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

The description is compact, front-loaded with the core function, and every sentence earns its place—covering scope, batch behavior, sibling routing, safety, and return format without 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?

With no output schema, the description provides a useful JSON skeleton and clear invocation guidance. It leaves some edge behavior implicit, such as how include_callers alters the response shape and what happens when the token budget is insufficient, but the schema and annotations cover most invocation details.

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 why batch queries and token_budget matter: they enable shared-import deduplication within a packed token budget.

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 operation (get) and resource (a symbol's source code, imports, and optional callers packed within a token budget). It also clearly distinguishes itself from get_symbol, naming the sibling and the difference in scope.

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

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

Explicitly says to use this instead of chaining get_symbol calls and gives the lighter-alternative condition: for a single symbol without imports, get_symbol is better. This is concrete, 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?

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?

Despite strong annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral detail: token budget behavior, output format variants, timeout cap with default value, and a degraded response shape on timeout. It also confirms the read-only nature, aligning with annotations. No 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 dense and front-loaded, with the core purpose and usage guidance first. It packs output shapes, timeout behavior, and alternatives into a compact block. Minor redundancy exists ('Read-only' repeats the annotation) and the toon reference is slightly tacked on, but overall 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?

With no output schema, the description properly explains return formats and the degraded timeout case. It covers tool selection, read-only semantics, token budget, and output options. Given the tool's moderate complexity and annotations already handling safety, nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100% and the schema already documents all four parameters, including defaults, enums, and constraints. The description reinforces token budget and output format behavior but does not add substantive per-parameter meaning 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 states a specific action ('Search code by keyword/topic'), a precise result ('ranked source snippets'), and an explicit constraint ('within a token budget'). It also distinguishes the tool from siblings by naming get_task_context and search as alternatives, 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?

It gives an explicit when-to-use condition ('when you need to READ actual code for a concept or feature') and clear routing instructions: use get_task_context for structured task context with tests and entry points, and search for symbol metadata without source. This is exactly the kind of differentiation agents need.

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 this with 'Read-only, no side effects.' It adds valuable context beyond annotations by describing the return format explicitly and mentioning pipeline progress (indexing, summarization, embedding). No contradictions with annotations exist.

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 (four sentences) and front-loads the core purpose. Every sentence adds useful information: purpose, safety, usage context, and return format. There is no fluff 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 parameterless, read-only health-check tool, the description is fully complete. It states what the tool does, when to use it, that it is safe, and exactly what JSON it returns. An agent has everything needed to decide whether to call it and interpret the result.

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

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

The tool has zero parameters, so the schema is empty. Per calibration, a baseline of 4 applies when there are no parameters, as there is nothing to document. The description does not need to add parameter detail.

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 ('Get'), a clear resource ('index status, statistics, health information, and pipeline progress'), and explicitly mentions the readiness check ('verify the index is ready before running queries'). This clearly distinguishes it from sibling tools like get_project_map or get_context_bundle, which serve different purposes.

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

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

The description provides clear usage context: 'Use to verify the index is ready before running queries.' This tells the agent when to invoke it. However, it does not explicitly mention alternatives or when not to use it, though the purpose is narrow enough that this is not a major gap.

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

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

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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: it is signatures-only, cheaper than Read, expands nested declarations with parentId+depth up to max 3, and specifies the exact JSON return 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?

The description is compact and front-loaded: purpose, use case, follow-up, nested behavior, read-only flag, return shape, and format note appear in a logical order. Every sentence earns its place; there is no filler or repetition of schema details.

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

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

Despite having no output schema, the description provides the full JSON return shape and all key behavioral constraints. Parameter semantics are covered by high schema coverage, and usage vs. alternatives is explicit. For a read-only listing tool this is complete enough 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the nested=true effect (expands large top-level symbols, default ≥100 LOC, max depth 3) and noting output_format 'toon' support, which goes slightly beyond the schema's per-parameter text.

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

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

The description states a specific verb+resource ('Get all symbols for a file') and immediately clarifies scope ('signatures only, no bodies'). It also distinguishes itself from the sibling get_symbol and from Read by noting it is cheaper for understanding a file before editing, which is strong 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?

The description explicitly says when to use this tool ('before editing' to understand a file, 'cheaper than Read') and names the follow-up alternative ('get_symbol') for reading a symbol's source. It also explains when nested expansion applies, giving clear practical usage direction.

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 cover read-only and idempotent behavior, and the description reinforces that with 'Read-only.' It adds context beyond the annotations by disclosing that it parses Claude Code JSONL logs automatically and by specifying the exact returned JSON keys, which is useful since 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 well-organized: purpose, input-format behavior, safety clarification, routing to siblings, and return shape. Each sentence earns its place, and the most important scope is front-loaded before the routing and return 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 read-only, two-parameter tool with a fully documented schema and helpful annotations, the description supplies all remaining contextual essentials: JSON output shape, automatic log parsing, and sibling routing. Nothing needed for correct invocation 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 parameter meaning is fully documented in the input schema for both session_id and period. The description mentions analysis dimensions and output fields but does not add parameter-specific semantics beyond what the schema already provides, so the baseline of 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: 'Analyze AI agent session logs' and then lists concrete outputs (token usage, cost breakdown by tool/server, top files, models). It also distinguishes itself from sibling tools by directing waste detection to get_optimization_report and cost trends to get_usage_trends.

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 names alternatives and when they should be preferred over this tool: 'For waste detection use get_optimization_report; for cost trends use get_usage_trends.' This gives an agent routing guidance rather than leaving the choice to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add non-safety behavior. It adds the return shape and key metrics (latency percentiles, cumulative, dedup_saved_tokens), which is meaningful since no output schema is present. No contradiction exists.

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-loads the core purpose. The metric list is dense but informative, and the return shape is summarized efficiently. The 'Read-only' phrase is redundant with annotations but does not meaningfully hurt conciseness.

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

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

For a parameterless read-only stats tool, the description covers scope, metric contents, and return structure. The '...' inside the session object leaves some schema detail unspecified, but the description is still sufficient for an agent to call it correctly and understand what it returns.

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?

This tool takes zero parameters, so the description cannot add parameter-level meaning beyond the schema. The baseline of 4 applies because there are no parameters to document and no ambiguity for an agent.

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 provides token savings stats for the current session, including per-tool call counts, savings, reduction percentage, dedup savings, and latency metrics. This is specific and not a tautology, though it does not explicitly distinguish itself from sibling tools like get_session_analytics or get_usage_trends.

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' provides useful context, implying use when current-session token savings statistics are needed. However, there is no explicit guidance about when not to use this tool or which sibling alternative to choose, especially given overlapping siblings like get_real_savings and get_session_analytics.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds useful context by specifying that only the symbol is returned (not the whole file) and by enumerating the JSON response fields. It does not detail the git verification behavior, but that is disclosed in the schema.

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

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

Three sentences carry the core purpose, usage routing, safety hint, and return shape with no filler. 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?

For a read-only 4-parameter tool without an output schema, the description gives a good overall contract: what is returned, which sibling to use, and that it is read-only. The only meaningful omission is resolving the symbol_id/FQN requirement conflict and noting the optional git mismatch behavior, though the latter is present in the input schema.

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

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

The schema covers 100% of parameters, so the baseline is 3; however, the description's 'by symbol_id or FQN' conflicts with the schema's required array listing both symbol_id and fqn. This can mislead an agent into supplying only one of them. The optional max_lines and verify_against_git behaviors are left entirely to the schema.

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

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

The description names a specific verb and resource ('look up a symbol ... return its source code') and immediately distinguishes itself from Read and get_context_bundle. An agent can infer exactly which operation this tool performs.

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

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

It explicitly says when to prefer this over Read (one specific function/class/method) and when to prefer get_context_bundle instead (multiple symbols). No ambiguity remains about 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 declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces these with 'Read-only.' It adds value by disclosing the output formats (JSON default or Markdown) and the adaptive-by-task-type behavior. No contradiction with annotations is present, and the extra output-format detail goes beyond what annotations 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?

The description is compact and front-loaded: the first sentence states the core purpose, the second gives direct usage guidance, and the third handles sibling differentiation. Every sentence earns its place with no redundant 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?

Given six parameters, a rich schema, and no output schema, the description covers the essential call-or-not decision and high-level output shape. It names the context contents (execution paths, tests, entry points) and output formats, though it does not enumerate the exact JSON fields returned; this is a minor gap for an all-in-one context tool but not blocking.

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 all six parameters, including task, focus, detail_level, token_budget, include_tests, and output_format. The description does not need to compensate for parameter gaps and adds only general context about output format, which is already reflected in the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the all-in-one context for starting a dev task, listing concrete contents (execution paths, tests, entry points) and how it adapts by task type. It also explicitly distinguishes itself from the sibling get_feature_context, so an agent can tell them apart without inspecting 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 gives explicit when-to-use guidance: 'Use as your FIRST call when beginning any new task' and frames it as a replacement for manually chaining search → get_symbol → Read. It also directs narrower feature-code lookups to get_feature_context, providing a clear alternative and exclusion condition.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it emits notifications/tools/list_changed, returns the loaded tools' schemas, and explains that the tools are usable even if the client ignores the notification (via batch). It also discloses the response JSON shape (loaded, already_loaded, unknown, blocked, tools, hint), which is not otherwise specified.

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

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

Two sentences, tightly packed with essential information, and the core action is front-loaded. Every clause adds value: the loading modes, the no-args list behavior, the notification side-effect, the batch fallback, and the return format. No redundancy or fluff.

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

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

Given a simple 2-parameter schema with no output schema, the description is remarkably complete. It explains the exact behavior, the notification, the return shape (including fields like 'unknown' and 'blocked'), and how to use the returned tools through batch. There is no missing information an agent would need to invoke this 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% for both parameters (preset and tools), so the schema already describes each parameter adequately. The description adds minimal parameter-specific meaning beyond the schema—only the hint to call with no arguments to list deferred tools, which is more usage guidance than parameter semantics. 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 states a specific verb ('Load') and resource ('this session's preset deferred'), and clarifies the two modes (preset and/or explicit tool names, or no args to list). It is clearly distinct from sibling tools like get_preset_info and batch, so an agent can immediately tell which tool to invoke.

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

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

Provides explicit usage context: call with no arguments to list deferred tools, and use the `batch` tool to call the loaded tools (since schemas are returned). It does not explicitly list when not to use this tool or name alternatives, but the batch reference and the 'list' mode give sufficient guidance for typical use cases.

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?

Goes far beyond the readOnly/idempotent annotations by disclosing the default approval tier, conditional cluster_ids, exact JSON return shape, support for the 'toon' output format, and the timeout/degraded response behavior. There is no conflict 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 dense and front-loaded: purpose and filters come first, followed by return format and edge behavior. Minor redundancy such as 'Read-only' (already in annotations) prevents a perfect score.

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 17 parameters, no output schema, and no external return documentation, the description is unusually complete: it specifies the response object, optional clusters_summary, total_results, default tier behavior, and degraded timeout behavior. An agent has enough information to invoke and interpret the result 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?

All 17 parameters already have schema descriptions, so the baseline is 3; the description mostly restates what those descriptions say (service_name scoping, review tiers, output format). It also leaves a mismatch: the input schema marks symbol_id, file_path, tag, and as_of as required while the description presents them as optional filters.

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?

Opens with a specific verb and resource: 'Query the decision knowledge graph.' It then lists the filter dimensions and ties the tool to the concrete question 'why was this architecture chosen?', which clearly distinguishes it from generic siblings like search_text 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?

Provides clear operational guidance: use service_name to scope to a subproject, and use include_pending or review_status to select decision tiers beyond the default. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

The description goes beyond annotations by disclosing that it mutates the index, is idempotent, invalidates search caches, checks for duplicate symbols, and returns a specific JSON shape. This aligns with annotations (idempotentHint=true, readOnlyHint=false) and adds valuable behavioral context.

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

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

Four tightly packed sentences: purpose, effect, usage timing, warning behavior, idempotence, and response format. Every sentence earns its place and the most important 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?

For a single-parameter mutation tool with no output schema, the description is complete: it covers when to call, side effects, idempotency, response format, and how to interpret the duplication warning. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already defines file_path as 'Relative path to the edited file'. The description reinforces this by referencing 'the single file', but it adds no new parameter-level detail beyond the schema.

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

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

The description opens with a specific verb and resource: 'Notify trace-mcp that a file was edited' and explains the concrete effect ('Reindexes the single file and invalidates search caches'). This clearly separates register_edit from the many read-oriented sibling tools like get_index_health and 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?

It explicitly says 'Call after Edit/Write to keep index fresh' and contrasts itself with 'much lighter than full reindex', giving clear timing and relative cost guidance. It does not name an exact sibling alternative, but the usage context is unambiguous.

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?

Annotation Contradiction: annotations declare readOnlyHint=true, while the description explicitly says 'Live agent write', routes rows through a review queue, drops low-confidence rows, and persists data. This is a direct contradiction that makes the tool's behavioral contract untrustworthy.

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 every clause earns its place: core behavior, routing rules, dedup/rate-limit, usage timing, sibling alternatives, and return shape. It is front-loaded and avoids 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?

Despite the annotation contradiction, the description itself provides the routing behavior, persistence semantics, return JSON shape, and usage context, while the schema covers all parameters. With no output schema, the explicit return shape is a strong addition. The conflicting readOnly annotation prevents a perfect score.

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 fully documents all 9 parameters. The description adds little parameter-level meaning beyond confirming session-based dedup and rate-limit behavior, which the schema already mentions for session_id. 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 identifies a specific action ('write into the decision knowledge graph'), the confidence-routing behavior, and explicitly contrasts itself with add_decision and mine_sessions. An agent can distinguish this tool from its siblings without inspecting 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?

States exactly when to use it ('capture decisions in real time') and names the alternatives for other scenarios: add_decision for manual high-confidence writes and mine_sessions for post-hoc extraction from session logs.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the baseline burden is lower. The description adds value by disclosing the return JSON shape, mode-specific output variations, and support for output_format 'toon'. 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 cover purpose, alternatives, return format, and output options with zero wasted words. Key differentiators are front-loaded, making it quick for an agent to read and act on.

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 20-parameter tool with no output schema, the description provides a useful return shape and notes mode-specific behavior. It does not enumerate every mode or retriever, but the schema covers those details completely, so the description is sufficiently complete 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%, so the schema fully documents all 20 parameters and their meanings. The description adds minimal parameter-specific insight beyond referring to symbol kinds and output_format, which is acceptable given the schema's completeness.

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 operation — searching symbols by name, kind, or text — and explicitly contrasts with grep, search_text, and find_usages. It identifies the resource (symbols) and distinguishes itself from similarly named siblings without leaving ambiguity.

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 this instead of Grep for symbols, use search_text for raw text/comments, and use find_usages for references to a known symbol. This is actionable 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so no contradiction exists. The description adds meaningful behavioral detail beyond annotations: it discloses the exact JSON return shape, the existence of total_matches, and the grouping option to deduplicate file paths — useful operational context. It doesn't fully describe all edge behaviors (e.g., timeout semantics), but given the annotation coverage, the added context earns a 4.

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

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

The description is three sentences with no fluff. It front-loads the core purpose, follows with explicit usage guidance and sibling routing, then closes with return-format and grouping behavior. Every sentence adds distinct agent-relevant information; nothing is redundant or wasted.

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

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

Despite having nine parameters and no output schema, the description provides the crucial context an agent needs: the scope ('all indexed files'), the intended use cases, the sibling distinction, the return payload shape, and a practical tip for handling many hits. The remaining param details are fully covered by the rich schem, so this 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%, so the baseline is 3 even without parameter details in the description. The description does add a little extra parameter meaning — notably the grouping by_file tip to deduplicate file paths — but this largely mirrors the schema's own grouping description ('saves tokens on long paths with many hits'). The description adds no significant new parameter semantics beyond the schema's comprehensive coverage.

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

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

The description uses a specific verb and resource: 'Full-text search across all indexed files.' It enumerates supported features (regex, glob, language filter) and concrete use cases (strings, comments, TODOs, config values, error messages), while explicitly distinguishing itself from the symbol-search sibling 'search.' This makes the tool's purpose unmistakable and differentiates it clearly from 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 explicitly states when to use this tool: 'Use for finding strings, comments, TODOs, config values, error messages — anything not captured as a symbol.' It also names the alternative: 'For symbol. search (functions, classes) use search instead.' This is a clear when/when-not routing with an explicit alternative, requiring no inference from the 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?

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.