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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Goes well beyond the annotations: the raw key is stored encrypted in Supabase Vault and never returned, failed probes stay quarantined, and baseUrl is gated to allow-listed OpenAI-compatible HTTPS providers. These are real operational facts an agent cannot infer from readOnlyHint/idempotentHint 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?

Dense but front-loaded, with the add-and-validate action stated first and caveats trailing. The provider enumeration duplicates the schema enum and 'NOT idempotent' restates the annotation, so a little space is spent on already-structured data.

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

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

For a 6-param mutation with no output schema, the description covers the important unknowns: storage, non-return of the secret, validation failure handling, and baseUrl constraints. It stops short of saying what a successful call returns (e.g. a key record/id), which is the remaining gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: baseUrl's allow-list restriction, and that the supabase token must be scoped read-only and is checked against the linked supabase_project_ref. That is more than the schema's one-line 'Allow-listed OpenAI-compatible HTTPS base URL'.

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

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

States a specific verb (add + immediately validate) and resource (BYOK API key), enumerates the supported providers, and clarifies the special Supabase case. It is clearly distinguishable from siblings test_byok_key, list_byok_keys, and remove_byok_key.

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

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

Gives clear context: it is a write, it is not idempotent, and validation happens on add, which implicitly tells the agent this is the create path. However it never names test_byok_key or explains when to re-test versus add a replacement key, so routing between siblings is left to inference.

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

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

The annotations already mark it read-only and idempotent, and the description reinforces this with 'Read-only' and the explicit side-effect boundary 'Does not bump the pin.' It also discloses the response shape including the conditional suggestedActions, which adds useful behavioral context beyond the structured annotations.

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

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

Every sentence carries information: purpose, endpoint, response, conditionality of suggestions, read-only guarantee, and usage triggers. It is front-loaded with the core action and remains compact without redundant filler.

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

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

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

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

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

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

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

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

The description states a specific verb and resource: 'Compare a published @mushi-mushi/* package version against the catalog (GET /v1/sdk/latest-version)'. It is immediately distinguishable from sibling tools by focusing on SDK version drift, and explicitly notes it does not bump the pin, separating it from mutating fix tools.

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

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

It gives explicit trigger conditions: 'Use when Dependabot or mushi upgrade --check reports a drift, or before dispatching a fix that assumes a current SDK.' It also states a clear boundary: 'Does not bump the pin — that stays a human/Dependabot change,' telling the agent when the tool is not the right action.

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

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

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

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

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

The description is compact but packs in the purpose, mode breakdown, return format, and a routing note. It is front-loaded with the core purpose and uses semicolons to list mode specifics efficiently. No filler sentences, though it could be slightly tighter.

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

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

With 2 parameters, a rich output schema, and annotations covering safety, the description covers all necessary calling context: mode options, default behavior, return structure, and a clear routing rule. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining mode defaults ('full (default) runs both...'), the projectId default ('defaults to configured project'), and the alias ('project_id' is accepted too'), which are not fully spelled out in the schema. This extra nuance elevates it slightly above baseline.

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

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

The description states a specific verb ('Diagnose'), a resource ('Mushi setup health'), and a concrete outcome ('return the single best next action'). It also explicitly positions itself as 'The one setup-diagnosis entry point — use this instead of separate connection/ingest checks,' which differentiates it from siblings like get_inventory or get_two_way_comms_health.

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

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

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

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

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

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

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

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

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

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

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

For a diff tool with no output schema, the description adequately covers the return shape, prerequisite, and usage context. It could elaborate on edge cases (e.g., what 'changed' encompasses or error conditions), but given the tool's simplicity and the annotations covering safety, this is sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 100% with descriptions for all parameters, so the description need not re-explain them. It mentions fromSha and toSha in the narrative but adds no semantic detail beyond the schema's descriptions. The baseline of 3 applies because the schema carries the semantic load.

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

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

States a specific verb ('diff') and resource ('inventory commits') with a clear scope (fromSha to toSha, added/removed nodes/edges). Explicitly differentiates from sibling get_inventory by calling out the current snapshot alternative. Unambiguous and immediately actionable.

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

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

Provides explicit when-to-use guidance ('before merging a PR that touches inventory.yaml') and names the alternative tool (get_inventory) with its distinct purpose. No ambiguity about when this tool should be selected.

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

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

Annotations only cover the safety profile (openWorld, not readOnly, not idempotent); the description goes well beyond by disclosing the write side effects, the GitHub + LLM key prerequisites, and the idempotencyKey retry semantics (without it each call starts a new attempt). It also states the return shape and that fixId is immediately usable by get_fix_timeline.

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

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

Purpose is front-loaded and every clause carries information (prereqs, agent choice, repo targeting, idempotency, next steps). It is dense as a single paragraph, but for a 6-param dispatch tool with many conditional branches the length is largely justified.

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

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

Despite an output schema existing, the description covers prerequisites, the required classification precondition, the safe-retry path, and the follow-up workflow (get_fix_timeline, merge_fix). An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is 100%, so the schema already documents most parameters. The description still adds value the schema lacks, e.g. that the default agent is the in-repo worker and that targetRepoId exists for multi-repo projects, though much of the targetRepoId/idempotencyKey text duplicates the schema.

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

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

States a specific verb and resource ('Start a Mushi fix agent for a classified report') plus the concrete side effects it produces (writes a branch, opens a signed draft PR). This clearly distinguishes it from siblings like suggest_fix, submit_fix_result, 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?

Explicitly routes the agent: run diagnose_setup mode=dispatch first for prerequisites, run triage_issue if the report isn't classified, set agent=cursor_cloud for a cloud agent, and poll get_fix_timeline then call merge_fix when CI is green. Both when-to-use and named alternatives are present.

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 readOnly/idempotent annotations, the description discloses the state machine (open/not_in_latest_run/unknown/allowlisted), how the 'latest run' is matched (design-server vs server scans, CI vs CI pushes, other-story scopes skipped), the guidance to treat unknown as open, and the 404 for inaccessible projects. That is substantial behavioral context the annotations do not carry.

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 content is front-loaded and mostly earns its place, but it is delivered as one enormous run-on sentence with deeply nested parenthetical clauses about state semantics, which is hard to parse. Structure could be broken into separate lines for state, fix, and location.

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 compensates by enumerating the full return shape ({ id, projectId, gate, gateLabel, ruleId, rule, severity, reason, fix, location, state, stateReason, run, latestRun }) and the nested fix fields. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the provenance of the id and ties it to the specific source tools, giving the agent more than the schema's format/pattern constraint 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?

States a specific verb and resource ('explain one gate finding by its id') and enumerates exactly what the explanation contains: the raising check, rule, reason, location, fix, and lifecycle state. It also names the sibling tools that produce the id, so an agent can distinguish it from get_fix_context or suggest_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?

It clearly says where the id comes from (list_gate_findings, get_radar, get_recipe_drift, get_code_health, get_store_status, or the console) and when a finding is unreachable (404). It does not explicitly contrast itself with adjacent tools like get_fix_context, so it falls short of a full when/when-not statement.

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

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

Annotations already carry readOnlyHint/idempotentHint, so 'Read-only' is largely redundant, but the description adds real behavioral weight: it defines the full state vocabulary (ok | drift | unknown | not_connected | error) and explicitly warns that 'unknown' never means healthy and 'not_connected' means nothing is configured. That prevents an agent from misreading results. It stops short of auth/rate-limit or pagination behavior.

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

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

Front-loads purpose, then the element set, the state vocabulary, the return shape, and finally alternatives — each block serves a distinct need. The inline return-shape JSON is the heaviest part but is justified because there is no output schema. Slightly dense rather than wasteful.

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 takes on the return-value burden itself and lists the full response shape ({ projectId, worst, elements, manifest, snapshotHash }) plus the element state semantics. For a single-param read tool this covers everything an agent needs to call and interpret 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?

Only one parameter with 100% schema description coverage; the schema already documents projectId, its UUID type, the server-configured default, and the `project_id` alias. The description adds nothing beyond it, so baseline 3 applies.

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

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

Specific verb+resource ('Return the App Recipe for a project') with the exact contents enumerated (per-element cards for schema, design, routes, gates, ci, deploy, env, integrations). It also names the sibling tools it is not (get_design_tokens, get_design_deviance, list_gate_findings), so an agent can route without opening any schema.

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

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

'Use to see how the app is put together and which part is drifting' gives the selecting condition, and it explicitly routes to get_design_tokens for token values, get_design_deviance for code that drifts off them, and list_gate_findings for gate detail. When-to-use and alternatives are both explicit.

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

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

Annotations already supply readOnlyHint, idempotentHint and openWorldHint, so the closing 'Read-only' is largely redundant. The description earns credit for real behavioral context beyond them: only one automatic draft may exist, and its failure blocks every subsequent automatic release until a human acts. It stops short of permissions or rate-limit 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?

Front-loads the purpose, then the blocking semantics, then the remedy, then the return shape. Dense but every clause contributes; the trailing 'Read-only' and repeated default note are minor redundancy.

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

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

With no output schema, the description explicitly documents the return contract ({ blockingDraft: { id, version, createdAt, autoSource, stale } | null }), covers the optional parameter's default, and explains the blocking condition. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the single optional projectId is fully documented there, including the 'project_id' alias and the server-configured default. The description restates the default without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return the automatic release draft that is blocking auto-release for one project') with the singleton scope made explicit. No sibling tool covers this, and the phrase 'if any' plus the nullable return makes the query nature unambiguous.

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

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

