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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to repeat safety. It adds value by stating the return fields and alternative resource access, providing useful behavioral context beyond annotations.

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

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

The description is two sentences plus a return shape, with no redundant information. It is front-loaded with the core purpose and efficiently adds guidance, alternative access, and return structure.

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

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

Given the tool's simplicity, one optional parameter, no output schema, and rich annotations, the description fully covers purpose, usage, and return format. It also mentions an alternative access method, making it 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?

With 100% schema coverage, the schema already documents the single optional parameter 'project_id' with its default behavior. The description does not add additional parameter details, so it meets the baseline without exceeding it.

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

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

The description clearly states the tool returns the 'unified activation posture' with specific fields, and distinguishes it as the first step before guessing onboarding blockers. The verb 'Return' and resource are specific, and it differentiates from siblings by providing usage context.

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 'Read this before guessing which onboarding step is blocking the user,' giving a clear when-to-use. It lacks explicit when-not-to-use or alternatives, but the guidance is straightforward and actionable.

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

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

Goes well beyond annotations by disclosing that the raw key is encrypted in Supabase Vault, never returned, and that failed probes remain quarantined. These are non-obvious behavioral traits not present in annotations. The description's 'Write; NOT idempotent' aligns perfectly with idempotentHint=false and readOnlyHint=false, with no contradictions.

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

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

Three sentences efficiently convey purpose, security, validation, and constraints. Every sentence earns its place, with the primary action front-loaded and no redundant details.

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

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

For a mutation tool with 6 parameters and no output schema, the description covers the action, validation, storage, security, and side effects. The main gap is the return value (e.g., whether an ID is returned), but the description gives enough behavioral context to be useful.

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 covers 100% of parameters with descriptions. The description adds modest value by reiterating provider options and the baseUrl allow-list restriction, but doesn't meaningfully elaborate on individual parameter semantics 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 clearly states the tool's function: 'Add and immediately validate a BYOK API key' for specific providers. This distinguishes it from siblings like remove_byok_key, list_byok_keys, and test_byok_key by emphasizing the add-and-validate 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?

Provides clear context: it's for adding new keys, not for testing existing ones. The constraint on baseUrl (only allow-listed OpenAI-compatible HTTPS providers) and the explicit 'Write; NOT idempotent' warning give useful usage guidance, though it doesn't explicitly mention alternative 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?

States 'Read-only', matching annotations. Discloses that the tool runs checks but is non-destructive and idempotent. Details what each mode checks and the return format, giving full behavioral context beyond 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, front-loaded with purpose and return. Every sentence adds essential information without redundancy. Highly efficient.

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

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

Given output schema exists, the description still covers all behavioral aspects: modes, checks included, return structure, and safe nature. No gaps for a read-only diagnosis 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?

With 100% schema coverage, the description adds significant value by explaining the mode enum values (full, ingest, dispatch) and their meanings, noting that mode defaults to full, and clarifying project_id usage for dispatch checks.

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 uses the verb 'diagnose' with 'Mushi setup health' and states the goal to return the single best next action. It distinguishes itself from siblings by claiming to be the unified entry point.

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 'the one setup-diagnosis entry point — use this instead of separate connection/ingest checks', providing clear guidance on when to use and when not to use alternatives. Also explains the three modes.

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, but description adds prerequisite 'Requires inventory_v2' and return format, providing useful context beyond 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, zero wasted words, front-loaded with action and output.

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

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

Adequately covers purpose, usage, return structure, and prerequisite for a 3-param no-output-schema 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 coverage 100%, description mentions fromSha and toSha in context but adds no meaning beyond schema for projectId.

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

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

The description clearly states the tool diffs two inventory commits and returns added/removed nodes and edges, distinguishing it from get_inventory.

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

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

Explicitly says to use before merging a PR touching inventory.yaml and contrasts with get_inventory for current snapshot.

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 show readOnlyHint=false and idempotentHint=false, and the description reinforces these by stating it writes a branch, opens a PR, and that each call without the idempotency key creates a new attempt. It adds dependencies (GitHub + LLM key), idempotency behavior, and operation semantics that are not available from annotations alone.

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

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

The description is dense but well organized: behavior first, then configuration, prerequisites, return value, polling guidance, idempotency, and a precondition. Every sentence carries workflow-relevant information and there is no redundant filler.

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

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

Given the four parameters and the tool's broader workflow, the description covers behavior, prerequisites, idempotency, returns, and follow-up actions. The remaining details like inventoryActionNodeId are already thoroughly documented in the input schema, so no critical decision context is missing.

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

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

Schema coverage for parameter descriptions is 100%, so the baseline is 3. The description adds useful meaning about the agent selection and idempotency key usage, but it also instructs callers to set agent="cursor_cloud", which is not present in the schema enum (claude_code, codex, rest_worker, mcp). That mismatch could cause an agent to select an invalid value and sizes the otherwise strong guidance.

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

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

The description names a specific verb-resource pair ('Start a Mushi fix agent'), targets a classified report, and states concrete effects: writes a branch and opens a signed draft PR. It clearly distinguishes this dispatch action from the many get_* and merge_fix sibling tools.

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

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

