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

Annotations already signal read-only, idempotent, and open-world hints, so the description does not need to restate safety. It adds value beyond the annotations by specifying the exact returned fields and mentioning the equivalent mushi://activation resource. No contradiction with annotations was found.

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, front-loaded with the core purpose, followed by usage cue and exact return shape. The natural-language list and the JSON key list overlap, but they serve different readers (human summary vs exact field names) without unnecessary prose.

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

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

For a read-only status tool with one optional parameter and no output schema, the description covers the return contract, the usage moment, and an alternative protocol. It does not explain edge-state behavior (e.g., what fields look like before activation), but annotations and simplicity make the tool unlikely to cause incorrect invocations.

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

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

With 100% schema description coverage, the schema already documents projectId as a defaulting optional UUID. The description does not add parameter-level meaning, but the high coverage keeps this at the baseline rather than lower.

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

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

The description uses a specific verb-resource pair ('Return the unified activation posture') and enumerates the exact components (SDK heartbeat, ingested reports, GitHub, MCP readiness, QA stories, next best action), so an agent can distinguish this activation-status tool from siblings like get_inventory or get_recent_reports. The 'next best action' phrase also signals what makes this tool unique.

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 instructs when to use the tool: 'Read this before guessing which onboarding step is blocking the user,' which gives a concrete decision point. It also notes an alternative access path (mushi://activation for resource-reader clients), but it does not spell out when to prefer sibling tools over this one.

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

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

The description adds significant behavioral detail beyond annotations: the key is stored encrypted in Supabase Vault and never returned, failed probes remain quarantined, and baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. These are not present in the annotations and give the agent critical knowledge about side effects and constraints.

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

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

The description is three sentences with no filler. The primary action is front-loaded ('Add and immediately validate'), followed by critical storage/security details and a non-idempotency warning. Each sentence provides necessary information without redundancy.

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

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

For a mutation tool with no output schema, the description covers storage, validation, quarantine behavior, and baseUrl constraints. It doesn't explain what the response contains, but that is arguably not needed for an add operation. It might benefit from mentioning prerequisites like projectId existence, but the core calling context is well 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%, so the schema already describes all six parameters. The description adds marginal extra meaning by clarifying the baseUrl restriction ('only for allow-listed OpenAI-compatible HTTPS providers'), which slightly reinforces the schema's phrasing. It does not meaningfully explain label, priority, or projectId beyond what the schema does, 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 starts with a specific verb and resource: 'Add and immediately validate a BYOK API key', followed by the exact list of supported providers (anthropic, openai, firecrawl, browserbase, cursor). This clearly distinguishes it from sibling tools like test_byok_key (which tests existing keys) and remove_byok_key (which deletes them).

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

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

The description implies when to use this tool (adding a new BYOK key with immediate validation) but does not explicitly name alternatives or when-not-to-use conditions. It provides clear context by mentioning the immediate validation step, which indirectly suggests test_byok_key for testing without adding, but lacks an explicit routing statement.

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 mark it read-only and idempotent, and the description reinforces this with 'Read-only' and the explicit side-effect boundary 'Does not bump the pin.' It also discloses the response shape including the conditional suggestedActions, which adds useful behavioral context beyond the structured 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?

Every sentence carries information: purpose, endpoint, response, conditionality of suggestions, read-only guarantee, and usage triggers. It is front-loaded with the core action and remains compact without 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?

For a low-complexity read-only check with two optional parameters and an output schema, the description is complete. It covers what the tool compares, when to use it, what it returns, and the boundary that it never mutates the dependency pin.

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

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

Schema description coverage is 100%, with clear descriptions for 'current' and 'package', so the description does not need to add parameter details. It does not materially extend the parameter semantics, which matches the baseline 3 for fully covered schemas.

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: 'Compare a published @mushi-mushi/* package version against the catalog (GET /v1/sdk/latest-version)'. It is immediately distinguishable from sibling tools by focusing on SDK version drift, and explicitly notes it does not bump the pin, separating it from mutating fix 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 explicit trigger conditions: 'Use when Dependabot or mushi upgrade --check reports a drift, or before dispatching a fix that assumes a current SDK.' It also states a clear boundary: 'Does not bump the pin — that stays a human/Dependabot change,' telling the agent when the tool is not the right action.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds 'Read-only' (consistent with annotations) and discloses the exact return shape ({ ready, steps: [{...}], nextAction }), providing context beyond the annotations. No contradiction found.

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 but packs in the purpose, mode breakdown, return format, and a routing note. It is front-loaded with the core purpose and uses semicolons to list mode specifics efficiently. No filler sentences, though it could be slightly tighter.

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 2 parameters, a rich output schema, and annotations covering safety, the description covers all necessary calling context: mode options, default behavior, return structure, and a clear routing rule. 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%, so the baseline is 3. The description adds value by explaining mode defaults ('full (default) runs both...'), the projectId default ('defaults to configured project'), and the alias ('project_id' is accepted too'), which are not fully spelled out in the schema. This extra nuance elevates it slightly above 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 states a specific verb ('Diagnose'), a resource ('Mushi setup health'), and a concrete outcome ('return the single best next action'). It also explicitly positions itself as 'The one setup-diagnosis entry point — use this instead of separate connection/ingest checks,' which differentiates it from siblings like get_inventory or get_two_way_comms_health.

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

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

The description gives explicit mode-based usage: full, ingest, and dispatch, each with its own set of checks. It also names an alternative ('use this instead of separate connection/ingest checks') and clarifies when this tool should be selected, leaving no ambiguity about when to invoke it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read-only' is redundant but consistent. It adds genuine value by stating the prerequisite ('Requires inventory_v2') and the exact return shape ('{ added, removed, changed }'), which is critical since there is no output schema. These details go 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?

Two tight sentences, no filler. The core purpose and return format are front-loaded, followed by usage context and sibling routing. Every sentence earns its place.

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

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

For a diff tool with no output schema, the description adequately covers the return shape, prerequisite, and usage context. It could elaborate on edge cases (e.g., what 'changed' encompasses or error conditions), but given the tool's simplicity and the annotations covering safety, this is sufficiently complete 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% with descriptions for all parameters, so the description need not re-explain them. It mentions fromSha and toSha in the narrative but adds no semantic detail beyond the schema's descriptions. The baseline of 3 applies because the schema carries the semantic load.

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 ('diff') and resource ('inventory commits') with a clear scope (fromSha to toSha, added/removed nodes/edges). Explicitly differentiates from sibling get_inventory by calling out the current snapshot alternative. Unambiguous and immediately actionable.

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 ('before merging a PR that touches inventory.yaml') and names the alternative tool (get_inventory) with its distinct purpose. No ambiguity about when this tool should be selected.

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, the description discloses the real-world side effects (branch creation, signed draft PR), the non-idempotent behavior ('without it each call starts a new attempt'), and the prerequisite of GitHub + LLM key. These are consistent with readOnlyHint=false and idempotentHint=false, and they add detail the annotations alone cannot 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 dense but every clause carries information: purpose, agent override, prerequisites, return contract, retry semantics, and classification precondition. It is front-loaded with the main action. The only minor blemish is the cryptic 'Write;' marker, which slightly obscures the retry note.

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 a rich schema and output schema, the description covers everything an agent needs to invoke it correctly: when it is applicable, prerequisites, what it returns, how to monitor it, and how to complete the workflow. Nothing critical 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 schema already covers all 5 parameters with descriptions (100% coverage). The description adds value by emphasizing that agent defaults to the in-repo worker and by framing idempotencyKey omission as a new attempt. This is a modest addition over the schema, which already explains the idempotency behavior.

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 ('Start a Mushi fix agent'), plus the concrete side effects ('writes a branch and opens a signed draft PR'). This clearly differentiates it from siblings like suggest_fix, which only produce suggestions, and submit_fix_result, which submits results.

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 direct context for when to dispatch: a report must be classified, with an explicit fallback ('run triage_issue if not'). It also names prerequisites and the post-dispatch workflow (poll get_fix_timeline, merge_fix when CI is green). It does not enumerate all alternative tools, but the key conditions and sequencing are explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar for additional disclosure is lower. The description adds value by explaining the traversal origin ('from the report node') and the exact return shape ('{ nodes: [{ id, label, type }], edges }'), which is especially 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 front-loaded. The first sentence states purpose and return format, the second provides usage timing and alternatives. There is no filler or redundant restating of the title.

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

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

For a single-parameter, read-only tool with strong annotations, the description covers purpose, return shape, intended usage, and alternates. It is complete enough for an agent to decide when to invoke it and what to expect in 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 schema covers nodeId as 'Graph node UUID', so baseline is 3. The description adds meaning by indicating the traversal starts from a report node, which clarifies what kind of UUID should be supplied. This is a useful supplement to the schema, though it does not give detailed instructions on locating the nodeId.

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 ('Return') and resource ('other components/pages a bug group touches'), and clarifies the mechanism ('knowledge-graph traversal from the report node'). It also distinguishes itself from sibling tools by naming get_knowledge_graph and analyze_codebase_impact as alternatives.

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

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

The description explicitly says when to use the tool: 'Use before dispatch_fix to scope a change safely.' It also names alternatives with their distinguishing conditions: get_knowledge_graph for arbitrary seeds and analyze_codebase_impact for file-level import impact. This gives an agent clear decision criteria.

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, openWorldHint, and idempotentHint. The description adds valuable context beyond those: it is read-only, requires 'no second LLM key needed,' and explains that the fixPrompt is 'paste-ready' with a specific composition (diagnosis, reproduction, suggested fix, relevant code, blast radius). This goes beyond the annotations and schema by clarifying operational and content expectations.

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

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

The description is information-dense but every sentence earns its place: purpose, bundled contents, return shape, read-only/cost note, and usage routing. It is front-loaded with the core purpose and does not waste words on 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?

The tool has an output schema, so the description does not need to explain return values in detail. It covers when to use the tool, what it returns conceptually, its read-only nature, the absence of a second LLM key requirement, and how to route to alternatives. For a read-only bundle tool with clear annotations, 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%, with both reportId and projectId already described in the input schema. The description does not add substantial parameter-specific semantics beyond what the schema provides; it mentions report detail and project context only implicitly. With full schema coverage, 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 states a specific action ('Bundle everything an agent needs to fix one bug in a single call') and enumerates the bundled contents, the exact return fields, and the tool's relationship to siblings. It distinguishes itself from triage_issue and suggest_fix by naming what each alternative is for, so an agent can select the right tool 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 gives explicit guidance: 'Use before writing a fix' and then names concrete alternatives with their specific scopes ('use triage_issue for a multi-report review packet, or suggest_fix for just the Stage-2 hint'). This directly tells the agent when to use this tool versus its closest siblings, leaving 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 readOnlyHint=true and idempotentHint=true, and the description redundantly says 'Read-only.' It adds useful behavioral context beyond the annotations by describing the ordered stage lifecycle and the returned event structure. It does not contradict the annotations, and the safety profile is adequately covered.

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

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

The description is compact, front-loaded with the main purpose, and efficiently provides output shape plus usage guidance. The only minor waste is the standalone 'Read-only.' sentence, which merely repeats the readOnlyHint annotation.

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 single-fix-attempt tool with only two parameters, the description covers what an agent needs: the exact operation, the output shape, when to call it, and which sibling tools to use instead. No output schema exists, but the description provides the return shape directly, so nothing essential 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 input schema already documents fixId and projectId, including accepted aliases. The description adds no new parameter-level semantics, 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 names a specific verb ('Return'), a specific resource ('one fix attempt'), and the exact scope ('ordered lifecycle... dispatched, started, branch, commit, PR opened, CI, completed/failed'). It also distinguishes itself from get_report_timeline by explicitly limiting scope to a single fix attempt rather than the whole report thread.

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

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

There is explicit when-to-use guidance ('Use to debug "why did this fix fail?" after dispatch_fix') and named alternatives with their purposes ('use refresh_ci to re-poll GitHub CI, or get_report_timeline for the whole report thread'). This fully routes an agent to the correct tool.

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

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

Annotations already cover read-only/idempotence, and the description goes further by disclosing BFS traversal, a depth budget with default and max, and the returned node/edge structure. It doesn't over-explain beyond what 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?

Two compact sentences, with the core output and depth behavior front-loaded before routing guidance. Every phrase adds either operational or selection value.

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

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

The definition covers what it returns, how traversal depth works, when to use it, and which siblings handle adjacent cases. With an output schema and rich annotations present, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that seed can be by id or label and mentions depth default/max, but those details are already present in the schema.

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

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

The description names a specific verb and resource ('Return the BFS neighborhood around one graph node by id or label') and gives the exact return shape. It also explicitly positions itself against siblings like get_knowledge_graph and get_graph_node, so it's easy to tell apart.

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 use-case signal ('Tuned for "what touches this action?"') and names two alternatives with their distinct seeding conditions. This leaves no ambiguity about when to choose this tool.

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

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

Annotations already cover read-only, open-world, and idempotent behavior, so the description only needs to add extra context. It adds the return shape and, notably, the v2 derived status on Action nodes (ok | stale | broken), which is useful behavioral information beyond the annotations. It does not contradict 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 sentences with no filler. The action is front-loaded, the return shape is compact, and the sibling distinction is placed at the end. 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?

Given the single required parameter, a rich output schema, and annotations that already convey the safety profile, the description provides all the operational context an agent needs. It also routes to the relevant sibling tool, making the definition complete for correct 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 coverage is 100%, so the schema already fully documents nodeId as a UUID graph_nodes.id. The description merely repeats 'by id' and adds no additional parameter semantics beyond what the schema provides, 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 verb ('Fetch'), a specific resource ('knowledge-graph node row'), and the lookup key ('by id'). It distinguishes itself from get_graph_neighborhood by clarifying this tool returns a single node's details rather than connections.

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 to use this tool to inspect a single node's status and directs the agent to get_graph_neighborhood for connectivity queries. This gives clear when-to-use and alternative guidance 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 readOnlyHint and idempotentHint, and the description reinforces this with 'Read-only.' The description adds a non-obvious prerequisite ('Requires the inventory_v2 plan') and documents the return shape, which is especially valuable because there is no output schema. It does not detail all failure modes, but the annotation coverage lowers the burden.

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

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

Two sentences front-load the core behavior, then add return shape, prerequisite, and sibling routing without waste. The structure makes the tool immediately scannable and actionable.

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 low-complexity tool with one optional parameteramen and no output schema, the description provides the return structure, distinguishes from relevant siblings, and states the prerequisite. An agent has enough information 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?

The input schema has 100% coverage: projectId is fully described, including its default behavior and accepted alias. The description adds no new parameter-specific meaning, 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 uses a specific verb and resource: 'Return the current inventory.yaml snapshot' and gives the exact response shape. It also differentiates itself from sibling tools by naming diff_inventory and list_gate_findings and contrasting their 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?

Provides explicit selection guidance: 'Use for the full current state; use diff_inventory to compare two commits, or list_gate_findings for the latest gate results.' It also states the prerequisite 'Requires the inventory_v2 plan,' which tells the agent when the tool is applicable.

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 openWorldHint, and the description reinforces the read-only nature while adding behavioral context beyond annotations: the traversal respects a depth budget (default 2, max4 hops) and returns a specific nodes/edges structure. It does not contradict any annotation.

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

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

The description is short,front-loaded with purpose and output, and contains no fluff. The only slight redundancy is stating 'Read-only' when the annotations already declare readOnlyHint, and the return shape is already expressed by the output schema, but overall the structure is effective.

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 traversal tool with only one required parameter and a rich output schema, the description covers the key behavioral constraints (depth default/max), the intended usage, and the sibling differentiation. Nothing essential for an agent to correctly select and invoke this tool 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%, with seed and depth already documented. The description loosely reinforces these concepts by calling the seed a 'component or page' and mentioning the depth budget, but it does not add meaningful semantic details 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 states a specific action and resource: 'Traverse the knowledge graph from a seed component or page.' It also names the return shape (nodes and edges) and explicitly differentiates from sibling tools by pointing to get_blast_radius and get_graph_neighborhood, 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 explicitly says when to use this tool: 'Use to see how a component connects to the rest of the app.' It also names alternatives and their specific use cases: get_blast_radius for a bug's impact area and get_graph_neighborhood for a tighter BFS around one node.

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, openWorldHint, and idempotentHint. The description adds substantial behavioral context: the return shape ({ title, url, markdown, truncated }), the 8,000-character cap with a pointer to read more, the requirement that pages be indexed, and the note that no API key is needed. These details go beyond the annotations and are not contradictory.

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

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

Three concise sentences, front-loaded with the core purpose and return format. Every sentence adds value: the input source, the return structure, the truncation behavior, the indexing caveat, and the usage timing. No fluff 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 single-parameter tool with a detailed output schema and annotations covering safety, the description covers all necessary aspects: input source, output format, size limits, prerequites (indexed pages), authentication (no API key), and when to use. Nothing an agent needs 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?

Schema coverage is 100% (the page parameter is described as 'A url from search_mushi_docs, or a docs route such as \"/quickstart/mcp\"'). The description adds a concrete example route and reinforces the two accepted input forms, which slightly enriches the schema but is largely redundant. Since coverage is high, baseline is 3, but the example and explicit mention of the search source push it to 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 a specific verb+resource: 'Fetch one official Mushi docs page as Markdown'. It also distinguishes from siblings by mentioning the source (url from search_mushi_docs) and the trigger condition ('Use after search_mushi_docs when an excerpt is not enough'). This makes the tool's 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?

Provides explicit guidance: 'Use after search_mushi_docs when an excerpt is not enough' directly names the sibling and the condition for selection. Also states the constraint 'Only indexed docs pages resolve', giving the agent a clear precondition. This is more than enough to route the agent 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?

Although annotations already declare readOnlyHint=true, idempotentHint=true, the description adds important behavioral context: it promises newest-first ordering, discloses that includeRaw=true changes the returned columns, and states that reporter identifiers are never returned. This goes beyond the 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 dense but front-loaded with the core purpose and return shape, followed by filters and routing guidance. It earns its length because it packs meaningful details (never returns reporter IDs, includeRaw behavior, limit defaults), but a sentence or two could be trimmed since some filter details duplicate the schema enums.

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 an output schema present and annotations covering read-only/idempotent safety, the description still supplies what an agent needs: ordering, optional filters, limit bounds, includeRaw semantics, the never-returned reporter data, and routing to siblings. Nothing critical 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 all six parameters thoroughly, including enums and aliases. The description itself repeats some filter details (status/category/severity enums, limit defaults) and adds the note that reporter identifiers are never returned—useful but not a major compensation need. Baseline 3 is exceeded slightly because the description reinforces the key filter semantics and the default/max limit, but it also largely duplicates 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 states a specific verb and resource ('List recent bug reports for a project, newest first'), specifies the return shape, and distinguishes itself from siblings by naming alternatives (get_report_detail, search_reports). The scope (project, newest first) is clear, and the presence of filters reinforces its purpose.

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

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

Explicitly says 'Use to survey open reports; for one report use get_report_detail, to find a bug by text use search_reports.' This provides clear when-to-use guidance and names alternatives, which is exactly what the dimension asks for.

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 and idempotentHint, and the description adds valuable behavioral context: reporter identifiers are never returned, includeRaw=true returns every column instead, and the response is wrapped in { report }. These details go well beyond what the annotations 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?

Every sentence earns its place: purpose, content list, response shape, privacy note, read-only statement, usage scenario, and sibling alternatives. It is dense but not bloated, 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?

Combined with the full input schema, output schema, and annotations, this description covers what is returned, what is redacted, the alternative includeRaw mode, and when to choose sibling tools. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and each parameter has a description including accepted aliases. The tool description mentions includeRaw's effect but does not add significant new parameter semantics beyond the schema, so the baseline 3 applies.

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

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

Clearly states a specific verb 'Fetch' with a specific resource 'the full record for one bug report by id' and enumerates its contents. It distinguishes itself from siblings by naming which tool to use for evidence, timeline, and fix bundle alternatives.

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

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

Explicitly says 'Use when you have a reportId and need everything about it' and gives conditional routing to get_report_evidence, get_report_timeline, and get_fix_context. This is textbook 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 openWorldHint, so the safety profile is covered. The description adds valuable behavioral disclosure beyond those hints: reporter identifiers (session id, end-user id) are never returned, and the evidence package is explicitly scoped to a single bug report. This is meaningful context about what the tool will and will not surface.

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

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

The description is long, but every sentence earns its place: it needs the detail because there is no output schema and the return payload spans many categories. The content is front-loaded with the core purpose, then organized by pillar with numbered subsections, making it easy for an agent to scan. The final comparison to get_report_detail plus report timeline is a useful, non-redundant closing note.

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 the return value, and it does so thoroughly: it lists logs, traces, metrics, screenshot, browser environment, tags, and explicitly states what is excluded. It also gives the relationship to sibling tools and the efficiency benefit. An agent has enough information to call the tool correctly 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?

Schema description coverage is 100%: the reportId parameter is documented as 'Report UUID. (`report_id` is accepted too.)'. The description does not add much beyond this, though it reinforces that the parameter selects a single bug report. Since the schema already carries the parameter meaning, a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Return the full evidence package for a single bug report.' It enumerates exactly which data is included across logs, traces, and metrics, and explicitly distinguishes itself from get_report_detail and get_report_timeline. This makes it immediately clear what this tool does and how it relates to 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 gives clear context for when to use the tool: it returns the data an engineer would collect for root-cause investigation, and it is faster than calling get_report_detail and report timeline separately. It names alternatives and positions this tool as their combined, faster replacement, but it does not explicitly state when-not-to-use it or compare it with more decision-oriented siblings like get_fix_context or suggest_fix.

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 supply readOnlyHint, openWorldHint, and idempotentHint. The description adds value by stating the ordering (oldest to newest), the merging behavior across multiple event streams, and the exact return shape. It does not mention potential rate limits or additional access constraints, but for a read-only getter this is sufficient 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?

Three front-loaded sentences: purpose, return shape, and usage guidance. 'Read-only.' is redundant with the readOnlyHint annotation, which is a minor waste. Otherwise every sentence earns its place and the structure is efficient.

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

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

Despite having no output schema, the description includes a concrete return shape, names the sibling tools for contrast, and clarifies ordering and merge scope. With only one parameter and annotations covering safety/idempotency, 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?

Schema description coverage is 100%, and the parameter description already explains that reportId is the report UUID and accepts report_id. The tool description adds no extra parameter-level semantics beyond what the schema 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?

States a specific verb ('Return') and resource ('ordered activity timeline for one report'), enumerates the merged event kinds, and explicitly distinguishes itself from get_report_detail and get_fix_timeline. An agent can unambiguously identify what this tool does and when to use it over 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?

Provides explicit guidance: use for an end-to-end view of a report thread, with named alternatives get_report_detail for the static record and get_fix_timeline for debugging a single fix attempt. This is a model of when-to-use/when-not-to-use 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond those: it explains the retrieval technique (pgvector nearest-neighbour), the tuning intent, and the ranked 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?

Three sentences with no filler: purpose is front-loaded, return format is summarized, and usage/alternative guidance closes it out. Every sentence earns its place.

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

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

For a two-parameter read-only tool with an output schema, the description covers what it does, what it returns, when to use it, and how it differs from search_reports. Nothing an agent needs 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?

Schema description coverage is 100%, and the schema already documents query as 'Component name, page path, or bug description' and limit with default/max. The description mostly restates this information without adding new parameter semantics, 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 states a specific verb and resource ('Find existing bugs similar to...') and names the underlying mechanism (pgvector nearest-neighbour search). It also distinguishes itself from the sibling search_reports by noting it is 'tuned for "have we seen this before?"'.

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?

Explicit usage guidance is provided: 'Use to dedupe before filing or group regressions; use search_reports for general free-text search.' This tells the agent exactly when to choose this tool versus the relevant 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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral context by listing what the summary includes and the verification purpose (confirming two-way delivery), which helps the agent set expectations about output content beyond the generic 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 sentences, no fluff. The first sentence front-loads the core purpose and deliverables; the second provides the actionable usage context. Every phrase earns its place, and the key scope ('two-way') is stated immediately.

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 parameters and no output schema, the description carries the burden of explaining what the result contains—it does so by naming all key fields. It also supplies the integration scenario and verification goal, which is sufficient for an agent to correctly invoke and use the tool.

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

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

The tool has zero parameters, and the input schema confirms this with 100% coverage. Per calibration, a baseline of 4 applies for zero-parameter tools. The description adds no unnecessary parameter guidance, which is appropriate here.

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 ('Summarize') and resource ('SDK ↔ admin two-way reporter health for a host app'), then enumerates the exact data points covered. This makes it clearly distinguishable from siblings like get_recent_reports or reply_to_reporter, which focus on one side of the communication flow.

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 when to use it: 'after wiring @mushi-mushi/web in a Vite/Capacitor app to confirm reports land in the console and admin/MCP replies reach the in-app widget.' This gives a clear temporal and functional context, though it does not name alternatives or explicitly say when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it states the return shape (pooled keys plus legacyKeys metadata), explicitly says 'never the raw secret', and clarifies that legacyKeys are read-only metadata for pre-pooled credentials. This is meaningful additional transparency.

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

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

The description is compact and front-loaded: it states the core action and grouping first, then the return shape, then the safety note, then usage guidance and the sibling alternative. Every sentence earns its place with no 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 read-only list tool with one documented parameter and no output schema, the description is nearly complete. It explains the return structure, the safety property (no raw secrets), and the usage context. The only minor gap is that it doesn't describe pagination or ordering, but for a list of pooled keys this is a small omission given the annotations already cover safety and idempotency.

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 single parameter (projectId). The description doesn't add parameter-level detail beyond what the schema provides, but it does clarify the overall return semantics. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 ('List'), a clear resource ('the project's BYOK API keys'), and a grouping dimension ('by provider'), naming the exact providers. It also distinguishes itself from siblings by explicitly pointing to add_byok_key as the tool for adding keys, so an agent can tell it 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 says when to use this tool ('Use to see which keys are validated, active, pending, legacy, or rate-limited') and names the alternative for a different action ('use add_byok_key to add one'). This is clear context with an explicit exclusion and 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 establish readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to re-derive safety. It adds value by disclosing the newest-first ordering, the returned runs/findings shape, and the available gate/severity filters. The explicit 'Read-only' line is redundant with annotations but not contradictory.

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

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

The description is front-loaded with the core purpose, followed by the return shape, filters, and sibling routing. It is slightly dense because it repeats the full enum lists that the schema already provides, but every sentence carries functional value and it remains compact.

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

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

For a read-only list tool with three optional, fully documented parameters and an output schema, the description covers purpose, ordering, return shape, filters, and alternatives. 'Recent' is not precisely bounded and pagination is not mentioned, but those are minor gaps given the output schema and annotation coverage.

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

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

Schema description coverage is 100%, and both gate and severity already carry enums and meaningful descriptions. The description restates the filter options and maps them to the conceptual purpose, but it doesn't add substantial meaning beyond the schema, so the high-coverage 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 opens with a specific verb and resource: 'List recent inventory gate runs and their findings for a project, newest first.' It clearly differentiates the tool from siblings by explicitly naming diff_inventory and get_inventory as alternatives for different tasks.

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

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

It provides direct usage guidance: 'Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.' This tells the agent exactly when to pick this tool over nearby alternatives, 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 cover read-only, idempotent, and open-world behavior, and the description reinforces 'Read-only'. Beyond that, it adds behavioral context about 'promoted' lessons and highest-frequency-first ordering. The return shape is mentioned but the output schema already covers it, so this is useful but not critical extra disclosure.

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

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

Three sentences deliver the purpose, output shape, read-only trait, and usage alternative with zero filler. The most decision-relevant information (what it lists and how it is ordered) 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 output schema, annotations, and fully documented parameters, nothing essential is missing. The description also supplies the key sibling-routing information, making it complete for an agent to select and call 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 description coverage is 100%, so limit, severity, and projectId are already fully documented. The description adds minimal parameter-level meaning beyond confirming the 'current project' default, which is consistent with projectId. It does not need to compensate for schema gaps.

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

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

The description states a specific action (List), a specific resource (promoted learning rules/lessons for the current project), and a concrete behavior (highest-frequency first). It also distinguishes itself from query_lessons by describing the full-catalog browsing purpose, making it easy to tell apart 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 says when to use this tool ('browse the full catalog of encoded heuristics') and when not to, naming query_lessons as the alternative for diff/PR-specific retrieval within a token budget. This gives clear routing guidance 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?

Annotations already say destructiveHint=true and idempotentHint=true, but the description goes further by explaining that the action is irreversible from Mushi's side, that GitHub has no unmerge endpoint, that a revert would require a manual PR, and that re-running on an already-merged attempt is a safe no-op. This substantially enriches the annotation signal.

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 sentence earns its place: outcome, return shape, destructiveness, idempotence, prerequisite, and sibling routing. It is front-loaded with the core action and return value before safety context, and no filler or redundant restatement appears.

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 an output schema present, annotations covering safety, and a description covering irreversibility, idempotence, prerequisites, and alternatives, an agent has everything needed to decide whether and when to call this tool. Nothing material is missing 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 already fully documents fixId and mergeMethod, including the accepted alias fix_id and the default merge method. The description adds little parameter-level detail beyond aligning with the squash default, which is acceptable given the high schema coverage.

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

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

The description opens with a specific verb and resource: squash-merge the GitHub PR for a fix attempt, then mark the report fixed and notify the reporter. It also names sibling tools dispatch_fix and transition_status, so an agent can distinguish shipping a fix from dispatching one or changing status without merging.

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 when-to-use guidance: 'Use to ship a fix opened by dispatch_fix.' It also states the alternative ('use transition_status to change state without merging') and a hard prerequisite: CI must be green, checked via refresh_ci, and the agent must confirm the diff and CI status with the user before merging an unreviewed PR.

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, openWorldHint, and idempotentHint, so the safety profile is well covered. The description adds non-obvious behavior: bi-encoder retrieval, severity-weighted scoring, and token-budget packing, which are valuable beyond annotation 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?

Three dense sentences front-load purpose, then mechanics, then usage guidance. 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 description is complete for a read-only retrieval tool: it states the return shape ({ lessons: [...] }), usage context, and distinguishes from sibling list_lessons. With full schema coverage and safety annotations, no critical information is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions diffText and maxTokens defaults but those details already exist in the schema; no new parameter meaning is added beyond what the schema descriptors provide.

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 ('retrieve'), resource ('learning rules/lessons'), and context ('code diff or PR'). The description explicitly contrasts with list_lessons, naming what it is not and making sibling differentiation immediate.

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: 'Use before writing a fix or opening a PR'. It also names the alternative list_lessons for browsing all lessons unfiltered, providing a clear decision boundary.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral value by explaining that the write is a local persistence on the fix_attempt row and explicitly denies any external GitHub mutation, which is important context beyond the annotation booleans.

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 wasted words. It front-loads the main behavior, then states side effects, return value, and usage guidance, making it easy to scan 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 single-parameter, idempotent write operation with rich annotations, an output schema, and explicit sibling routing, the description covers everything needed to invoke it correctly. It communicates the write target, the external side-effect boundary, the return shape, and the recommended 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?

There is only one parameter and schema description coverage is 100%, so the schema fully documents fixId, including the accepted alias fix_id. The description reinforces that the parameter refers to the fix attempt whose PR check-runs should be re-polled, but adds no new semantic 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 states a specific action and resource: re-poll GitHub for a fix attempt's PR check-run status and persist it on the fix_attempt row. It also explicitly differentiates itself from related tools by clarifying it does not merge or mutate GitHub, making it easy to distinguish from merge_fix and get_fix_timeline.

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 context: use it right before merge_fix to confirm CI is green, and use get_fix_timeline when the full attempt lifecycle is needed. It also lists an exclusion, stating it does not merge or mutate GitHub, which prevents misuse.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds that it removes 'including its Vault secret', providing context on what gets destroyed beyond the annotation. It also states 'Permanently remove', reinforcing the irreversibility. This adds value beyond 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?

One concise sentence with high information density. It front-loads the destructive and idempotent nature, and the scope. 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?

Given the schema fully describes parameters, annotations cover safety, and no output schema exists, the description adequately covers what the tool does and its consequences. It doesn't mention prerequisites (e.g., authentication) but those are implied by 'authenticated project'. It is complete for a destructive mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description doesn't add meaning beyond the schema, except that 'keyId' is a pooled BYOK key UUID from list_byok_keys (already in schema). Baseline 3 is appropriate as the schema does the heavy lifting.

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 ('remove'), a precise resource ('pooled BYOK credential by key id'), and the scope ('from the authenticated project'). It clearly distinguishes from siblings like add_byok_key and test_byok_key by naming the operation and the destructive nature.

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 labels the operation as destructive and idempotent, and mentions it removes a BYOK credential. However, it does not explicitly state when not to use it (e.g., when a key is still in use) or name alternatives. The clear destructive label provides sufficient guidance for an agent to avoid misuse, but not full exclusion 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?

Adds behavior beyond annotations: 'Write; idempotent — reopening an already-reopened report is a no-op' and discloses return shape ({ report } with status=reopened). These details extend the idempotentHint and readOnlyHint annotations rather than 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?

Two sentences with zero redundancy: the first states action and return, the second covers idempotency and usage guidance. 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 an output schema present and annotations covering safety/idempotency, the description supplies the trigger, the alternative, the affected states, the return, and the idempotency behavior. Nothing an agent needs 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 baseline is 3. The description confirms reportId as UUID and note as operator note, but adds no format or constraint details beyond the schema. The 'previously fixed/verified/dismissed' context implicitly constrains the report state, but that is resource-level context, not parameter-level.

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 action and resource: 'Move a previously fixed/verified/dismissed report back to the reopened state for regression review.' Explicitly names the sibling tool 'transition_status' for any other state change, making differentiation immediate.

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

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

Provides an explicit trigger condition ('when a reporter says "still broken" after a fix shipped') and an explicit alternative ('use transition_status for any other state change'). This is exactly the when/when-not guidance needed.

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

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds behavioral detail: the reply is visible, appears as an admin comment in the in-app widget, and creates an unread notification badge. This goes beyond the annotations and helps the agent understand the side effects.

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

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

Two concise sentences. The first states the action and its visible effect; the second gives concrete usage scenarios. No redundant words, and the 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 simple tool with fully documented parameters and no output schema, the description covers the purpose, behavior, and usage. It could mention prerequisites (e.g., whether the report must be in a certain state), but that is minor and not critical for an agent to 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?

The schema has 100% description coverage for all three parameters, each with clear explanations. The description does not add extra parameter-level meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Send a visible message to the end-user who filed a bug report') and resource, and distinguishes itself from sibling tools that handle report state (transition_status, reopen_report) or retrieval (get_report_detail). 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?

It gives explicit use cases ('answer questions, request reproduction steps, or confirm a fix') and notes the benefit ('without leaving the Cursor IDE'). It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over other report-related 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds non-obvious behavioral context beyond those: no privileged schemas, a 60/hour rate limit, and a return shape of { sql, rows }. This helps the agent anticipate operational and safety constraints.

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

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

Two sentences, each earning its place. The first defines the operation, constraints, and return format; the second gives usage context and routes to alternatives. 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?

Given the low complexity, strong annotations, and absence of an output schema, the description is complete: it communicates purpose, constraints, return shape, rate limit, and alternative tools. An agent has enough information to decide whether and how to invoke this tool.

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

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

Schema description coverage is 100% and the single required parameter is fully described with an example. The description reinforces the natural-language style and adds an example use case, but it does not add meaning beyond what the schema already provides.

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

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

The description states a specific verb+resource: answer a natural-language question by generating and running a read-only SQL query over project data. It clearly distinguishes itself from siblings by framing itself for ad-hoc analytics rather than report lookups or documentation searches.

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

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

The description explicitly says 'Use for ad-hoc analytics' and names the alternatives: 'use get_recent_reports/search_reports for plain report lookups, or search_mushi_docs for documentation questions.' This gives an agent 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?

Annotations already provide readOnlyHint=true and idempotentHint=true, and the description adds meaningful context beyond them: 'works without an API key', the indexing scope ('titles, section headings and summaries'), and the ranked result format. No contradiction with annotations; the added details improve the agent's expectations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place—scope, returned shape, auth/read-only note, and sibling routing. There is no fluff 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?

With only two parameters, an output schema, and strong annotations, the description covers everything an agent needs: what is searched, the return shape, auth requirements, and how to chain with get_mushi_doc or avoid using it for project data. No critical operational detail 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 both parameters (query, limit) are already described in the input schema. The description adds only minor semantic value ('by keyword'), so a baseline 3 is appropriate since the schema already carries the parameter definitions.

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: 'Search the official Mushi documentation' by keyword, and names the indexed content areas (guides, MCP setup, inventory, QA, skills). This clearly distinguishes it from siblings like get_mushi_doc (fetch a page) and search_reports (search bug reports).

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 tells the agent when to use it ('before guessing API shapes, tool names, or RPC names'), what to do next ('then get_mushi_doc to read a page'), and when not to ('use run_nl_query for questions about your own project data'). This is exemplary sibling routing.

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 hints. The description adds real behavioral context beyond those: server-side pgvector similarity, a fallback to summary/description substring matching when embeddings are unavailable, and the ranked result shape. This is more than minimal, though it does not discuss rate limits or auth—minor given the tool's read-only nature.

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 tightly constructed sentences front-load the mechanism and result format, then move to usage guidance. Every sentence earns its place; 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?

With a full output schema and 100% parameter schema coverage, the description still adds the essential behavioral twist (fallback) and explicit sibling routing. Nothing an agent needs to correctly invoke this tool 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 schema already documents query, limit, and threshold including defaults. The description reinforces that the query is free text or component path but adds no new parameter-specific detail 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 verb and resource ('Search reports by meaning and keyword') and explicitly names sibling tools (get_similar_bugs, get_recent_reports) with contrasting use cases. An agent can immediately distinguish this from related search/list 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 explicit when-to-use guidance ('Use to find reports by free text') and when-to-use-alternatives guidance ('use get_similar_bugs to dedupe a known component/bug, or get_recent_reports to list without a query'). This fully answers the routing question.

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 reveals internal behavior beyond annotations: it creates a fix_attempt row, patches it to completed, links it to the report, and returns a fixAttemptId. It explicitly flags the write nature and non-idempotence, and explains the idempotency key mechanism and its default derivation. This goes well beyond the annotation hints and gives the agent a realistic model of side effects.

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

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

The description is two sentences, front-loaded with the core purpose, and packs essential usage guidance and behavioral context into a compact space. No filler or redundant phrasing; 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 parameters and a required output, the description covers the invocation trigger, the side effects, the return value, idempotency caveats, and sibling alternatives. Combined with a fully described schema and an output schema, an agent has everything needed 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?

The input schema has 100% coverage with detailed descriptions for every parameter, including the nuanced idempotencyKey behavior. The description merely lists field names without adding new semantic meaning; it reinforces the overall purpose but does not clarify any parameter beyond what the schema already provides. Baseline 3 applies since the schema carries the load.

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 ('Record') and resource ('fix outcome from an external agent'), lists the exact fields involved (branch, PR URL, files changed, lines added/removed), and immediately distinguishes it from sibling tools by naming dispatch_fix and merge_fix as alternatives. This leaves no ambiguity about what the tool does and how it differs from related operations.

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

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

It gives an explicit condition for use: 'Use after you opened a PR outside Mushi.' It then states clear alternatives: 'use dispatch_fix to have Mushi open the PR instead, or merge_fix once CI is green.' It also adds a critical usage warning about idempotency ('call once per PR'), which is exactly the kind of guidance an agent needs to avoid mistakes.

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 readOnlyHint, idempotentHint, and openWorldHint, and the description reinforces safety with 'Read-only' while adding useful behavioral context: it reads existing classification, is faster than get_report_detail, and requires prior triage for unclassified reports. It does not discuss error conditions, but the annotations carry much of the safety burden and the added precondition context is valuable.

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, output shape, read-only safety, precondition, speed comparison, and alternative routing with zero filler. The most decision-relevant information is front-loaded: what the tool returns and when to choose it.

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 read-only tool with both an output schema and strong annotations, the description covers everything an agent needs to invoke it correctly: return shape, precondition, sibling differentiation, and use case. There is no apparent missing context that would lead to incorrect invocation.

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

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

The input schema already fully documents reportId as a report UUID, and the tool description itself does not add much beyond the schema's own description. Schema coverage is 100%, so the baseline of 3 applies; the only slight addition is the field list returned, not a semantic augmentation of the parameter itself.

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 ('Return the Stage-2 suggested-fix slice for one report') and enumerates the exact fields returned, including rootCause, suggestedFix, reproductionSteps, summary, and component. It also distinguishes itself from sibling tools by naming get_report_detail and get_fix_context, so an agent can clearly tell when this tool is the right one.

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 ('when you only need the human-readable hint', 'for a quick "what should we try?"') and when-not-to-use guidance by routing to get_fix_context for a full paste-ready bundle. It also states a clear precondition: run triage_issue first if the report is unclassified.

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, the description discloses meaningful behavior: a successful provider probe activates the key, while auth, quota, and network failures keep it out of the runtime pool. It also states the return value is a sanitized validation result plus updated metadata, which is useful context. There is no contradiction with 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?

The description is compact and front-loaded, with the core action in the first sentence. The trailing 'Write; idempotent' duplicates annotation flags and adds a small amount of redundancy, but it does not significantly detract from the overall clarity.

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 only two simple parameters and no output schema, the description fully covers what an agent needs to call the tool correctly: the action, the key ID targeting, success/failure behavior, and the return value. No essential contextual information 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 schema already documents both keyId and projectId with 100% coverage, so the description is not required to add much. It only refers to 'by key id', which mirrors the schema's keyId description and adds no new 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 starts with 'Re-test one pooled BYOK credential by key id', giving a specific verb, resource, and scope. It clearly distinguishes this from sibling tools like add_byok_key, remove_byok_key, and list_byok_keys by focusing on the testing/activation action.

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 'Re-test one pooled BYOK credential' implies the tool is for existing pooled keys, and the outcome descriptions offer behavioral context. However, it never explicitly states when to prefer this over siblings such as add_byok_key or activation_status, and it provides no exclusionary or alternative guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description adds important context beyond that: it consumes LLM budget, is NOT idempotent, and each call opens a new PR. It also discloses the return shape ({ qaStoryId, prUrl }). This is meaningful behavioral disclosure that goes beyond the structured 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: it states the action, the prerequisites, the return value, the side effects, and the alternative in three sentences. Every sentence earns its place, and the most important behavioral warnings (consumes LLM budget, not idempotent) are placed before the usage guidance.

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

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

For a write tool with no output schema, the description covers the key facts an agent needs: what it does, what it requires, what it returns, and how it differs from the sibling. It doesn't describe the PR contents or failure modes, but the annotations plus description cover the critical operational context. A 4 is appropriate because it's complete enough for correct invocation, with minor gaps around error behavior.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a small amount of value by noting that reportId is the input to turn into a PR and that projectId defaults to the configured project, but it doesn't add substantial meaning beyond 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 states a specific verb ('Generate'), a resource ('Playwright regression test from a classified report'), and a concrete outcome ('open a draft GitHub PR with the spec'). It also distinguishes itself from the sibling generate_tdd_from_story by naming the alternative and its different input source, 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 says when to use this tool ('Use to lock in a regression as an E2E test') and names the alternative ('use generate_tdd_from_story to build a test from a mapped user story instead'). It also states prerequisites (inventory_v2 plan, GitHub and LLM keys configured), which is clear context for when the tool is applicable.

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 idempotentHint and readOnlyHint, but the description adds value by stating it is a write operation, idempotent (no-op on current status), rejects illegal transitions, and returns the updated report object. This goes beyond the annotation hints and clarifies behavior.

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

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

Two dense sentences pack purpose, valid targets, return shape, idempotency, rejection behavior, and usage guidance without waste. The critical constraint (valid targets) is front-loaded, making it easy to scan.

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

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

For a tool with 3 params, 2 required, and no output schema, the description covers all essentials: what it does, what targets are allowed, return format, idempotency, rejection, and how it relates to siblings. Nothing an agent needs 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?

Despite 100% schema coverage, the description adds critical semantic info: the valid targets are limited to 7 statuses, even though the schema enum lists 11. This restricts usage and clarifies the transition rules. It also reinforces that 'resolved' is stored as 'fixed' via the schema, and the description's explicit list is essential for correct parameter selection.

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 (move) and resource (report) with a clear goal: changing workflow state. It lists valid targets and distinguishes itself from sibling tools merge_fix and reopen_report by naming them, making the purpose unambiguous and differentiated.

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 tells when to use this tool ('to dismiss a duplicate or mark fixed') and when to use alternatives (merge_fix for merged PR, reopen_report for reopened path). Also mentions enforcing same transition rules as admin UI, giving clear context for 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 and idempotentHint, and the description adds substantial behavior beyond that: it discloses that the tool merges multiple sources, returns recommended_actions, reports partial_errors for failed sources, and includes notes for non-applicable sources. This gives an agent an accurate mental model of what actually happens when the tool runs.

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 longer than a simple one-liner but is information-dense and front-loaded with the core purpose. The Sentry 'Analyze with Seer' analogy is helpful but slightly optional; otherwise each clause earns its place given the tool's complexity.

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

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

Given the rich input schema, annotations, and presence of an output schema, the description is complete: it covers what sources are merged, what the returned packet contains, how failures/non-applicable sources are surfaced, and the intended call order before dispatch_fix. 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 fully documents reportId, projectId, and includeLogs. The description only adds 'Pass reportId to kick off review', which restates what the schema already conveys, so it does not go 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?

Description states a specific verb and resource: a 'read-only combined tool' that 'merges' six named sources into one 'structured review packet'. This clearly distinguishes it from the individual get_* siblings it aggregates, and the ordering hint 'Call this before dispatch_fix' anchors its role.

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 sequencing guidance ('Call this before dispatch_fix') and strongly implies the use case: a combined review packet with recommended actions when analyzing a user-felt report. However, it does not explicitly say when to prefer this over calling the individual get_* tools, or explicitly list when-not conditions.

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, idempotent, and open-world, and the description reinforces read-only while adding real behavioral context: the priority ordering, the output shape, and the fact that next-step actions carry tool/args. It could note that it only recommends actions rather than executing them, but the read-only hint implies this.

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 carry a lot of useful detail without redundant fluff, and the most important 'prioritised next list' concept is front-loaded. The priority categories are packed into a long first sentence, but it remains readable and each 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 an entry-point planning tool, the description covers the priority algorithm, output schema, read-only safety, and the exact user query that should trigger it. With an output schema present and annotations covering safety/idempotency, nothing essential for correct invocation appears 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 single optional projectId parameter is fully documented in the schema (100% coverage), including the default behavior and project_id alias. The description adds no additional parameter-level meaning, 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 specifies a clearly scoped verb-object: it returns a prioritised 'do this next' list for the project, with a defined ordering across blocked auto-fixes, in-flight fixes, reports, and chores. The trigger phrase 'Call this first when the user asks...' distinguishes it from siblings like triage_issue or get_recent_reports.

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 instruction: call first when the user asks what needs attention or what to triage/fix. It does not explicitly name alternatives or list when-not-to-use conditions, 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context: it's a write operation that consumes LLM budget, idempotent only 'within a short window', and results land asynchronously in judge_results. This goes beyond the annotations by clarifying the asynchronous nature and budget consumption, though it does not detail failure modes.

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

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

The description is well-structured, front-loading the core action and then layering return type, side effects, idempotency, and usage guidance. It is dense but every sentence earns its place, though it could be slightly tightened without losing meaning.

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?

An output schema exists, so return values are covered. The description includes how to read results (via run_nl_query), mentions the asynchronous nature, and gives usage context. It lacks error handling or prerequisite details, but given the annotations and simplicity of the tool, it 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 description coverage is 100%, and both parameters have meaningful descriptions ('Max reports to judge', 'Restrict to one project'). The tool description adds no additional parameter guidance beyond what the schema provides, 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 clearly states the verb 'Queue', the resource 'Sonnet-as-Judge', and the purpose 'to grade recent fix quality across accessible projects'. It also differentiates from the sibling get_fix_timeline by naming it as an alternative for single-attempt inspection. This is specific and unambiguous.

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

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

The description explicitly tells when to use it ('Use before shipping to vet fix quality') and when not to ('use get_fix_timeline to inspect a single attempt instead'). This provides clear decision rules without requiring the agent to infer context.

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 valuable behavioral context beyond annotations: it explicitly says 'Read-only; does not call any downstream tools itself,' which is a meaningful guarantee for an agent deciding whether to invoke it. It also discloses that hidden tools are named with enablement instructions, which is a useful behavioral trait not visible in the schema or 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 front-loaded with the most critical instruction ('CALL THIS FIRST'), then the return contract, then the scope constraint, then the safety note. Every sentence earns its place: the examples are compact, the return format is enumerated, and there is zero filler. It is appropriately sized for a tool that needs to orient an agent.

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 orientation tool with one optional parameter, no output schema, and no nested objects, the description is complete. It explains what the tool returns (three enumerated items), how to use it (intent phrase or blank), what it does not do (no downstream calls), and how it handles hidden tools. An agent has everything needed to invoke it correctly without further 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 the single 'intent' parameter well. The description adds value by giving concrete example values ('fix the top bug', 'check what I should work on', 'run QA tests', 'set up Mushi') and clarifying that leaving it blank yields a general orientation. This goes beyond the schema's examples and clarifies the blank case, which is genuinely useful.

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 ('CALL THIS FIRST'), a clear resource (Mushi project orientation), and a precise scope: it returns a curated list of 5–12 relevant tools, a one-paragraph orientation, and a single recommended first tool. It also explicitly distinguishes itself from the 40+ sibling tools by being the entry point when unsure which tool to use, so an agent can tell it 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 gives explicit when-to-use guidance: 'CALL THIS FIRST if you are new to this Mushi project or unsure which tool to use.' It also provides concrete example intents and states what it avoids (loading the full tool catalog), which implies when not to use it (when you already know the exact tool). This is strong routing guidance relative to the large sibling list.

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