The description establishes the condition under which a result exists (a failed-publish automatic draft halting later releases) and routes the agent to the resolution paths ('mushi releases publish / delete, or the console Releases page'). It never states an explicit when-not or a named alternative read tool, so it falls just short of the top band.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar for additional disclosure is lower. The description adds value by explaining the traversal origin ('from the report node') and the exact return shape ('{ nodes: [{ id, label, type }], edges }'), which is especially useful since there is no output schema.

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

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

The description is compact and front-loaded. The first sentence states purpose and return format, the second provides usage timing and alternatives. There is no filler or redundant restating of the title.

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

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

For a single-parameter, read-only tool with strong annotations, the description covers purpose, return shape, intended usage, and alternates. It is complete enough for an agent to decide when to invoke it and what to expect in the result.

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

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

The schema covers nodeId as 'Graph node UUID', so baseline is 3. The description adds meaning by indicating the traversal starts from a report node, which clarifies what kind of UUID should be supplied. This is a useful supplement to the schema, though it does not give detailed instructions on locating the nodeId.

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

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

The description states a specific verb ('Return') and resource ('other components/pages a bug group touches'), and clarifies the mechanism ('knowledge-graph traversal from the report node'). It also distinguishes itself from sibling tools by naming get_knowledge_graph and analyze_codebase_impact as alternatives.

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

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

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

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

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

Annotations already declare readOnly, idempotent and openWorld, and the description adds real behavioral context beyond them: score range semantics (0–100, lower is better), that null means not scored, that a scan may still be running, and the finding structure. It repeats 'Read-only' from the annotations, slightly redundant, but the semantic disclosures are genuinely useful.

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 core purpose is front-loaded, then the return payload is enumerated. It is dense and somewhat run-on, but with no output schema present the field enumeration earns its place; minor redundancy in repeating limit and read-only wording.

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 return contract and does so thoroughly: score semantics, rule list, trend, running state, finding fields, and the active-rule enumeration. Combined with the routing note to the sibling, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the limit range and the projectId default. The description only restates the limit range and default, adding no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: it returns the design-deviance score and its breakdown for a project. It also names the sibling it is not (get_design_tokens), so an agent can route correctly without opening either schema.

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

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

Explicitly says when to use it ('to find and fix off-token code') and names the alternative 'get_design_tokens' for the full token list. It does not clarify the relationship to the sibling run_design_deviance (which presumably triggers a scan), leaving a small inference gap.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds real domain semantics beyond that, explaining what each flag actually does (threshold fires actions above it, failCi fails CI on push, autofix dispatches fixes, autofixEnabled gates the whole auto-fix behavior). It doesn't describe error or fallback behavior when no project is configured, so it stops short of a 5.

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

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

A single dense sentence plus two short trailing fragments; the returned fields are front-loaded and the read-only nature is stated last. It is efficient with no filler, though cramming four field definitions into one sentence slightly hurts scannability.

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 describing the return value, and it does so by naming all five fields and their meanings. An agent knows what it gets back and that omission of projectId is safe; only the fallback/error case is unaddressed.

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 single projectId parameter is already fully documented including the snake_case alias. The description only restates that projectId is optional, adding no syntax or scoping detail beyond the schema; baseline 3 applies.

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

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

The description clearly states the verb and resource: it returns the design deviance score's actionable settings for one project, and enumerates the specific fields returned (threshold, failCi, autofix, autofixEnabled, canEdit). It does not explicitly name the write counterpart set_design_settings, but 'Read-only' implicitly frames it against that sibling.

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

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

Usage is only implied: an agent can infer this is the read-side of the settings pair and that projectId scopes it to one project or falls back to the server-configured one. There is no explicit 'use this when... / use set_design_settings when...' routing, which would matter given the paired write tool in the sibling list.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces 'Read-only'. Crucially, it adds behavioral facts annotations cannot convey: the 500-token cap, the exact return shape { projectId, set, tokens, nameMap, total }, and the nameMap direction (CSS var/TS name → token path). It doesn't discuss pagination or how the cap interacts with filters, which is the remaining gap.

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

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

Front-loads the return payload, then the motivating use case, then filters, then the return shape and limit. Dense but every clause carries information. Slightly repetitive in listing both return fields in prose and in { ... } form.

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

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

For a read-only lookup tool with no output schema, the description supplies the return shape, the cap, the nameMap semantics, and routing to the two most relevant siblings. An agent has everything needed to invoke and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds useful framing for group/type/direction (e.g. direction means 'a named token set instead of the active one') but largely restates 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?