It explicitly says when the tool is appropriate (classified report), what prerequisites apply (GitHub connected + LLM key, run diagnose_setup first), and what to do before or instead (run triage_issue if report isn't classified). It also gives the follow-up workflow: poll get_fix_timeline and then merge_fix when CI is green.

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, idempotentHint. Description adds 'Read-only' and specifies return shape '{ nodes: [{ id, label, type }], edges }', which adds context beyond annotations. No contradictions. Score 4 for meaningful addition.

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?

Description is two sentences: first defines purpose and return shape, second gives usage guidance. No filler, front-loaded with essential info. Perfectly concise.

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 single parameter, high schema coverage, and annotations describing safety/idempotency, the description adequately covers usage and return structure. Absence of output schema is mitigated by description of return format. Could detail node types but not required.

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

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

Schema coverage is 100% for the single parameter nodeId, which is described as 'Graph node UUID'. Description does not add further parameter details but mentions 'report node' context. Baseline 3 is appropriate as 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?

Description uses specific verb 'Return' and resource 'other components/pages a bug group touches' with method 'knowledge-graph traversal from the report node'. It clearly distinguishes from siblings like get_knowledge_graph and analyze_codebase_impact, earning a 5.

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

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

Explicitly states when to use ('Use before dispatch_fix to scope a change safely') and when to use alternatives ('use get_knowledge_graph to traverse from an arbitrary seed, or analyze_codebase_impact for file-level import impact'). This provides clear 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, openWorldHint, idempotentHint. Description adds valuable behavioral context: 'No second LLM key needed' and clarifies the output structure. No contradiction.

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

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

The description is front-loaded with the key purpose and is relatively concise. The first sentence is packed but clear. Could be slightly tighter, but overall well-structured.

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

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

Given the output schema exists and annotations are rich, the description fully covers the tool's behavior, return values, and usage context. It differentiates from multiple siblings and answers likely agent questions.

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 clear descriptions for reportId and project_id. The description does not add parameter-specific meaning beyond what the schema provides, so 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?

Description starts with a specific verb 'Bundle' and resource 'everything to fix one bug', and explicitly distinguishes from siblings like triage_issue and suggest_fix. It clearly states the tool's purpose and scope.

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

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

Explicitly says 'Use before writing a fix' and provides alternatives: 'use triage_issue for a multi-report review packet, or suggest_fix for just the Stage-2 hint'. Also notes it's read-only.

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, idempotentHint. The description adds that it is read-only and returns events with 'ts, stage, detail' shape. While not overly detailed (e.g., no error cases or rate limits), it is sufficient for a harmless read operation and adds context beyond annotations.

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

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

The description is two sentences: first states purpose and output, second gives usage guidance and alternatives. It is concise and front-loaded with key info. Could be slightly more structured (e.g., using bullet points) but no waste.

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

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

Given the tool's simplicity (read-only, two parameters), the description fully covers the return shape and usage context. No output schema exists, but the description explains the return format. Annotations handle safety concerns, so completeness is high.

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%: both 'fixId' and 'project_id' have descriptions in the input schema. The description does not add new parameter-level semantics beyond what the schema provides. 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 it returns the ordered lifecycle of one fix attempt with specific stages (dispatched, started, branch, commit, PR opened, CI, completed/failed) and data fields (timestamps, PR URL). It distinguishes itself from sibling tools like refresh_ci and get_report_timeline by explicitly naming them 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: 'to debug "why did this fix fail?" after dispatch_fix'. It also provides alternatives: use refresh_ci to re-poll GitHub CI, or get_report_timeline for the whole report thread. This guides the agent on selecting 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 declare readOnly, idempotent, openWorld. Description adds algorithmic detail (BFS, depth budget) and explicitly states 'Read-only'. No contradictions.

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

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

Two sentences, front-loaded with core information. Every sentence adds value: first covers functionality and output, second gives usage guidance and alternatives. No waste.

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 output schema exists, description fully covers purpose, parameters, and usage context. No gaps for a 2-param tool with strong annotations.

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

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

Schema coverage is 100%. Description adds context: seed can be 'id or label' with example, depth is 'BFS hops' with default and max, providing extra meaning beyond schema.

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

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

The description clearly states it returns the BFS neighborhood around a graph node, specifies the output structure (nodes and edges with fields), and distinguishes from siblings (get_knowledge_graph, get_graph_node).

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 it is 'Tuned for what touches this action?' and provides clear alternatives: use get_knowledge_graph for component seed traversal, get_graph_node for a single node's row.

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, idempotentHint. Description adds valuable behavioral detail about including 'v2 derived status on Action nodes', which is beyond what annotations provide. No contradiction.

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

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

Two sentences, no fluff. Purpose is front-loaded. Every sentence provides distinct value.

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

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

For a simple single-fetch tool with strong annotations and an output schema (mentioned but not shown), the description is complete. It explains what it returns and how it differs from the neighborhood explorer.

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 clear description for nodeId. The description doesn't add new meaning to the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Fetch one knowledge-graph node row by id' with a specific verb (fetch) and resource (node). It distinguishes from the sibling tool get_graph_neighborhood.

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 inspect a single node's status; use get_graph_neighborhood to see what connects to it,' providing clear when-to-use and alternative guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds required plan and return structure, consistent with annotations. Does not contradict.

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 well-structured sentences with clear purpose, output format, and sibling guidance. No unnecessary 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 tool's simplicity (one optional param, no output schema) and good annotations, the description fully covers the tool's behavior, prerequisites, and return format.

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 covers the single parameter with description and optionality. Description does not add further parameter details beyond mentioning 'for a project', so no significant enhancement over schema.

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

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

The description clearly states the tool returns the current inventory.yaml snapshot with specific fields (latest ingest, validation errors, per-action status). It also distinguishes from siblings diff_inventory and list_gate_findings.

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 ('full current state') and provides alternatives for comparing commits or gate findings. Also notes prerequisite 'Requires the inventory_v2 plan'.

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 'Read-only' and elaborates on traversal behavior (depth budget, clamping to 4 hops) and return structure, which provides valuable 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?

The description is concise: 3 sentences, front-loaded with the main action, and no extraneous words. Every sentence adds value.

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

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

Given the presence of annotations, full schema coverage, and an output schema (implied by the description of return format), the description is complete. It covers purpose, usage, behavior, and parameter information adequately.

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

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

Schema coverage is 100% with clear parameter descriptions (seed, depth, default 2, max 4). The description does not add new information beyond what's in the schema, so it meets the baseline 3.

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

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

The description clearly states the tool's purpose: traversing the knowledge graph from a seed component or page. It specifies the return format (nodes and edges) and distinguishes from sibling tools by mentioning get_blast_radius and get_graph_neighborhood.

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 provides usage context: 'Use to see how a component connects to the rest of the app' and contrasts with alternatives: 'use get_blast_radius for a bug's impact area, or 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, idempotentHint. Description adds useful behavioral context: ordering (newest first), default limit and max, and that project_id defaults to server-configured project. No contradictions.

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

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

The description is concise, front-loaded with the main action and return type, then details filters and usage guidance. Every sentence adds value without redundancy.

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

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

Given the output schema, full parameter coverage, and annotations, the description is complete. It covers purpose, usage, parameters, and sibling differentiation with no apparent gaps.

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

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

Schema coverage is 100% with individual parameter descriptions. The description adds context: lists filter values, defaults, constraints (limit max 100), and for project_id explains its purpose and how to obtain IDs via other tools. Adds significant value beyond schema.

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

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

The description clearly states 'List recent bug reports for a project, newest first.' It specifies the return shape and explicitly differentiates from siblings: 'for one report use get_report_detail, to find a bug by text use search_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?

Directly states when to use: 'Use to survey open reports' and provides explicit alternatives: 'for one report use get_report_detail, to find a bug by text use search_reports.' Also lists optional filters for narrow usage.

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

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

Description discloses read-only nature and details the return object structure. Annotations already declare readOnlyHint, so the description adds value by listing fields and format. No contradictions.

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

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

Three focused sentences: purpose and fields, read-only and format, usage guidance with alternatives. No redundant information.

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

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

Given the presence of an output schema and rich annotations, the description is complete. It covers purpose, fields, safety, and differentiation from similar tools without missing critical 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 has 100% coverage with clear descriptions for both parameters. Description does not add new parameter information beyond the schema, so 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 'Fetch' and the resource 'full record for one bug report by id', listing specific fields. It distinguishes from sibling tools like get_report_evidence and get_report_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?

Explicit when-to-use: 'Use when you have a reportId and need everything about it'. Provides three alternatives for specific use cases, making the decision clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds value beyond these by detailing the exact components returned (logs, traces, metrics, screenshots, environment, tags) and noting it is equivalent to an engineer's manual investigation. The description 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 long but structured into clear sections (LOGS, TRACES, METRICS) with sub-bullets. It front-loads the core purpose and then elaborates. Every detail serves the agent's understanding of the returned data, though the length could be slightly trimmed without losing 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?

There is no output schema, so the description must carry the burden of explaining the return format. It does so exhaustively, covering all three observability pillars with specific field names, plus additional attributes (screenshot_url, browser environment, tags). Given the tool's complexity, this description is complete and fit for an agent to understand what to expect.

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

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

The input schema covers the single parameter 'report_id' with a description ('Report UUID.'), giving 100% schema coverage. The description does not add meaning beyond the schema, but it implicitly clarifies that this ID is used to fetch evidence for that specific report. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Return') and clearly identifies the resource ('full evidence package for a single bug report'). It explicitly distinguishes itself from sibling tools by mentioning it is faster than calling get_report_detail + report timeline separately, and it enumerates the exact data categories (LOGS, TRACES, METRICS).

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

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

The description states when to use this tool: when you need the full evidence package for root-cause investigation. It explicitly mentions the alternative ('get_report_detail + report timeline separately') and highlights the benefit ('Faster'), guiding the agent to choose this tool over alternatives for comprehensive evidence retrieval.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds merging behavior and return structure, providing useful context beyond 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 redundancy, core purpose first, usage guidance second. Highly efficient.

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

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

Describes input, output format, and usage context. Handles complexity of merging multiple event types without output schema.

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

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

Schema covers 100% of parameters; description does not add further meaning for the single parameter.

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

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

Description clearly states it returns ordered activity timeline for one report, merging multiple event types. It distinguishes from siblings like get_report_detail 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?

Explicitly says when to use this tool ('see what happened end-to-end') and when to use alternatives ('for static record' or 'to debug fix attempt').

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 description does not need to restate safety. The description adds value by revealing the algorithm (pgvector nearest-neighbour search), the relationship to search_reports, and the exact return format (Ranked { reports: [{ id, summary, similarity }] }). This provides behavioral context beyond annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose, then states the return format, then gives usage guidelines. Every sentence serves a distinct purpose.

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

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

Given the tool has only 2 parameters (1 required), has an output schema (implied), and annotations cover safety and idempotence, the description is fully complete. It explains the algorithm, return format, and usage scenario, leaving no gaps for an AI agent.

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

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

Schema coverage is 100% and the description does not add meaning beyond what the schema already provides for both parameters (query and limit). The schema descriptions are identical to what the description says. Therefore, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool finds existing bugs similar to a component, page, or description using pgvector nearest-neighbour search, which is a specific verb+resource+method. It distinguishes itself from the sibling tool search_reports by noting it is tuned for 'have we seen this before?' rather than general free-text search.

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

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

The description provides explicit usage guidance: 'Use to dedupe before filing or group regressions; use search_reports for general free-text search.' This clearly states when to use this tool and when to use an alternative, 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 indicate read-only, idempotent, and open-world. Description adds the specific metrics returned but doesn't disclose any additional behavioral traits like rate limits or data freshness.

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: first lists output fields, second gives usage context. Front-loaded, no redundancy, every part 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 no output schema, description adequately explains return values and when to use. Could note data format or update frequency, but sufficient for a health check 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?

No parameters exist, so schema coverage is 100%. Description adds value by detailing the return metrics, meeting the baseline expectation for zero-parameter tools.

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

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

Description clearly states it summarizes two-way communication health with specific metrics (SDK heartbeat, app version, unread messages, replies, follow-ups), distinguishing it from siblings like get_backend_health 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?

Explicitly says to use after wiring the SDK in a Vite/Capacitor app to confirm two-way communication works. Doesn't specify when not to use or list alternatives, but the context is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses that it returns pooled keys plus read-only legacyKeys metadata and 'never the raw secret.' This adds meaningful behavioral context about data safety and return composition, exceeding what annotations alone communicate.

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 not overly long. It front-loads the action, then details the return structure and gives usage guidance. The redundant 'Read-only.' sentence is minor but acceptable, leading to a slight deduction.

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

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

With no output schema, the description carries the burden of explaining return shape and semantics. It thoroughly covers pooled keys, legacyKeys, provider grouping, and key statuses, making it fully useful for an agent deciding 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 coverage is 100% for the only parameter (projectId, described as 'Project id'). The description adds no additional parameter 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 clearly states the tool lists BYOK API keys grouped by provider, with a specific verb ('List') and resource ('project's BYOK API keys'). It distinguishes itself from sibling tools like add_byok_key and remove_byok_key by focusing on listing/inspection.

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

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

The description explicitly says 'Use to see which keys are validated, active, pending, legacy, or rate-limited' and provides an alternative: 'use add_byok_key to add one.' This gives clear when-to-use context and directs to a sibling tool for a different operation.

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, idempotentHint. The description adds 'Read-only' and reveals return structure with fields. No contradictions; it provides useful behavioral insight beyond 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: purpose+ordering, return shape, usage guidance+alternatives. No redundant words, 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 3 parameters, 33 siblings, and an output schema, the description fully covers purpose, filtering, return format, and usage distinction. Output schema exists, so return details are sufficient.

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%, baseline is 3. The description summarizes the filter options with enumerated values (gate ids and severity levels), which adds clarity by grouping and providing quick reference, improving over schema alone.

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

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

The description clearly states 'List recent inventory gate runs and their findings for a project, newest first,' specifying the verb 'list', the resource 'inventory gate runs and findings', and the ordering. It distinguishes from siblings like 'diff_inventory' and 'get_inventory' by mentioning 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 '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,' providing clear context and named alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds 'Read-only' (consistent) and describes return format as an object with lessons array. It does not detail pagination or rate limits, but for a read-only list with good annotations this is acceptable.

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 covering purpose, ordering, usage context, and sibling differentiation. No filler or redundant information.

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

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

With output schema present and all parameters optional, the description covers the key aspects: what is returned (lessons with fields), ordering, and differentiation from sibling. No missing critical information for a read-only list 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 all three parameters (limit, severity, project_id). The description adds no parameter-specific details beyond what schema provides, which is fine for a baseline score of 3.

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

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

Description specifies verb 'list', resource 'promoted learning rules (lessons)', and ordering 'highest-frequency first'. It clearly distinguishes from sibling tool query_lessons by stating their different use cases (browse full catalog vs. retrieve for specific diff/PR).

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

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

Explicitly states when to use this tool ('Use to browse the full catalog of encoded heuristics') and when to use the alternative query_lessons ('retrieve only lessons relevant to a specific diff or PR within a token budget').

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 and idempotentHint=true. Description adds crucial context: irreversible from Mushi's side (no unmerge endpoint, only manual revert PR), safe no-op if already merged, and preconditions like CI green. 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?

Five sentences, front-loaded with main action, then behavioral notes and usage guidelines. No wasted words; every sentence adds value.

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

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

Output schema provided, return value mentioned in description. Annotations cover safety traits. Prerequisites and alternatives are given. Sibling tools are referenced. Complete for a tool of this complexity.

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

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

Schema coverage is 100% and both parameters (fixId, mergeMethod) are well-described in schema. Description does not add significant new info beyond the purpose mentioning 'squash-merge' (default method). 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?

Description clearly states the tool squash-merges a GitHub PR for a fix attempt, marks the report fixed, and notifies the reporter. It distinguishes from sibling tools like transition_status (change state without merging) and dispatch_fix (opens a fix).

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

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

Explicitly states when to use: 'Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.' Also provides prerequisites: CI must be green, and user should confirm diff and CI before calling on unreviewed PRs.

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 indicate read-only and idempotent. Description adds retrieval method (bi-encoder + severity-weighted scoring), token budget, and output format. However, it omits mention of the default value discrepancy for max_tokens (description says 2000, schema says 3000).

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: first front-loads purpose, second adds technical detail and usage guidance. 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 schema coverage and annotations, description explains output format and when to use. Lacks explanation of top_k and project_id, but schema covers them fully. Could briefly mention the ranking mechanism.

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

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

Schema has 100% coverage, so baseline is 3. Description adds context about token budget and retrieval method, but contradicts schema by stating max_tokens default is 2000 instead of 3000. This inconsistency reduces reliability for the agent.

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

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

Clearly states the tool retrieves lessons relevant to a code diff or PR context, using specific verb 'retrieve' and resource 'lessons'. Distinguishes from sibling list_lessons by mentioning unfiltered browsing.

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 advises using this tool before writing a fix or opening a PR, and recommends list_lessons for browsing all lessons. Also specifies the query input as diff/description.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds clarity by stating it is a write operation that persists data but does not mutate GitHub. Returns specific fields. No contradictions.

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

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

Three sentences, front-loaded with the core purpose, each sentence adds value without redundancy.

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

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

Given the low complexity, the description covers purpose, usage, parameters, return value, and behavioral traits. The output schema is referenced in the description, compensating for the absence of a formal schema in the 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 coverage is 100%, and the description does not add extra meaning beyond the schema's description of fixId. The tool's purpose implies the parameter's role, but that is already clear from the schema.

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

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

The description clearly states it re-polls GitHub for check-run status and persists it. It explicitly says what it does not do ('does not merge or mutate GitHub'), and distinguishes from siblings like get_fix_timeline and merge_fix.

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

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

The description explicitly advises when to use the tool ('right before merge_fix') and when to use an alternative ('use get_fix_timeline for the full attempt lifecycle'), providing clear usage guidance.

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

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

The description adds context beyond the annotations by specifying that removal is permanent and includes deletion of the associated Vault secret. It also labels the operation as write, destructive, and idempotent, which is consistent with the annotations and adds meaningful detail.

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

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

The description is a single sentence plus three tag-like tokens, all front-loaded with the action and resource. It packs essential information without redundancy or unnecessary words.

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

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

For a simple deletion tool with two well-described parameters and annotations covering destructive and idempotent behavior, the description adequately conveys the scope and consequences, including the Vault secret. It does not mention potential prerequisites like project existence, but this is not critical given the simplicity.

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 both parameters with descriptions (keyId as 'Pooled BYOK key UUID from list_byok_keys' and projectId as 'Project id'), so the description adds no additional parameter-level meaning beyond echoing 'by key id'. Baseline of 3 applies due to 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 explicitly states the tool "Permanently remove one pooled BYOK credential by key id from the authenticated project, including its Vault secret." This clearly captures the action, resource, and scope, and distinguishes it from sibling tools like add_byok_key and list_byok_keys.

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

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

The description implies usage for removing a BYOK key but does not explicitly state when to use it versus alternatives or any conditions. It names no sibling tools or exclusions, so guidance is limited to the core purpose.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds specific detail: 'Idempotent — reopening an already-reopened report is a no-op' and notes the return structure (object with status=reopened). No contradictions.

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

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

Two sentences: first sentence covers action and return, second provides usage guidance. No redundant information, front-loaded with key details.

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

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

Given annotations (idempotentHint, destructiveHint, readOnlyHint) and output schema, the description fully covers purpose, behavior, return shape, and usage context. No gaps for this level of complexity.

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

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

Schema coverage is 100% and descriptions already explain both parameters ('reportId' and 'note'). The description mentions 'recording an operator note' which aligns with the schema, but does not add new meaning beyond what is already 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 clearly states the action: 'Move a previously fixed/verified/dismissed report back to the reopened state for regression review, recording an operator note.' It specifies the verb (reopen) and resource (report), and distinguishes from sibling tool 'transition_status'.

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

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

Explicit when-to-use guidance: 'Use when a reporter says "still broken" after a fix shipped; use transition_status for any other state change.' This provides clear context and alternatives.

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

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

Annotations already indicate non-read-only (false) and non-destructive (false). The description adds value by specifying that the reply appears as an admin comment in the in-app Mushi widget and creates an unread notification badge, providing 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?

The description is three concise sentences, front-loaded with the primary action and effect. Every sentence adds value: first defines action, second explains UI impact, third gives usage scenarios. No wasted words.

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

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

The description covers purpose, usage, and behavioral effects adequately for a simple tool with complete schema annotations. However, since there is no output schema, it would be beneficial to mention what the tool returns (e.g., success confirmation), but this is a minor gap.

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

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

Schema description coverage is 100%: all three parameters (reportId, message, authorName) are described in the schema. The description does not add significant meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'send' and resource 'visible message to the end-user who filed a bug report'. It also details the effect (appears in widget, creates notification) and provides concrete use cases (answer questions, request repro, confirm fix), distinguishing it from sibling tools that are read-only or state-changing.

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

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

The description explicitly says 'Use this to...' and gives clear contexts (answering, requesting repro, confirming fix). It does not mention alternatives or when not to use, but the context is clear enough given the sibling list; no other tool performs this write 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, openWorldHint, idempotentHint. Description adds valuable context: no privileged schemas, rate limit of 60/hour, and return format. No contradiction.

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

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

Three sentences front-loaded with purpose, no wasted words. Efficient and clear.

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 one parameter, no output schema, the description fully covers use case, constraints, and alternatives. Complete for an AI agent to select and invoke correctly.

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

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

Single parameter 'question' has description in schema; description includes an example but doesn't add significant additional meaning. Schema coverage is 100%, so 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?

Clearly states it answers natural-language questions via read-only SQL, and distinguishes from sibling tools like get_recent_reports/search_reports and search_mushi_docs.

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 (ad-hoc analytics) and when not to (use other tools for report lookups or doc questions), providing clear usage 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 and idempotentHint true. The description reinforces 'Read-only' and adds behavioral context: it searches by keyword and returns ranked results. No contradiction. It adds value beyond annotations by specifying the search behavior and output fields.

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

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

Two sentences: the first states the action and output, the second gives usage guidance. No unnecessary words, front-loaded with key information. Maximally concise.

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 search tool with full schema coverage, output schema, and good annotations, the description covers purpose, usage context, and output shape. It includes the useful detail that results are ranked, which is not in schema. Complete enough for an agent to use 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 both parameters adequately described. The description adds 'by keyword' which aligns with the query parameter, but does not provide further semantic detail beyond the schema. 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 it searches the official Mushi documentation by keyword and returns ranked results with specific fields (title, url, excerpt). It distinguishes itself from sibling tool run_nl_query by specifying its scope is the docs, not project data.

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 ('before guessing API shapes, tool names, or RPC names') and when not to use ('use run_nl_query for questions about your own project data, not the docs'), providing a clear 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=true, idempotentHint=true, openWorldHint=true. The description adds behavioral details: pgvector server-side similarity, fallback to substring, and ranked results. It does not contradict annotations.

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

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

Two sentences, front-loaded with core purpose, then alternatives. No wasted words. Efficient and well-structured.

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

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

With 3 parameters, output schema described in description, and good annotations, the description covers search behavior, fallback, return format, and sibling context. Minor gap: 'component path' not further explained, but overall complete.

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

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

Schema coverage is 100% with descriptions for all parameters (query, limit, threshold). The description essentially matches the schema descriptions, adding no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it searches reports by meaning and keyword via pgvector similarity with a fallback, and specifies the return format. It distinguishes between siblings by naming alternatives like get_similar_bugs and 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?

Explicitly tells when to use this tool ('find reports by free text') and when to use alternatives ('use get_similar_bugs to dedupe a known component/bug, or get_recent_reports to list without a query').

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?

Discloses writing three specific files, idempotency (beyond annotation), required scope (mcp:write), and lifecycle relationship to `mushi sync-lessons`. This adds behavioral value beyond the `idempotentHint` annotation, which only flags idempotency without details.

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

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

Three concise sentences cover purpose, files, idempotency, scope, and usage alternatives. No redundant information; every sentence adds value.

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

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

For a bootstrap tool with one optional parameter and no output schema, the description fully explains the side effects, prerequisite (scope), and post-usage steps. It provides a complete picture of how this tool fits into the workflow.

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 does not elaborate on the `projectId` parameter beyond its schema description ('Project UUID — defaults to configured project'). No additional meaning is added, but the schema alone is sufficient given the optional default.

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

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

The description clearly states it writes three specific bootstrap files (`.cursorrules`, `.mushi/lessons.json`, `MUSHI.md`) and briefly explains each. This distinguishes it from siblings like `list_lessons` or `query_lessons` by specifying exactly what files are created and that it's a one-time setup step.

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: 'Call this once after connecting the repo; subsequently use mushi sync-lessons from CI.' Also notes idempotency and safe re-running, giving clear when-to-use and when-not-to-use 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?

The description clearly discloses the write semantics and the non-idempotency 'each call creates a new fix_attempt, so call once per PR.' It also explains the lifecycle side effects (creates a row, patches it to completed, links it). The annotations already mark write and non-idempotent, but the description adds important context about side effects and safe call frequency, which is beyond what annotations provide.

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

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

The description is dense yet succinct, with each sentence serving a distinct purpose: what it records, what it does, its return value, its side-effect/non-idempotency constraint, and the routing to sibling tools. The key warnings are front-loaded after the core function. No extraneous content.

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

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

The description includes all necessary information for an agent to decide whether to invoke this tool instead of dispatch_fix or merge_fix, to construct the input meaningfully, and to avoid duplicate submissions. It covers the workflow stage, the side effects, the return value, and the idempotency behavior — everything needed beyond the rich schema and annotation hints.

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 full coverage, but the description adds meaning by enumerating the key fields (branch, PR URL, files changed, lines added/removed). Most importantly, it explains the idempotency key's derived fallback behavior, which the schema only describes as 'optional UUID' — the description clarifies that omitting the key still yields a stable key derived from reportId + branch + prUrl, which helps the agent reason about safe retries.

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: 'Record a fix outcome' and 'Creates a fix_attempt row,' clearly distinguishing it from the read-only report tools and other fix-related tools. It explicitly names sibling tools dispatch_fix and merge_fix, which disambiguates it from those 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 this tool ('Use after you opened a PR outside Mushi') and when to use alternatives ('use dispatch_fix to have Mushi open the PR instead, or merge_fix once CI is green'). This leaves no ambiguity about tool selection.

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

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

Annotations already mark this as read-only and idempotent, and the description reinforces this by saying 'Read-only' and explaining that it reads the existing classification. The added value beyond annotations is the precondition about triage_issue and the promise of being faster than get_report_detail.

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?

Clear, front-loaded, and scannable; the first sentence conveys the core purpose and alternatives. There is mild redundancy in listing the exact return fields, since the field list and output schema largely repeat the prose, but the structure is otherwise 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?

The description is complete for a simple, single-parameter read-only tool: it covers what is returned, how to use it, the precondition, and the alternatives. No crucial context 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?

With one required parameter at 100% schema description coverage, the schema already documents reportId as a 'Report UUID to read the Stage-2 suggested-fix slice for'. The description's mention of 'one report' echoes this but does not add substantial 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?

Description begins with a specific verb and resource: 'Return the Stage-2 suggested-fix slice for one report' and enumerates exactly which fields are included. It differentiates itself from get_report_detail and get_fix_context by naming what it is NOT and why you would choose it.

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 when you only need the human-readable hint, use get_report_detail when needing more detail, and use get_fix_context when you want the full paste-ready bundle. Also states the precondition that triage_issue should be run 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?

While annotations provide idempotentHint, the description enriches with concrete behavioral details: a successful provider probe activates the key, while auth/quota/network failures keep it out of the runtime pool, and it returns sanitized validation results and updated metadata. 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, front-loaded with the core action, then outcome, then return value. Every sentence adds distinct information 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?

For a simple two-parameter tool with rich annotations, the description fully covers what the tool does, what side effects occur, and what it returns. Since there is no output schema, the explicit mention of return content ('sanitized validation result and updated key metadata') is sufficient and complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add extra parameter semantics beyond what the schema already documents (keyId as pooled BYOK key id, projectId as project id). It simply refers to 'key id' without further elaboration.

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 ('Re-test') and resource ('one pooled BYOK credential by key id'), clearly distinguishing this from sibling tools like add_byok_key, remove_byok_key, and list_byok_keys. It also states the primary action and scope immediately.

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

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

The description implies clear usage context: it is for re-testing an existing pooled BYOK credential. It explains outcomes (activation vs. staying out of the pool) but does not explicitly name alternatives or state when-not-to-use, leaving inference to the agent.

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

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

Description adds context beyond annotations: says it's a write operation that consumes LLM budget and is not idempotent (each call opens new PR). Annotations already indicate non-idempotent, but description fleshes out implications.

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: first explains core action, second provides usage guidance and output info. No wasted words. Front-loaded with purpose.

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

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

Covers input, output shape, side effects, prerequisites, and context for use. No output schema exists, but description provides return value shape.

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

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

Input schema covers both parameters with descriptions (100% coverage). Description does not add additional parameter details beyond 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?

Description clearly states it generates a Playwright regression test from a classified report and opens a draft PR. Verb and resource are specific. Explicitly distinguishes from sibling generate_tdd_from_story.

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 (lock in regression as E2E test) and when not to use (use generate_tdd_from_story instead). Also mentions prerequisites (inventory_v2 plan, GitHub and LLM keys).

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

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

Annotations already carry readOnlyHint=false, idempotentHint=true, and destructiveHint=true, lowering the bar. The description adds value beyond the hints: idempotence becomes a concrete no-op, illegal transitions are explicitly rejected, and the admin-UI equality is stated. It does not spell out what destructive effects may occur (e.g., irreversibility of dismissing), but the annotation already flags the risk.

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?

Five dense sentences cover the action, targets, return shape, behavioral traits, and sibling routing with no filler. It is front-loaded with the action and only minor redundancy with the structured fields ('Write', 'idempotent') keeps it from a top score.

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

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

For a mutation tool with 2 required strings, 100% schema coverage, and no output schema, everything the agent needs is present: how to call it, what statuses are legal, the return shape '{ report }', the idempotence rule, and the alternatives. Safety traits are already covered by the annotations, so 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 coverage is 100%, placing the baseline at 3. This description raises it by curating the full 11-value enum into the actual valid targets (classified, grouped, fixing, fixed, verified, reopened, dismissed), preventing an agent from trying to enter pending, triaged, in_progress, or resolved directly. The semantics slightly exceed what the schema alone provides.

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

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

The description opens with a concrete action on a concrete resource: 'Move a report to a new workflow state' and immediately scopes it with the rule of the admin UI. It explicitly names the valid target set, distinguishing this tool from get_* siblings, merge_fix, and reopen_report.

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

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

The final sentence is an explicit routing rule: 'Use to dismiss a duplicate or mark fixed; use merge_fix to mark fixed via a merged PR, or reopen_report for the reopened path.' This tells the agent exactly when to use this tool and when not to, naming the alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description reinforces the read-only nature and adds specifics about the output (structured review packet, recommended actions). This goes 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?

The description is four sentences, front-loaded with the main purpose, and every sentence adds value. No redundancy or superfluous information.

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

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

Given the complexity of the tool, the description covers purpose, usage, behavioral traits, and output. The presence of an output schema means return details are not needed. The description is self-contained and sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all three parameters documented. The description does not add significant meaning beyond the schema, except emphasizing report_id as the trigger. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a read-only combined tool that merges multiple data sources into a structured review packet and returns prioritized next actions. It uses specific verbs and identifies the resource (report), distinguishing it from sibling tools that provide individual data pieces.

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 advises to call this tool before dispatch_fix and provides the required parameter (report_id). It implicitly positions this as the comprehensive triage step, replacing the need to call multiple individual getters. No explicit when-not-to-use, but the context is clear enough.

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

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

The annotations already cover read-only, idempotent, and open-world hints, and the description reinforces the read-only nature. The description adds meaningful behavioral value by exposing the internal priority ordering and the fact that steps include 'tool' and 'args' for follow-up actions. This tells the agent that the tool only recommends actions rather than executing 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 every clause earns its place: the exact ordering policy, the items included, the return shape, the read-only behavior, and the trigger phrase are all packed into two short sentences. The key decision information is front-loaded with 'Prioritised do this next list' and ends with a clear usage trigger.

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 simple one-parameter optional schema, a full output schema, and annotations covering read-only and idempotence, the description covers what is needed: what the tool returns, its prioritization logic, and when to invoke it. There is no significant missing context that would prevent 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?

The input schema has 100% description coverage for the only parameter, project_id, with a clear default behavior. The tool description adds no extra parameter-level meaning, but none is needed because the schema fully documents the parameter. This is the appropriate baseline for full 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 states a specific verb and resource: a prioritised 'do this next' list for the project. It also clearly distinguishes itself from sibling tools by defining the ordering of blocks (blocked auto-fixes, in-flight fixes, user-felt reports, chores) and by giving an explicit call-to-action phrase. An agent can tell this is the global triage summarizer rather than a report-detail or fix-action tool.

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

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

The description gives an explicit trigger condition: 'Call this first when the user asks...'. It also implies this is a starting point rather than a detailed analysis or mutation tool. However, it does not explicitly name when NOT to call it or point to an alternative sibling, so it falls just short of the highest guidance level.

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?

Description adds behavioral context beyond annotations: it is a write operation consuming LLM budget, asynchronous (scores land in `judge_results`), and idempotent within a short window. 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 front-load the action and return type, with no redundant information. Every sentence adds value.

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

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

Covers core purpose, return type, async nature, idempotency, budget consumption, and sibling reference. Could mention error conditions or more detail on the dispatched count, but sufficient given the output schema is available.

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

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

Input schema has 100% description coverage for both parameters (`limit` and `projectId`). The description does not add significant meaning beyond the schema; it mentions 'one judge-batch job per project' but that is implicit from `projectId`. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Queue' and the resource 'Sonnet-as-Judge to grade recent fix quality across accessible projects', and distinguishes from sibling `get_fix_timeline` by specifying it is for vetting fix quality before shipping.

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

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

Explicitly states when to use ('Use before shipping to vet fix quality') and when not to (use `get_fix_timeline` instead for a single attempt), and notes idempotency within a short window.

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 (read-only, idempotent), the description discloses that it 'does not call any downstream tools itself' and that it avoids loading the full catalog into context. These are significant behavioral traits that aren't captured by the annotations, giving the agent a clear picture of side-effects and resource usage.

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

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

The description is concise, front-loaded with the most important call-to-action, and structured with numbered return items. There is no fluff; every sentence contributes to orientation, usage, or behavioral transparency.

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 1-parameter tool with no output schema, the description fully compensates by describing exactly what the agent will receive (three items listed) and why the tool is useful (avoids loading full catalog). It leaves no ambiguity about the tool's output or when to choose it.

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

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

The schema covers the parameter fully (100% coverage, including guidance to leave blank for general orientation). The description adds value by providing concrete examples of intent phrases ('fix the top bug', 'run QA tests') and emphasizing brevity ('short natural-language phrase'), which clarifies semantics 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 clearly states the tool's purpose: to be called first when new or unsure, returning a curated list of relevant tools, orientation, and a recommended first tool. It uses an explicit directive ('CALL THIS FIRST') and enumerates the three distinct outputs, making it unmistakably different from the sibling tools that perform specific operations.

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

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

The description provides explicit when-to-use guidance: 'if you are new to this Mushi project or unsure which tool to use.' It also explains the benefit ('avoids loading the full 68-tool catalog into context'), which helps the agent recognize when this tool is preferable over directly browsing or guessing.

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