States a specific verb (Return) and resource (normalized design tokens) and enumerates the exact payload fields (path, type, resolved value, hex/px, alias, CSS var, TS/RN names, description, defining file). This clearly distinguishes it from siblings like get_design_settings (settings) and get_design_deviance (drift analysis).

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 the primary use case ('makes a fix use the app's tokens instead of hard-coded literals: look up the token for a colour, spacing, radius or font before writing one') and names two alternatives with their distinct purposes: get_design_deviance for drift, get_app_recipe for overall state.

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, and the description goes well beyond them: it discloses the recipe state machine (ok | drift | unknown | not_connected | error, never null), that each section carries its own state and note, and that no second LLM key is required. That is meaningful operational context an agent needs before invoking.

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 content is dense but mostly earns its place given the rich 8-field return. However it is delivered as one sprawling near-sentence packing fixPrompt, recipe, recipe.context and inventoryAction into a single block, which hurts readability. Front-loading is good but structure could be split into digestible lines.

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

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

Despite an output schema already existing, the description fills the remaining gaps an agent would care about: what 'recipe' and 'recipe.context' contain, the guaranteed state enum, and how it relates to sibling tools. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% for both parameters (reportId, projectId plus the snake_case aliases), so the schema already documents them fully. The description adds no extra meaning about the parameters, so the baseline of 3 applies.

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

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

States a specific action and scope ('Bundle everything an agent needs to fix one bug in a single call') and then enumerates the concrete payload sections: fixPrompt, report detail, repro steps, component, root cause, ontology tags, inventory action, and recipe/recipe.context. It also names the distinct siblings (triage_issue, suggest_fix), so an agent can tell this apart from them without opening any schema.

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

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

Explicit routing: 'Use before writing a fix; use triage_issue for a multi-report review packet, or suggest_fix for just the Stage-2 hint.' It gives the when-to-use condition and two named alternatives with the condition that selects each, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description redundantly says 'Read-only.' It adds useful behavioral context beyond the annotations by describing the ordered stage lifecycle and the returned event structure. It does not contradict the annotations, and the safety profile is adequately covered.

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

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

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

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

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

For a read-only single-fix-attempt tool with only two parameters, the description covers what an agent needs: the exact operation, the output shape, when to call it, and which sibling tools to use instead. No output schema exists, but the description provides the return shape directly, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already documents fixId and projectId, including accepted aliases. The description adds no new parameter-level semantics, so the baseline of 3 applies.

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

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

The description names a specific verb ('Return'), a specific resource ('one fix attempt'), and the exact scope ('ordered lifecycle... dispatched, started, branch, commit, PR opened, CI, completed/failed'). It also distinguishes itself from get_report_timeline by explicitly limiting scope to a single fix attempt rather than the whole report thread.

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

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

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

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

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

Annotations already cover read-only/idempotence, and the description goes further by disclosing BFS traversal, a depth budget with default and max, and the returned node/edge structure. It doesn't over-explain beyond what an agent needs.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It gives an explicit use-case signal ('Tuned for "what touches this action?"') and names two alternatives with their distinct seeding conditions. This leaves no ambiguity about when to choose this tool.

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

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

Annotations already cover read-only, open-world, and idempotent behavior, so the description only needs to add extra context. It adds the return shape and, notably, the v2 derived status on Action nodes (ok | stale | broken), which is useful behavioral information beyond the annotations. It does not contradict the annotations.

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

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

Two sentences with no filler. The action is front-loaded, the return shape is compact, and the sibling distinction is placed at the end. Every sentence earns its place.

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

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

Given the single required parameter, a rich output schema, and annotations that already convey the safety profile, the description provides all the operational context an agent needs. It also routes to the relevant sibling tool, making the definition complete for correct selection and invocation.

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

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

Schema coverage is 100%, so the schema already fully documents nodeId as a UUID graph_nodes.id. The description merely repeats 'by id' and adds no additional parameter semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Fetch'), a specific resource ('knowledge-graph node row'), and the lookup key ('by id'). It distinguishes itself from get_graph_neighborhood by clarifying this tool returns a single node's details rather than connections.

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

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

The description explicitly says to use this tool to inspect a single node's status and directs the agent to get_graph_neighborhood for connectivity queries. This gives clear when-to-use and alternative guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'Read-only.' The description adds a non-obvious prerequisite ('Requires the inventory_v2 plan') and documents the return shape, which is especially valuable because there is no output schema. It does not detail all failure modes, but the annotation coverage lowers the burden.

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

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

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

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

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

For a low-complexity tool with one optional parameteramen and no output schema, the description provides the return structure, distinguishes from relevant siblings, and states the prerequisite. An agent has enough information to select and invoke the tool correctly.

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

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

The input schema has 100% coverage: projectId is fully described, including its default behavior and accepted alias. The description adds no new parameter-specific meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Return the current inventory.yaml snapshot' and gives the exact response shape. It also differentiates itself from sibling tools by naming diff_inventory and list_gate_findings and contrasting their purposes.

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

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

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

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint, and the description reinforces the read-only nature while adding behavioral context beyond annotations: the traversal respects a depth budget (default 2, max4 hops) and returns a specific nodes/edges structure. It does not contradict any annotation.

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

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

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

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

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

For a read-only traversal tool with only one required parameter and a rich output schema, the description covers the key behavioral constraints (depth default/max), the intended usage, and the sibling differentiation. Nothing essential for an agent to correctly select and invoke this tool is missing.

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

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

Schema description coverage is 100%, with seed and depth already documented. The description loosely reinforces these concepts by calling the seed a 'component or page' and mentioning the depth budget, but it does not add meaningful semantic details beyond the schema.

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

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

The description states a specific action and resource: 'Traverse the knowledge graph from a seed component or page.' It also names the return shape (nodes and edges) and explicitly differentiates from sibling tools by pointing to get_blast_radius and get_graph_neighborhood, making the purpose unambiguous.

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

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

It explicitly says when to use this tool: 'Use to see how a component connects to the rest of the app.' It also names alternatives and their specific use cases: get_blast_radius for a bug's impact area and get_graph_neighborhood for a tighter BFS around one node.

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

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

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

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

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

Three concise sentences, front-loaded with the core purpose and return format. Every sentence adds value: the input source, the return structure, the truncation behavior, the indexing caveat, and the usage timing. No fluff or repetition.

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

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

For a single-parameter tool with a detailed output schema and annotations covering safety, the description covers all necessary aspects: input source, output format, size limits, prerequites (indexed pages), authentication (no API key), and when to use. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% (the page parameter is described as 'A url from search_mushi_docs, or a docs route such as \"/quickstart/mcp\"'). The description adds a concrete example route and reinforces the two accepted input forms, which slightly enriches the schema but is largely redundant. Since coverage is high, baseline is 3, but the example and explicit mention of the search source push it to 4.

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

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

The description clearly states a specific verb+resource: 'Fetch one official Mushi docs page as Markdown'. It also distinguishes from siblings by mentioning the source (url from search_mushi_docs) and the trigger condition ('Use after search_mushi_docs when an excerpt is not enough'). This makes the tool's purpose unambiguous.

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

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

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

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the bar is lower, yet the description still adds substantial behavioral context: auth requirements and the 403 outcome, the ORG_REQUIRED 400 disambiguation, and detailed failure semantics (readErrors, unreadable columns reported as unknown rather than zero, holes null when integrations can't be read). It also defines non-obvious enum members ('unknown and not_connected never mean healthy', 'never_run means not checked yet').

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

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

Front-loaded with purpose, and with no output schema every sentence about card fields, return keys and failure handling earns its place. The opening sentence is a long run-on enumeration with heavy parentheticals, which slightly hurts scannability, but there is essentially no filler to cut.

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

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

For a read tool with no output schema, the description supplies what an agent actually needs: the full return shape ({organizationId, organizationName, cards, totalProjects, repeatedGroups, holes, readErrors}), the meaning of ambiguous card states, auth and error-code behavior, and the routing alternative. Nothing needed to call it correctly is missing.

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

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

With a single parameter at 100% schema coverage, the baseline is 3; the description goes beyond the schema's 'defaults to the key owner's only organization when omitted' by explaining the multi-org failure path (400 ORG_REQUIRED lists the choices). UUID format itself is left to the schema, so it is not a full 5.

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

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

Opens with a precise verb+resource+scope ('Return every project in one organization as a card') and immediately enumerates what each card contains. It also distinguishes itself from the nearest sibling by routing two-or-more-app problems to list_portfolio_findings, so an agent can separate the two without opening either schema.

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

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

States the alternative explicitly and the condition that selects it ('Use list_portfolio_findings for the problems open in two or more apps'), and gives the orgId-omission decision path plus the 400 ORG_REQUIRED branch when several organizations exist. The auth precondition (account-level key vs 403 for a project-bound key) is spelled out rather than implied.

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

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

Annotations already cover readOnlyHint, idempotentHint and openWorldHint, so the 'Read-only' sentence is largely redundant. The description does add genuinely non-structured semantics: the four possible states (ok | finding | unknown | error) and the crucial clarification that 'unknown means not checked and never means healthy', plus that each finding carries a plain-English reason and a fix. It does not repeat annotation content as its only contribution, so it clears the lower bar set by 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 opening clause front-loads the core purpose before the long enumeration of check types, and the scope semantics follow. It is a single dense paragraph rather than a bulleted list, so the enumeration of check categories is heavy to read, but no sentence is pure filler.

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

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

With no output schema, the description carries the burden of describing returns and does so well: it specifies the four states, the presence of a plain-English reason, and per-finding fixes, which is exactly what an agent needs to interpret results. The one shortfall is that it never mentions the run_radar sibling, so an agent asked to re-run checks is pointed at a UI page instead of an available 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 baseline is 3. The description exceeds it by explaining defaulting behavior and interaction between parameters that the schema only states tersely: projectId is optional and falls back to the server-configured project, organizationId is optional and falls back to the key owner's only organization, and organization scope requires an account-level key.

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 concrete verb and resource ('Return the hole checks') and then enumerates the specific defect classes it surfaces (store name mismatches, missing listing languages, expiring certs, broken privacy links, orphaned storage rows, rejected target SDKs). It implicitly distinguishes itself from the sibling run_radar by framing the tool as a read-only retrieval of existing check results rather than a trigger.

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

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

It gives clear conditional guidance for the two scopes: 'project' (default, projectId optional) returns every check with state, while 'organization' (organizationId optional, account-level key) returns open findings across all apps. However, it does not name the sibling tool run_radar as the way to re-run checks, instead pointing at 'the console Recipe page', which is a UI instruction rather than a tool alternative an agent can act on.

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

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

Although annotations already declare readOnlyHint=true, idempotentHint=true, the description adds important behavioral context: it promises newest-first ordering, discloses that includeRaw=true changes the returned columns, and states that reporter identifiers are never returned. This goes beyond the annotations without contradicting them.

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

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

The description is dense but front-loaded with the core purpose and return shape, followed by filters and routing guidance. It earns its length because it packs meaningful details (never returns reporter IDs, includeRaw behavior, limit defaults), but a sentence or two could be trimmed since some filter details duplicate the schema enums.

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

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

With an output schema present and annotations covering read-only/idempotent safety, the description still supplies what an agent needs: ordering, optional filters, limit bounds, includeRaw semantics, the never-returned reporter data, and routing to siblings. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly, including enums and aliases. The description itself repeats some filter details (status/category/severity enums, limit defaults) and adds the note that reporter identifiers are never returned—useful but not a major compensation need. Baseline 3 is exceeded slightly because the description reinforces the key filter semantics and the default/max limit, but it also largely duplicates the schema.

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

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

The description states a specific verb and resource ('List recent bug reports for a project, newest first'), specifies the return shape, and distinguishes itself from siblings by naming alternatives (get_report_detail, search_reports). The scope (project, newest first) is clear, and the presence of filters reinforces its purpose.

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

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

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

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: the status state machine (queued → running → pr_opened, rejected, failed), that error carries the failure reason, and that a job past its deadline reads as failed.

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

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

Purpose is front-loaded in the first clause, followed by the return-field list and lifecycle semantics. Slightly dense with the inline field enumeration, but every element earns its place given there is no output schema.

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 compensates by enumerating the returned fields and explaining the terminal statuses and deadline failure behavior. Combined with the jobId/projectId guidance, an agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the projectId default. The description only notes 'Optional projectId' and the jobId source, adding no syntax or format detail beyond what the schema provides — the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return one recipe change job by jobId') and names propose_recipe_change as the originating tool, which lets an agent distinguish it from other get_* siblings without opening a schema.

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

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

The description makes the usage context clear by tying jobId to the value propose_recipe_change returned, implying this is the follow-up status-polling call. It does not state explicit when-not conditions, but there is no competing sibling that would be confused with it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: it clarifies that despite returning suggestedFixes it never applies them ('Mushi never runs DDL or edits workflows'), and it explains the semantics of the gate status (never_run means not checked, never healthy).

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 purpose and return structure are front-loaded, and the long enumeration earns its space because there is no output schema to carry it. It is dense and somewhat run-on, but not padded with filler.

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

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

With no output schema, the description carries the full burden and delivers: it spells out the return shape ({ projectId, gates, findings }), the field-level meaning of findings and gate status, and the follow-up action for applying fixes. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% with a single optional projectId, so the schema already documents the parameter fully (including the project_id alias). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Return what drifted from the app recipe') and then enumerates the exact drift categories it detects (CI workflows, deploys, env names, migrations, off-token design values). This clearly separates it from siblings like get_app_recipe (which returns the recipe itself) and get_design_deviance.

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

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

Usage is implied by the rich enumeration of what it detects — you call it to find drift and get fixes — but the description never names an alternative (e.g. get_app_recipe, list_gate_findings, get_design_deviance) or states when-not to use it. The trailing note on applying fixes hints at a boundary but does not route between tools.

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

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

Annotations only declare readOnly/idempotent/openWorld, but the description adds substantial non-obvious behavior: files are read from the default branch head, files over 512 KB or containing secret-shaped content return content null, and stale shas cause refusal at propose time. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with purpose, then behavior, then return shape and the read-only note; nearly every clause earns its place. The parenthetical enumerations of element values duplicate the schema, which is the only minor 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?

There is no output schema, yet the description fully specifies the return envelope ({ ok, element, branch, headSha, files } or { ok: false, reason }) and the per-file fields { path, exists, content, sha, writable, reason }. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description largely repeats the enum semantics verbatim. It adds only 'Optional projectId', which the schema already conveys via the description and non-required status. Baseline 3 is appropriate.

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

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

States a specific verb+resource with scope: 'Return the repo files a recipe change may edit for one part of the recipe', then enumerates the three element variants. An agent can distinguish this from siblings like get_app_recipe, get_recipe_change, and propose_recipe_change without opening a schema.

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

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

Gives a concrete workflow instruction: 'Pass each sha as baseSha to propose_recipe_change so a file that changed since is refused', which tells the agent this tool feeds the propose workflow. It does not state when NOT to use it or name alternative sources of similar info (e.g. get_app_recipe), so it falls short of a 5.

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

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

Goes well beyond the readOnlyHint/idempotentHint/openWorldHint annotations by disclosing failure modes (400 ORG_REQUIRED with a list of choices, 403 for project-bound keys), the auth model, and the critical behavioral fact that the tool only proposes a batch rather than executing a release. 'Read-only' does echo the annotation, but the surrounding detail is substantive.

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

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

Purpose is front-loaded and every sentence carries information (contents, batching semantics, defaults, auth, return shape). The prose is dense and somewhat comma-spliced into long clauses, but nothing is filler.

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

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

With no output schema, the description compensates by naming the return keys ({ rows, batchSuggestion, note }), and it covers scope, defaults, error codes, and permission requirements. An agent has everything needed to call this correctly without opening the 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 coverage is 100% for the single organizationId param, so the baseline is 3; the description adds real meaning by spelling out the omitted-parameter fallback and the multi-organization error path (400 ORG_REQUIRED lists the choices), which the schema description does not mention.

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

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

States a specific verb and resource ('Return the release calendar of one organization') and enumerates exactly what it contains: live apps, merged-but-unshipped fixes, store state, and a release batch suggestion. This is clearly distinguishable from siblings like get_store_status and get_auto_release_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?

Explains the workflow boundary explicitly — 'Mushi only proposes the batch; your CI builds and submits' — which tells the agent what this tool will and will not do. It also gives the key-scope precondition (account-level key vs project-bound 403), though it never names an alternative sibling tool to use instead.

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

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

Annotations already cover readOnly/openWorld/idempotent, but the description adds substantial context beyond them: the null-when-undrawn behavior, how a diagram gets created (console Repo page, one AI call per commit), the side effect of overlay:true (adds open bugs/findings mapped by stack frames and paths), and that no indexing is required. These are precisely the behaviors an agent needs that the annotations cannot express.

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

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

Front-loaded with the core purpose and return shape, then details. It is dense and somewhat run-on with colon/parenthesis packing, but nearly every clause earns its place by carrying distinct behavioral or return-format information rather than restating structured fields.

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

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

No output schema exists, yet the description documents the return envelope ({diagram, publication}) and the overlay variant's shape, including the null cases. Combined with the creation prerequisite and indexing note, an agent has everything required to call and interpret the tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond the schema by spelling out the concrete effect of overlay:true and the meaning of the overlay payload fields (unplaced, frames_matched, considered). projectId is only labeled 'Optional', which the schema already conveys, so it adds little there.

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

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

States a specific verb and resource ('Return the latest architecture diagram of the connected repo') and enumerates what the diagram contains (nodes with label/group/path/description, edges, commit, publication). It explicitly differentiates itself from the sibling get_repo_digest, which returns the code itself. An agent can tell exactly what this tool produces without opening the schema.

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

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

Gives an explicit when-to-use ('see where a bug sits in the app before reading code') and names the alternative with its selecting condition ('use get_repo_digest for the code itself'). It also states a key prerequisite/context ('Works without codebase indexing') and explains the null state arises until a diagram is drawn from the console Repo page.

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

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

Annotations only cover the safety profile (readOnly/idempotent/openWorld); the description goes well beyond by disclosing that .env/keys are never included, secret-looking files are replaced with a notice, token counts are estimates, ordering is README → manifests → entry points → source → tests, and it works without indexing. These are exactly the behavioral traits an agent needs before relying on the output.

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 core purpose and the return shape are front-loaded, and with no output schema the return-field enumeration earns its place. It is dense, though the first sentence runs long enough that some detail could be trimmed.

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 fully compensates by spelling out the returned object (sha, ref, total_tokens, files, dropped_counts, redacted, scope, text). Combined with the redaction and indexing caveats, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: budgetTokens default and max, that reportId prioritizes stack-frame files, fix files and related code then the files that import them, and the ranking/scope behavior of path. The exclude/include and projectId params get no extra narrative, keeping it below a 5.

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

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

States a specific verb and resource ('Return the connected GitHub repo as one paste-ready text digest at a pinned commit') and immediately differentiates itself from siblings by naming get_fix_context and search_codebase. The agent can tell exactly what artifact this produces without opening the schema.

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

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

Explicitly routes usage: 'Use to hand yourself the code around a bug before fixing it; use get_fix_context for the diagnosis, or search_codebase to find one thing.' It also gives both scoping modes (path vs reportId) with the condition that selects each, so when-to-use and alternatives are fully covered.

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

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

Annotations already provide readOnlyHint and idempotentHint, and the description adds valuable behavioral context: reporter identifiers are never returned, includeRaw=true returns every column instead, and the response is wrapped in { report }. These details go well beyond what the annotations convey.

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

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

Every sentence earns its place: purpose, content list, response shape, privacy note, read-only statement, usage scenario, and sibling alternatives. It is dense but not bloated, and the most important information is front-loaded.

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

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

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

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

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

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

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

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

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

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

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

Explicitly says 'Use when you have a reportId and need everything about it' and gives conditional routing to get_report_evidence, get_report_timeline, and get_fix_context. This is textbook when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral disclosure beyond those hints: reporter identifiers (session id, end-user id) are never returned, and the evidence package is explicitly scoped to a single bug report. This is meaningful context about what the tool will and will not surface.

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

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

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

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does so thoroughly: it lists logs, traces, metrics, screenshot, browser environment, tags, and explicitly states what is excluded. It also gives the relationship to sibling tools and the efficiency benefit. An agent has enough information to call the tool correctly and interpret the result.

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

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

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

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

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

The description opens with a specific verb and resource: 'Return the full evidence package for a single bug report.' It enumerates exactly which data is included across logs, traces, and metrics, and explicitly distinguishes itself from get_report_detail and get_report_timeline. This makes it immediately clear what this tool does and how it relates to siblings.

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

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

The description gives clear context for when to use the tool: it returns the data an engineer would collect for root-cause investigation, and it is faster than calling get_report_detail and report timeline separately. It names alternatives and positions this tool as their combined, faster replacement, but it does not explicitly state when-not-to-use it or compare it with more decision-oriented siblings like get_fix_context or suggest_fix.

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

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

Annotations already supply readOnlyHint, openWorldHint, and idempotentHint. The description adds value by stating the ordering (oldest to newest), the merging behavior across multiple event streams, and the exact return shape. It does not mention potential rate limits or additional access constraints, but for a read-only getter this is sufficient context beyond the annotations.

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

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

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

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

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

Despite having no output schema, the description includes a concrete return shape, names the sibling tools for contrast, and clarifies ordering and merge scope. With only one parameter and annotations covering safety/idempotency, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, and the parameter description already explains that reportId is the report UUID and accepts report_id. The tool description adds no extra parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

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

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

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

Provides explicit guidance: use for an end-to-end view of a report thread, with named alternatives get_report_detail for the static record and get_fix_timeline for debugging a single fix attempt. This is a model of when-to-use/when-not-to-use direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond those: it explains the retrieval technique (pgvector nearest-neighbour), the tuning intent, and the ranked return shape. No contradiction with annotations.

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

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

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

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

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

For a two-parameter read-only tool with an output schema, the description covers what it does, what it returns, when to use it, and how it differs from search_reports. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents query as 'Component name, page path, or bug description' and limit with default/max. The description mostly restates this information without adding new parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Find existing bugs similar to...') and names the underlying mechanism (pgvector nearest-neighbour search). It also distinguishes itself from the sibling search_reports by noting it is 'tuned for "have we seen this before?"'.

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

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

Explicit usage guidance is provided: 'Use to dedupe before filing or group regressions; use search_reports for general free-text search.' This tells the agent exactly when to choose this tool versus the relevant alternative.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint), so the description adds real context: the intake is off by default, sources report connected=false when the stored key cannot be read, only the 20 most recent reviews are returned, and canManage/canPull expose caller-level authorization. That is useful behavioral nuance 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?

One dense sentence front-loads the purpose and then enumerates the return shape, which is justified because there is no output schema. It is long but every clause carries field-level information; no filler sentences.

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 compensates by fully enumerating the returned settings, sources, review fields and permission flags, and it notes the 20-review cap and default-off state. What is missing is the tool's relationship to pull_store_reviews / set_store_review_intake, but nothing needed to invoke it correctly is absent.

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% for the single optional projectId, including the server-default fallback and the accepted alias. The description only repeats 'Optional projectId', adding nothing the schema does not already state, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Return the store review intake of one project') and enumerates the exact payload (settings, per-store sources, 20 most-recent reviews, caller permissions), which clearly separates it from action-oriented siblings like pull_store_reviews or run_store_review. However, it never explicitly names an alternative, so differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance and no comparison to the reads it overlaps with (get_store_status, pull_store_reviews, set_store_review_intake). 'Off by default' hints at a precondition state but does not tell the agent what to do when intake is disabled or which sibling to call instead.

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

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

With annotations already covering readOnly/openWorld/idempotent, the description still adds substantial behavioral context beyond them: it discloses the result vocabulary (ok | finding | unknown, noting 'unknown' means not checked rather than healthy), explains the never_run status and that it is triggered from the console, and states the return shape. This is exactly the extra behavior an agent needs when annotations alone would leave gaps.

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 main purpose and the 'what gets checked' list are front-loaded, and the operational notes (result states, never_run, return shape, read-only) follow at the end. It is dense and long but each clause carries information; the illustrative examples in parentheses ('never leaves your phone') earn their place as clarification.

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, and the description compensates by listing the returned fields (projectId, checkedAt, status, results, checklist, findings) plus the status/finding value semantics, which is complete for a single-parameter read. Only minor details such as auth or expected latency are absent, and those are not essential here.

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

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

There is a single parameter (projectId) with 100% schema description coverage, including the default-to-server-config note, so the schema already carries the semantics. The description adds nothing about projectId or how the default project is resolved, so baseline 3 applies.

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

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

The description gives a specific verb+resource ('Return the latest store review of an app') and then enumerates exactly what a store review covers (listing drift, claim-vs-code contradictions, privacy labels, screenshots, checklist). This makes it clearly distinct from user-review siblings, but it never names an alternative such as run_store_review or get_store_reviews, so sibling differentiation is left to inference.

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

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

Usage is implied rather than stated: 'it runs from the console' and the never_run explanation hint that this tool reads existing results rather than triggering a run. There is no explicit when-to-use/when-not-to-use guidance and no named alternative, but the read-only framing and 'not legal advice' caveat give the agent enough to infer the correct 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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral context by listing what the summary includes and the verification purpose (confirming two-way delivery), which helps the agent set expectations about output content beyond the generic annotations.

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

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

Two sentences, no fluff. The first sentence front-loads the core purpose and deliverables; the second provides the actionable usage context. Every phrase earns its place, and the key scope ('two-way') is stated immediately.

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

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

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

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

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

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

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

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

The description states a specific verb ('Summarize') and resource ('SDK ↔ admin two-way reporter health for a host app'), then enumerates the exact data points covered. This makes it clearly distinguishable from siblings like get_recent_reports or reply_to_reporter, which focus on one side of the communication flow.

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

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

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

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

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

Goes well beyond the annotations (which only say write, idempotent, non-destructive, open-world): it discloses dedup-per-issue semantics, that already-linked issues return 'linked' and are never reopened, that each new report spends classification budget, and the exact auth prerequisites (org slug, project slug, token with event:read/project:read in Integrations → Sentry). That is the kind of operational detail an agent needs before invoking.

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

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

Front-loaded with the core action and mode choice, then pagination, then side effects and auth. Dense and information-rich, but it is one long undivided block with some run-on sentences, so the cursor/sinceDays/cursor-loop and the auth requirement are harder to scan than they should be.

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 7-parameter, zero-required, open-world write tool this covers everything: both input modes, pagination, per-item outcomes, auth and scope requirements, budget cost, and idempotency. An output schema exists, yet the description still names the return envelope and nextCursor, which is helpful rather than redundant.

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

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

Schema coverage is 100%, so the baseline is 3, but the description synthesizes cross-parameter workflow meaning the schema cannot: mutually exclusive issueIds vs. query modes, the sinceDays/cursor pagination loop, and sentryProject selecting another of the project's Sentry projects. It adds real relational context, though several per-parameter facts (limits, 'search mode only') are duplicated 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?

States a specific verb and resource ('Pull existing Sentry issues into Mushi's report queue') and immediately distinguishes the two input modes (issueIds vs. a Sentry search query) that no sibling tool offers. An agent can tell this apart from triage_issue, search_reports, or the webhook path without opening the schema.

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

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

Gives clear situational context ('Use for issues that existed before the webhook was wired'), explains how to work a backlog (sinceDays + cursor loop until nextCursor is null), and routes to the follow-up tool (triage_issue on a created report). It does not state an explicit when-not or name a sibling that does the same job instead, so it stops short of a 5.

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

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

Annotations already cover readOnly/idempotent/openWorld, but the description adds real behavioral value: it guarantees the raw secret is never returned, explains the pooled vs. legacyKeys split, and enumerates the returned fields and status values. That is disclosure well 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?

Front-loads purpose, then behavior, then routing in a tight sequence. The inline return-shape block is dense but earns its place given there is no output schema; only minor redundancy in restating "Read-only" alongside the readOnlyHint annotation.

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

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

With no output schema, the description fully compensates by describing the return envelope ({ keys: [...] }, legacyKeys) and field names. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100% and the single projectId parameter is fully documented in the schema, including the alias note. The description adds nothing about the parameter, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ("List the project's BYOK API keys") and adds the grouping dimension (by provider) with the enumerated provider slugs. It is clearly distinguishable from siblings like add_byok_key, test_byok_key, and remove_byok_key.

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

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

Explicitly says when to use it ("Use to see which keys are validated, active, pending, legacy, or rate-limited") and routes to add_byok_key for the add case. It does not mention test_byok_key or remove_byok_key as alternatives, so coverage of siblings is partial rather than complete.

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

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

Annotations already cover readOnlyHint/idempotentHint, and the description goes well beyond them: 'Never returns credentials' is a meaningful data-exposure guarantee, 'account-level key needed' is an auth prerequisite, and 'blocked means an outside party refuses, for example an App Store agreement not accepted' explains a non-obvious status value.

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

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

Front-loaded with purpose, then the status semantics, then the parameter/auth note, then the return shape — a logical order. The middle clause is a dense run-on list of fields, but nothing is padding.

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

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

With no output schema, the description compensates by naming the response keys ({ organizationId, available, planned, instances, legacy }) and distinguishing 'available' vs 'planned' kinds, plus flagging the credential omission. An agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, and the schema's own description already explains the default-to-key-owner behavior, so the description's 'Optional organizationId' is largely redundant. Baseline 3 is appropriate when the schema carries the parameter semantics.

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?

Specific verb+resource ('List the sources connected to an organization') immediately followed by a precise inventory of what each entry contains (kind, status, scopes, capabilities, project bindings). The 'Read-only' closing statement cleanly separates it from the sibling 'request_connector_action', which is the mutating counterpart.

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

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

Usage is implied by the enumeration of connector state and the note that an account-level key is needed, but no explicit when-to-use/when-not or named alternative is given. It never tells the agent to prefer this over 'request_connector_action' when it actually wants to change a connector, leaving routing to inference.

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

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

Annotations already cover readOnly/idempotent/openWorld, but the description adds real behavior: newest-first ordering, that radar findings carry a suggested_fix, and a non-obvious auth constraint (a spend-cap fix is applied in the console by a signed-in project admin, not through an API key). It doesn't mention pagination or result limits despite 'recent' runs, and 'Read-only' partially repeats readOnlyHint.

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

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

Front-loaded with purpose, then return shape, filters, gate semantics, then usage. The bulk of the length comes from restating the 18-value gate enum already present in the schema, which is somewhat duplicative, but the surrounding explanation earns most of the space.

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

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

An output schema exists, so the description need not explain returns, yet it covers filtering, plan availability, gate semantics, sibling routing and an auth caveat. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning to the enum values — it explains that design_drift is code drifting off design tokens, ci_drift/deploy_drift/env_drift relate to recipe drift, and radar covers setup checks. That is semantic enrichment the bare enum does not provide.

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

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

States a specific verb+resource+scope: 'List recent inventory gate runs and their findings for a project, newest first.' It also distinguishes itself from siblings by naming get_radar, diff_inventory and get_inventory, so an agent can route without opening schemas.

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

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

Gives an explicit use case ('see which CI gates failed on the last crawl') and names the alternatives with their selecting conditions ('use diff_inventory to compare two commits, or get_inventory for the full snapshot', 'prefer get_radar' for portfolio/store gates). Routing is unambiguous.

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

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

Annotations already cover read-only, idempotent, and open-world behavior, and the description reinforces 'Read-only'. Beyond that, it adds behavioral context about 'promoted' lessons and highest-frequency-first ordering. The return shape is mentioned but the output schema already covers it, so this is useful but not critical extra disclosure.

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

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

Three sentences deliver the purpose, output shape, read-only trait, and usage alternative with zero filler. The most decision-relevant information (what it lists and how it is ordered) is front-loaded.

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

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

Given the output schema, annotations, and fully documented parameters, nothing essential is missing. The description also supplies the key sibling-routing information, making it complete for an agent to select and call this tool correctly.

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

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

Schema description coverage is 100%, so limit, severity, and projectId are already fully documented. The description adds minimal parameter-level meaning beyond confirming the 'current project' default, which is consistent with projectId. It does not need to compensate for schema gaps.

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

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

The description states a specific action (List), a specific resource (promoted learning rules/lessons for the current project), and a concrete behavior (highest-frequency first). It also distinguishes itself from query_lessons by describing the full-catalog browsing purpose, making it easy to tell apart from siblings.

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

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

The description explicitly says when to use this tool ('browse the full catalog of encoded heuristics') and when not to, naming query_lessons as the alternative for diff/PR-specific retrieval within a token budget. This gives clear routing guidance with no inference required.

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

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

Adds substantial context beyond the readOnly/openWorld/idempotent annotations: it defines 'open' (latest completed gate run per project and gate, not allowlisted), notes info findings are excluded, states an account-level key is required, and explains that a part named in readErrors is unknown rather than empty. This is exactly the behavioral detail the annotations cannot convey.

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

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

Purpose is front-loaded and every sentence carries information (definition of open, auth requirement, return shape, sibling routing). It is dense and long, but not padded — the density is justified by a complex multi-part return.

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 fully specifies the return shape ({ organizationId, groups, sdkSkew, holes, crossProject, readErrors }) and the readErrors caveat. Combined with the auth note and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single organizationId param is fully documented in the schema, so baseline is 3. The description only adds a cross-reference ('as for get_portfolio') rather than new syntax or meaning.

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

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

States a specific verb and resource ('Return what to fix across the apps of one organization') and enumerates the three things returned: cross-project finding groups, SDK version skew, and integration holes. It is clearly distinguishable from list_gate_findings (single project) and get_portfolio (referenced by name for the orgId convention).

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

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

Explicitly routes the agent to list_gate_findings for per-project work and references get_portfolio for the organizationId convention, giving clear usage context. It does not state outright when NOT to use this tool, but the sibling references effectively cover the selection decision.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description repeats 'Read-only' but adds real context: which message types are held, that text is exactly what the reporter will see, and the meaning of an empty list. The empty-list disclosure is genuinely useful behavior beyond structured fields.

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

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

Front-loaded with the purpose before the row-shape detail and the routing hint. It is dense but every clause (message types, row fields, empty-list meaning) carries information, though it packs several concerns into a single sentence.

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 compensates by enumerating the row fields and clarifying text semantics. Combined with annotations covering the safety profile and the routing to release_reporter_update, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% with a single optional projectId, so the schema already documents the parameter fully. The description adds no syntax or defaults beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (held reporter updates / pipeline messages waiting for review), and precisely scopes what it covers: messages held by projects in review mode. It is clearly distinguishable from siblings such as release_reporter_update and get_report_detail.

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

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

Explicitly routes the agent: 'Use before release_reporter_update', and explains the consequence of an empty result ('nothing is waiting, or the project sends updates automatically'). This names the alternative tool and the condition that selects it.

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

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

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

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

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

The description is dense but every sentence earns its place: outcome, return shape, destructiveness, idempotence, prerequisite, and sibling routing. It is front-loaded with the core action and return value before safety context, and no filler or redundant restatement appears.

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

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

With an output schema present, annotations covering safety, and a description covering irreversibility, idempotence, prerequisites, and alternatives, an agent has everything needed to decide whether and when to call this tool. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents fixId and mergeMethod, including the accepted alias fix_id and the default merge method. The description adds little parameter-level detail beyond aligning with the squash default, which is acceptable given the high schema coverage.

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

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

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

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

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

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

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

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

Adds substantial behavior beyond the annotations: dry-run default, the fact that 'One repo failing never rolls back the others; each result says what happened,' and the auth requirement ('Needs an account-level key'). For an openWorld, non-idempotent write, these are exactly the traits annotations can't convey.

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

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

Front-loads purpose, then default mode, failure semantics, prerequisites, and return shape in a tight block. No sentence is filler, and the return schemas are spelled out in place of a missing output schema.

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

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

No output schema exists, so naming '{ dryRun, plans }' versus '{ batchId, opened, results }' and flagging partial-failure behavior and account-level auth makes it callable without extra digging. The only real hole is the missing contrast with the single-repo sibling.

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 60%, so the schema carries most parameter meaning. The description only reinforces confirm's dry-run default (already in the schema) and the 10-repo cap; it adds nothing about element, changes, edits, or baseSha, so value over structured fields is marginal.

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

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

States a specific verb and resource plus unusual scope: 'Propose the same kind of recipe edit in up to 10 repos of one organization, one draft PR per repo with a shared batch id.' The multi-repo batch scope implicitly sets it apart from the singular propose_recipe_change, but that sibling is never named, so the differentiation is left to inference.

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

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

Gives clear operational context: dry run by default, 'confirm: true opens the drafts', and a procedural rule 'Confirm with the user before confirm: true.' Strong on how to drive it, but it never says when to pick this over the single-repo sibling or what qualifies a portfolio-sized change.

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

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

Annotations only say openWorld=true, idempotent=false, destructive=false. The description adds the safety model that matters: the PR stays a draft so repo CI does not run, nothing is merged or published, baseSha pinning prevents reverting someone else's edit, and malformed content (mushi.recipe.json, the inventory) is rejected.

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 lead sentence front-loads purpose and output (draft PR), and nearly every clause carries operational meaning. It is a dense run-on paragraph with heavy parentheticals, so it is slightly harder to scan than it could be.

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

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

No output schema exists, yet the description names both return shapes ({ dryRun, files, denied } and { jobId, status, prUrl }), covers prerequisite (user confirmation), versioning (baseSha), and validation failures. Nothing needed to call it correctly is missing.

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

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

With 60% schema coverage, the description compensates by mapping element/edits to concrete recipe surfaces (design tokens, budgets, .env.example, store listing text) and explaining the baseSha round-trip and confirm semantics. It does not touch title or projectId, so it is strong but not exhaustive over all five parameters.

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

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

States a specific verb+resource (propose edits to recipe-allowed files as ONE draft pull request) and enumerates the exact scope: design tokens, mushi.recipe.json budgets, .env.example, store.listingDir. An agent can distinguish it from siblings like propose_portfolio_change or get_recipe_change without opening a schema.

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

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

Gives explicit when-behavior (dry run by default) and when-not (confirm is refused if a file changed since the dry run; confirm: true requires user confirmation first). It also specifies what is never writable (workflows, env files, lockfiles, generated exports, migrations), making the boundary unambiguous.

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

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

Discloses error codes (400 INTAKE_OFF, 429 RATE_LIMITED), the viewer restriction, deduplication against earlier pulls, that reports are subsequently classified, and that store keys are spent read-only. This goes well past the annotations' write/openWorld profile.

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

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

Front-loaded with the core action and efficient, with prerequisites and return shape packed in. Dense but every clause carries information; the trailing one-word 'Write.' is slightly redundant against the annotation.

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

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

With no output schema, the description supplies the return shape ({ status, filed, stores }) plus prerequisites, side effects, and error behavior. An agent has everything needed to decide 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?

Schema description coverage is 100% and the parameter is fully documented there, including the project_id alias. The description only restates that projectId is optional, adding no syntax or format meaning beyond the schema; baseline 3 applies.

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

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

Names a specific verb (pull), the exact resource (App Store and Google Play reviews), and scope (one project, now). It also names the output artifact (reports with source store_review), so it is distinguishable from read-only siblings like get_store_reviews and run_store_review.

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

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

Gives clear operational context: intake must be on, rate limited to one pull per 10 minutes, and blocked for viewers. It does not explicitly name which sibling to prefer when you merely want to read reviews (get_store_reviews), so the routing guidance is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is well covered. The description adds non-obvious behavior: bi-encoder retrieval, severity-weighted scoring, and token-budget packing, which are valuable beyond annotation hints.

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

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

Three dense sentences front-load purpose, then mechanics, then usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

The description is complete for a read-only retrieval tool: it states the return shape ({ lessons: [...] }), usage context, and distinguishes from sibling list_lessons. With full schema coverage and safety annotations, no critical information is missing.

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

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

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

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

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

States a specific verb ('retrieve'), resource ('learning rules/lessons'), and context ('code diff or PR'). The description explicitly contrasts with list_lessons, naming what it is not and making sibling differentiation immediate.

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

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

Gives explicit when-to-use guidance: 'Use before writing a fix or opening a PR'. It also names the alternative list_lessons for browsing all lessons unfiltered, providing a clear decision boundary.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral value by explaining that the write is a local persistence on the fix_attempt row and explicitly denies any external GitHub mutation, which is important context beyond the annotation booleans.

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

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

The description is three sentences with no wasted words. It front-loads the main behavior, then states side effects, return value, and usage guidance, making it easy to scan and act on.

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

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

For a single-parameter, idempotent write operation with rich annotations, an output schema, and explicit sibling routing, the description covers everything needed to invoke it correctly. It communicates the write target, the external side-effect boundary, the return shape, and the recommended usage context.

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

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

There is only one parameter and schema description coverage is 100%, so the schema fully documents fixId, including the accepted alias fix_id. The description reinforces that the parameter refers to the fix attempt whose PR check-runs should be re-polled, but adds no new semantic detail beyond the schema.

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

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

The description states a specific action and resource: re-poll GitHub for a fix attempt's PR check-run status and persist it on the fix_attempt row. It also explicitly differentiates itself from related tools by clarifying it does not merge or mutate GitHub, making it easy to distinguish from merge_fix and get_fix_timeline.

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

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

The description gives explicit usage context: use it right before merge_fix to confirm CI is green, and use get_fix_timeline when the full attempt lifecycle is needed. It also lists an exclusion, stating it does not merge or mutate GitHub, which prevents misuse.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds the rate limit ('at most once per project every 5 minutes (429 RATE_LIMITED otherwise)') and the crucial side-effect clarification that it stores a snapshot while 'nothing in the repo changes'. That is exactly the kind of context annotations cannot carry.

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?

Dense but front-loaded: the action and rate limit come first, then the return shape, then usage routing. Every sentence earns its place, though the return-field enumeration makes it a single long paragraph with no visual 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?

With no output schema, the description takes on the burden of describing the return payload (state enum, issues list, tokensHash, manifestPresent, tokenCount) and does so fully. Rate limits, side effects, and next steps are all covered for a tool with one optional parameter.

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 single projectId parameter is already documented, including the `project_id` alias. The description only notes it is optional, which the schema's empty required list already conveys – baseline 3 applies.

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

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

States a specific verb+resource ('Read mushi.recipe.json and the design-token files ... and store a new recipe snapshot') and explicitly contrasts with the daily refresh. An agent can distinguish it from get_app_recipe and get_design_tokens without opening either schema.

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

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

Gives both the trigger ('Use after editing mushi.recipe.json or the tokens') and the follow-up ('then read get_app_recipe or get_design_tokens'), plus the alternative it replaces ('instead of waiting for the daily refresh'). Nothing about when to invoke it is left to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true): it discloses that this messages a real end user, requires user confirmation, returns CONFLICT instead of double-sending when the message is no longer held, and gives the response shape. That is exactly the extra context annotations cannot carry.

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

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

Three tight sentences: behavior and default first, side-effect warning second, return/idempotency third. No filler; every clause carries operational 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?

No output schema exists, yet the description supplies the return shape { delivered, skipped, failed }, the error behavior (CONFLICT), and the required human-confirmation step. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and the schema already documents action's default, bodyOverride's role, and messageId's source. The description largely restates these ('action=release, the default', 'bodyOverride replaces its text before sending') without adding syntax or constraint detail, so the baseline 3 applies.

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

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

States a specific verb pair (release/discard), the exact resource (one held reporter message from list_reporter_outbox), and names the sibling that produces the input. An agent can distinguish this from list_reporter_outbox (read) and reply_to_reporter (compose new) without opening any schema.

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

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

Tells the agent where the input comes from (list_reporter_outbox), that action defaults to release, and adds a hard prerequisite ('confirm with the user first' for a real end-user message). It doesn't explicitly contrast with reply_to_reporter as an alternative for non-held messages, but the context is otherwise unambiguous.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds that it removes 'including its Vault secret', providing context on what gets destroyed beyond the annotation. It also states 'Permanently remove', reinforcing the irreversibility. This adds value beyond annotations without contradicting them.

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

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

One concise sentence with high information density. It front-loads the destructive and idempotent nature, and the scope. No wasted words.

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

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

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

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

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

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

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

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

The description states a specific verb ('remove'), a precise resource ('pooled BYOK credential by key id'), and the scope ('from the authenticated project'). It clearly distinguishes from siblings like add_byok_key and test_byok_key by naming the operation and the destructive nature.

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

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

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

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

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

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

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

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

Two sentences with zero redundancy: the first states action and return, the second covers idempotency and usage guidance. Every sentence earns its place.

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

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

With an output schema present and annotations covering safety/idempotency, the description supplies the trigger, the alternative, the affected states, the return, and the idempotency behavior. Nothing an agent needs for correct invocation is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description confirms reportId as UUID and note as operator note, but adds no format or constraint details beyond the schema. The 'previously fixed/verified/dismissed' context implicitly constrains the report state, but that is resource-level context, not parameter-level.

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

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

States a specific action and resource: 'Move a previously fixed/verified/dismissed report back to the reopened state for regression review.' Explicitly names the sibling tool 'transition_status' for any other state change, making differentiation immediate.

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

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

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

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