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

Annotations mark this as non-read-only and non-idempotent but non-destructive; the description explains why by disclosing the write side effects: first-run live-scan persistence to artifact_path (surfaced as persisted_map_path) and write_overlay emitting .sumo-qa/diff-impact.json. It also covers staleness detection, merge-base diffing semantics, ignored cross-root artifacts, and probable_mapping_gap as a false-negative 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?

Front-loads the purpose, then a compact routing-phrase list, then parameter behavior in reading order. The length is earned: each clause either aids selection or supplies semantics the 0%-coverage schema omits.

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 enumerates the report contents (likely tests, risk surface, one-hop nodes, unmapped files, staleness flag, probable_mapping_gap, persisted_map_path), which is exactly what an agent needs to interpret the return. Nothing material is missing for a 5-param analysis tool.

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

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

Schema coverage is 0%, so the description carries the full burden and does so for all five params: root (the repository), changed_files (repo-relative paths), base_ref (any git ref, diffed against merge-base with HEAD so post-divergence base changes don't leak), artifact_path (read source with live-scan fallback and first-run persistence), and write_overlay (writes the overlay file under root).

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: maps changed files onto the repo-map and reports likely exercising tests, unmapped risk surface, one-hop affected nodes, and map staleness. This is clearly distinguishable from siblings like sumo_qa_query_repo_map (read the map) and sumo_qa_scan_repo (build it).

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

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

Provides concrete natural-language phrasings that should route to this tool ('which tests cover my changes', 'what should I re-test'), and explains the changed_files-vs-base_ref choice plus the artifact_path fallback. An agent knows both when to pick this and how to drive 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?

No annotations provided, so the description carries full behavioral burden. It discloses that answers cite a principle or technique from the loaded catalogue rather than producing generic advice, which is useful. However, it doesn't specify what happens if the catalogue is empty, how the citation is surfaced, or any output format 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?

Concise, two-sentence description. Front-loaded with usage condition and purpose. Slightly dense with the routing precondition and example questions, but 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?

For a zero-parameter tool with no output schema, the description covers purpose and usage well. But it doesn't explain what the user should expect as output (e.g., a cited principle/technique response) beyond the behavioral note, and no output schema exists to fill that gap.

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

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

Parameter count is 0, so baseline 4 applies. No parameter-related gaps to address.

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: answering generic testing questions. Differentiates from siblings by noting it's for questions that don't fit more specific QA skills. Not a tautology, but the scope (generic testing Q&A) is somewhat broad.

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: after sumo-qa-deciding-approach routes here, and when the user asks a generic testing question that doesn't fit a more specific skill. Names the routing precondition and the exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the exact shape of the response (workflows with prompts, skill routing, outcomes; active profile; how to enable omitted groups), which is necessary 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?

Front-loaded with the core action, then the payload contents, then the routing caveat. Dense but every clause carries information; the em-dash list is a bit long but not padded.

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

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

For a zero-parameter, no-output-schema discovery tool, the description covers what is returned, what it is for, and what it does not replace. Nothing an agent needs in order to decide to call it is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the absence of inputs, which the empty schema already communicates.

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 a compact, read-only map of sumo-qa's core QA workflows') and enumerates the payload (sample prompt, routed skill, one-line outcome, active tool profile, enabled capability groups). It explicitly distinguishes itself from siblings by naming using-sumo-qa and sumo_qa_deciding_approach as things it does not replace.

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 clear positive use condition ('A discovery aid for "what can sumo-qa do?"') and negative guidance naming two sibling tools it does not substitute. Lacks an explicit rule for when to prefer this over the entry router versus when to start there, but the routing intent 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 only give the generic read/write/idempotency flags; the description adds the critical behavioral facts an agent needs: the confirmation gate is the host's responsibility and not enforceable via a parameter, sensitive input (diff hunks, secrets, PR bodies) is rejected and never echoed, and memory-derived probes are advisory only. This is rich context beyond the 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?

It is well front-loaded (purpose, then action list, then caveats) and every section is substantive, but the ALL-CAPS emphasis and the trailing natural-language-phrasing block make it longer than strictly necessary for an agent reader.

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 four-parameter, no-output-schema mutation tool of this complexity, the description covers operations, defaults, storage locations, error behavior, and the advisory/confirmation model. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it defines the action enum values, the required fields of `entry` (scope, trigger_signal, recommended_probe, source_note, optional last_reviewed with ISO-8601 default), the role of `entry_id`, and the scope default plus the error behavior for an unrecognised scope.

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

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

The description states a specific verb+resource ('manage an explicit, user-confirmed review-feedback memory of recurring QA findings') and immediately distinguishes it from automatic learning, risk-ledger, AC tools, and the sumo-qa-feedback CLI. An agent can identify the tool's scope without reading any sibling 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?

It enumerates all four operations with their required arguments, states the default action ('list') and scope ('project' vs 'global'), and even maps natural-language user phrasings to the tool. Exclusions are explicit (never persist without confirmation, never auto-capture).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing return behavior: it yields the first matching path, or a negative-case object {"installed": false, "skill", "scope"} when absent — valuable 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?

Two compact sentences, front-loaded with the verb and resource, then the return contract. The inline JSON fragment is slightly awkward but nothing is wasted.

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

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

For a low-complexity read tool with no output schema, the description covers the core return shape adequately. Gaps remain around the 'auto' scope default, project-vs-global precedence, and whether path results are absolute — details an agent would want before relying on 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 0%, so the description must carry the load. It partially does: 'skill' is shown to mean a SKILL.md skill name, and 'scope' is implied to cover project vs global locations. However, the default value 'auto' and the precedence rule when both project and global matches exist are never explained.

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: locating an installed external SKILL.md file, scoped to Codex/Claude/agents paths. It is clearly distinct from siblings like sumo_qa_install_external_skill and sumo_qa_preview_external_skill in intent, though it never names those siblings explicitly to sharpen the distinction.

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 purpose implies a pre-check before install/execute, but there is no explicit when-to-use or when-not-to-use statement, and no pointer to the obvious alternative (install_external_skill or search_external_skills). Usage is inferable from the name and description rather than stated.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose key traits: one closed loop per gap, evidence must be red-then-green, and it pauses when repo context or evidence is insufficient. It stops short of stating side effects (does it write test files? mutate the repo? need permissions?) or what a completed loop returns, which matters for a tool that clearly produces artifacts.

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 triggering condition before the mechanics, and the three sentences each carry distinct information (when, what, and when to stop). The example list in the first sentence is slightly heavy but serves to disambiguate trigger intent, so it largely 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 zero-param, no-annotation, no-output-schema tool, the description covers the invocation context and the loop semantics well. It is not fully complete because an agent still cannot tell what artifacts the loop produces or where evidence is recorded, though that may be outside the description's scope.

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 takes zero parameters, so the schema baseline of 4 applies. There is nothing for the description to disambiguate, and it correctly spends no words on inputs, instead describing gap selection implicitly through the preconditions.

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: it drives ONE closed loop per named uncovered behavior gap, producing red and green evidence. That scope ('one loop per gap') is distinctive enough to separate it from siblings like sumo_qa_strengthening_tests or sumo_qa_implementing_with_tdd, which are not framed around a single already-named gap.

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

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

Explicitly names the upstream routing tool (sumo_qa_deciding_approach) and the precondition that a review, mutation run, or graded scenario has already named a concrete gap. It supplies concrete trigger utterances ('close this gap', 'fix this surviving mutant end to end') and a stop condition, leaving little 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?

No annotations are supplied, so the description carries the full burden. It discloses the tool's relative weight and the shape of its output (formal plan, criteria, phases), which is useful, but it says nothing about permissions, whether it mutates state, or what the caller receives back.

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 waste: the routing precondition comes first, then the heaviness/alternative contrast. Every clause earns its place.

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

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

With zero params, no output schema, and no annotations, the description covers the decision-relevant information an agent needs to route correctly. The only shortfall is that it leaves the returned artifact's form implicit rather than stated.

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 takes zero parameters, so schema coverage is a non-issue and the baseline of 4 applies. The description does not introduce parameter-like inputs that would need documenting.

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 concrete deliverable (a formal test plan with entry/exit criteria and a phased QA approach) rather than restating the name. It explicitly differentiates itself from the sibling sumo_qa_preparing_for_work by being 'heavier,' so an agent can choose between 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?

Gives explicit preconditions ('use after sumo-qa-deciding-approach routes here'), trigger conditions ('formal test plan, entry/exit criteria, phased QA approach'), and a when-not/alternative ('heavier than sumo-qa-preparing-for-work; use when the work is tracked or formally reviewed'). Nothing is left to inference.

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

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

With no annotations, the description carries the full disclosure burden, and it does well: it reveals the two catalogues loaded, that a reasoning step happens, that control is handed to a sub-skill, and that further catalogues are loaded on demand. It does not say what is returned to the agent or how the routing decision is surfaced, 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?

A single sentence, front-loaded with the usage directive before the mechanics, and no sentence is filler. The parenthetical asides ('the two needed to route', 'which loads any further catalogues on demand') add density that makes the sentence slightly hard to parse on first read.

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

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

For a zero-parameter router with no annotations and no output schema, the description covers the essential contract: when to call it, what it loads, what it decides, and where it delegates. What the call yields to the agent is left implicit, which keeps it just under fully complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It implicitly tells the agent that the input is the conversational/intent context rather than arguments.

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 action chain: load classifications + approaches, reason over intent, pick the canonical approach, and route to the matching sub-skill. This distinguishes it from the plain loaders (sumo_qa_load_classifications / sumo_qa_load_approaches) and from the individual QA sub-skills. It falls short of 5 only because terms like 'canonical approach' and 'sub-skill' are internal jargon not defined here.

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 first after using-sumo-qa on any QA intent' gives an explicit sequencing rule relative to a named sibling, which is exactly the routing guidance an agent needs. It stops short of 5 because it offers no when-not-to-use condition and never states whether it should be re-invoked if intent changes mid-session.

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 (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavior: it blocks on commit/digest mismatch and safety-lint failure, and it declares the returned body untrusted so it cannot override higher-priority instructions. That is meaningful context beyond the structured fields, though the failure/error surface and handoff format are not detailed.

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, front-loaded with the core action, followed by blocking conditions and the trust boundary. No filler, though the middle sentence compresses several conditions into one line without much elaboration.

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

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

For a tool with no output schema and three parameters, the description covers the trust/blocking behavior well but leaves gaps: what the 'execution handoff' actually contains, and the meaning of 'scope' and 'intent'. An agent can invoke it, but cannot predict the return shape or the parameter semantics.

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 0% for three parameters, so the description carries the full burden of explaining parameters and does not. Only 'skill' is loosely implied by 'SKILL.md'; 'scope' (with its 'auto' default) and 'intent' are entirely undocumented in both schema and description.

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 ('Load an installed external SKILL.md') plus the outcome ('return the execution handoff'), which clearly separates it from install/preview siblings in spirit. It does not explicitly name sumo_qa_preview_external_skill or sumo_qa_load_skill_context as the contrasting alternatives, so sibling differentiation is implied 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?

Usage is implied by 'Load an installed external SKILL.md and return the execution handoff' – the agent can infer it fetches a skill body for execution. However, there is no explicit 'use this instead of preview when...' guidance, and the surrounding family (preview, install, rollback, load_skill_context) makes an alternative-selection statement desirable.

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 no annotations, the description carries full burden. It discloses that tasks run in fresh subagents (parallel where independent), with two-stage review and no per-task check-ins. Adds useful context beyond typical annotations, but lacks details on failure handling or side effects.

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

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

Three sentences: first sets purpose and predecessor, second explains execution mechanism, third notes continuous execution and successor. No fluff, front-loaded with key 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?

For a zero-parameter, no-output-schema tool, the description covers workflow position, execution model, and successor. However, it lacks error handling behavior (e.g., what happens if a subagent or review fails), which would improve completeness.

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

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

Input schema has zero properties, so no parameter information needed. The description naturally omits parameter details, and the baseline for zero parameters is 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 it dispatches a QA plan task-by-task after planning, runs subagents with parallel execution and two-stage review, and finishes by routing to a finishing tool. It distinguishes itself from siblings by specifying its position in the workflow (after planning, before finishing).

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 after sumo-qa-planning-qa-rollout' and mentions routing to sumo-qa-finishing-qa-work, giving clear when-to-use context. It does not provide exclusions or alternatives for when not to use, but the sequential workflow implies usage only in that 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 (readOnly, idempotent, non-destructive, closed-world) already cover the safety profile, so the bar is lower. The description adds genuine context beyond them: the specific outputs produced (entity characteristics, preconditions, downstream dependencies, edge cases, and 'what NOT to use' guidance) and the domain-neutral scope. It does not mention rate limits or pagination, but for a read-only explainer that is minor.

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

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

Purpose, return contents, and routing phrasings are front-loaded in three tight paragraphs. The phrasing list is slightly long but earns its place by mapping user intent to the tool, so little is wasted.

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

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

With no output schema, the description correctly explains what comes back (characteristics, preconditions, dependencies, edge cases, exclusions) and the domain-neutral stance. Complete enough to call correctly; only the required `question` parameter's expectations are left implicit.

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

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

With 0% schema description coverage, the description must carry parameter meaning, and it partially does: it notes that `environment` (with the example 'integration') and `domain` are optional and folded into the analysis. The required `question` parameter is never characterized (format, length, expected phrasing), leaving a documented-parameter gap.

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

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

The description opens with a specific verb+resource: explaining what test data shape and characteristics a scenario needs. This distinguishes it from data-locating siblings like sumo_qa_find_test_data or sumo_qa_validate_test_data, though it never names those siblings explicitly to sharpen the boundary.

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

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

It provides a strong intent-mapping list of natural-language phrasings ('what data do I need to test X', 'what's the minimum data setup') that tell an agent when to route here. It stops short of an explicit exclusion (e.g. 'use find_test_data to locate concrete records, not this'), so it lacks the when-not clause.

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 give readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false; the description adds far more — default no side effects, the explicit write carve-out, confinement to <cwd>/.sumo-qa/exports, refusal of absolute/.. traversal paths, refusal to overwrite existing targets, and validation-before-write ordering. This is exactly the behavioral context an agent needs for a conditional-write tool.

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

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

Front-loaded with the core purpose then structured by parameter; each block maps to a caller decision. It is verbose and heavy with emphasis markers, and the 'import mappings may need local adjustment' line is somewhat tangential, but overall the length is justified by the complexity.

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

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

For a 4-parameter export tool with no output schema and no schema descriptions, the description covers purpose, format semantics, error behavior, write-path safety, and return fields (content, format, schema_version, test_case_count, written_path). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the full burden and it does: it documents format (markdown/json/csv with default and CSV's flat-outline restriction), the per-case dict fields (id, title, preconditions, steps, expected_result, linked_risk_id, priority, evidence_status with enumerated values), export_title's naming rationale, and output_path's resolution rules.

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 (EXPORT) and resource (QA test cases) plus the exact transformation: deterministic rendering of already-structured cases into a machine-readable shape. It explicitly bounds scope by stating the host LLM identifies the cases and the tool 'never infers them and never inspects a repo', so an agent knows precisely what this is and is not.

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

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

Gives clear when-to-use context: side-effect-free by default, file writes only when output_path is supplied, and CSV only valid for flat outlines. It does not name a sibling alternative or an explicit 'use X instead when...' route, but the guidance on format selection and the write carve-out is concrete.

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?

No annotations are provided, so the description carries the full disclosure burden. It does reveal the essential behavior — this tool delegates to one of four test-data tools rather than performing the work itself — which is the most important trait for an agent. However, it does not say what the caller receives back, whether the sub-tool's result is returned verbatim, or how the routing decision is actually resolved, leaving real behavioral gaps for a no-annotation tool.

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

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

Two sentences, front-loaded with the precondition and trigger before the routing target list; each clause earns its place by naming either a trigger or a destination tool. Minor density cost from the em-dash intent list, but nothing is redundant or padded.

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

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

For a zero-parameter router with no annotations and no output schema, the description covers the trigger and the routing targets, which is most of what an agent needs. It omits the post-routing contract (what the caller sees after dispatch) and does not explicitly tell the agent to prefer this entry point over invoking the leaf test-data tools directly, which is a meaningful ambiguity given how many overlapping siblings exist.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies: no parameter semantics are needed because no inputs exist.

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 function — dispatching test-data requests — and names the four downstream tools it routes between (explain, find, validate, register), which map onto identifiable siblings such as sumo_qa_find_test_data and sumo_qa_validate_test_data. It is clear this is a routing/entry-point tool rather than a leaf action, though the phrasing 'finding test data' in the name is slightly narrower than the routing role described.

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 precondition ('Use after sumo-qa-deciding-approach routes here') plus a concrete trigger taxonomy: what data to test X, find a known-good record, validate an entry, register new known-good data. This maps intents to the four target tools, so an agent can tell when to invoke it. It stops short of stating when NOT to use it (e.g. calling the leaf tools directly), so it is not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: local-YAML-only scope, no external lookups, ranked results with confidence/freshness/suitability reasons, and full pagination semantics (offset, total_count, has_more, next_offset).

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 returns, pagination, and routing examples; every block serves a function. The natural-language phrasing list is somewhat long but is directly useful for tool selection.

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 usefully describes return fields and pagination, which closes a major gap. It remains incomplete for a 0-required, 8-parameter tool because half the filter parameters go unexplained, leaving selection and invocation partly guesswork.

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 only 25% across 8 parameters, so the description must compensate. It explains offset/pagination and repeats the narrowing role of scenario_tags and known_valid_for, but sku, domain, product_id, environment, and limit are never mentioned in either place — an agent cannot infer how those filters behave.

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

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

States a specific verb and resource ("Search the local known-good test data catalogue") plus its scope boundary ("Reads the local YAML catalogue under `knowledge/test_data/` only; no external lookups"), which separates it from catalogue-loading and external-skill siblings. An agent can tell what this does 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?

Provides explicit trigger phrasings ("find me test data for X", "do we have a known-good record for X") that give strong context for routing. It does not, however, name when not to use it or explicitly contrast it with near-siblings such as sumo_qa_finding_test_data or sumo_qa_validate_test_data.

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 no annotations provided, the description carries the full burden and details the tool's actions: runs the suite, captures coverage/risk-to-test map/open follow-ups, writes a markdown summary, and offers to draft a PR description. While it doesn't cover every possible side effect, it provides substantial transparency for an agent.

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

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

The description is concise yet packed with essential information. It front-loads the usage context and clearly lists all key actions without unnecessary words 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?

The description fully explains what the tool does and what it produces (markdown summary and PR draft), which is complete given there is no output schema. It leaves no ambiguity about the tool's role in the QA workflow.

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

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

The tool has zero parameters, so the description does not need to explain parameters. The baseline for 0 params is 4, and the description adds value by detailing the tool's outputs and workflow beyond the schema.

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

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

The description clearly states the tool's purpose: to finish a QA rollout by capturing evidence, producing a PR-ready summary, and closing the loop. It explicitly mentions preceding actions and distinguishes itself from sibling tools by specifying when it should be used.

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: 'at the end of a QA rollout (after sumo-qa-executing-qa-rollout, or after a manual multi-step QA task)'. This provides clear context, though it does not explicitly mention when not to use or list alternatives.

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

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

Annotations already establish read-only/idempotent/non-open-world, and the description adds substantive behavior beyond them: partial/empty bundles are first-class, freshness values are enumerated, stale/unknown/absent facts are rendered with an explicit 'do not claim safety' warning, and a bundle-vs-local-state SHA divergence is called out rather than silently trusted.

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 with a bolded scope boundary, and the field-level detail is dense but each clause informs invocation. The NL-phrasing list and the issue-number parenthetical add mild retrieval value rather than essential content, keeping it just short of maximal conciseness.

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

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

For a 3-param formatter with no output schema and a nested, untyped bundle object, the description supplies enough to call it correctly and understand the rendered artifact. It could more fully describe the emitted brief's structure, but the freshness/conflict warnings and fallback behavior cover the agent's decision needs.

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 0% schema description coverage, the description carries the full burden and does so thoroughly: it names every bundle key (issue_summary, pr_summary, head_sha, changed_files with {path, change_kind}, test_evidence/ci_status with {result, freshness, source}, user_constraints), defines the freshness enum, and explains local_head_sha's conflict-detection role and max_files' bounding role.

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 (validate and render) and a precise resource (host-neutral issue/PR context bundle as a compact markdown brief for QA review/planning). The explicit boundary 'FILE/FORMAT PLUMBING ONLY — never inspects a repo, makes a network call, or assumes GitHub' cleanly separates it from siblings like sumo_qa_scan_repo and sumo_qa_analyze_diff_impact.

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 concrete natural-language triggers ('build the review context bundle', 'format this PR/issue context for review') and a clear condition for use, plus the fallback behavior when a partial/empty bundle is supplied. It doesn't name a specific sibling alternative explicitly, but the negative scope ('the host gathers the facts') effectively routes the agent away from inspection tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral detail the annotations cannot: readiness is structurally refused when a risk is uncovered or evidence stale; absent coverage/mutation signals are reported 'not measured' and never assumed passing; a missing local_head_sha with a named bundle head_sha makes the bundle UNVERIFIABLE (a distinct reason from 'stale').

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 and the 'not a predictive score' caveat, then uses tight bulleted parameter notes. It is longer than typical but nearly every sentence carries non-redundant information; the NL-phrasing list is useful routing signal rather than filler.

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

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

Despite no output schema, the description enumerates the return surface: four-state verdict, is_ready, uncovered-blocker/residual counts, stale and not-measured lists, rendered markdown, compact_summary, and serialized snapshot for the downstream report. For a complex aggregate tool this is complete enough to call 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?

With 0% schema description coverage across 7 params, the description must carry the load and largely does: it explains ledger_rows, context_bundle, coverage/mutation, scope, and local_head_sha semantics including derived effects (staleness flagging, unverifiable vs stale distinction). Only max_reasons is left undocumented, a minor gap.

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

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

Opens with a specific verb+resource: 'Compose a QA READINESS SCORECARD from already-produced evidence and DERIVE a readiness recommendation.' It also explicitly contrasts itself with a predictive quality score and ties itself to the sibling formatter tools (sumo_qa_format_risk_ledger, sumo_qa_format_context_bundle) whose shapes it reuses, so an agent can place it precisely among siblings.

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

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

Provides concrete trigger phrasings ('is this ready to merge/release', 'give me a readiness scorecard') and states the tool is an evidence summary that never asserts 'ready'. It differentiates from the upstream formatters by naming them as input producers, but does not explicitly state when NOT to reach for this versus e.g. sumo_qa_generate_qa_report (#157 is only mentioned as a downstream consumer).

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 (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real context: it discloses what each row must contain, the enumerated evidence_status/residual values, that it never infers risks itself, that output is token-bounded by max_rows, and what the uncovered-blocker count signals. It does not detail error or validation-failure 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-loaded with the core purpose, then the boundary, then field semantics, then return values. The row-field enumeration is dense but justified given 0% schema coverage. Every sentence carries weight, though the full list could be trimmed slightly.

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 fully specifies the return payload (markdown table, one-line summary, row count, uncovered-blocker count). Combined with the row-field documentation and the read-only annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well. It documents the structure of every row field (risk_id, risk, source_anchor, test, evidence_status, residual, repo_map_node_id), supplies the enum values for two of them, and explains that max_rows bounds output to the host token budget.

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

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

States a specific verb pair and resource ('Validate and render a risk-to-test traceability ledger as a markdown appendix') and immediately scopes the boundary with 'FILE/FORMAT PLUMBING ONLY'. An agent can distinguish this from sibling formatters like sumo_qa_format_qa_scorecard or sumo_qa_format_context_bundle.

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 clearly delineates responsibility ('the host LLM identifies the risks; this tool never infers them') and notes its role in the review workflow's safe-to-merge gate. It does not, however, name a specific alternative tool or state when to prefer it over sibling formatting tools, so it falls short of the explicit when/when-not bar.

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

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

Despite annotations only declaring readOnly/destructive/idempotent flags, the description adds substantial behavioral detail: the HTML body never returns to the host, write_to controls persistence (relative paths land under the repo), absence of write_to writes nothing, and inline overrides are validated before any write. This goes 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?

Content is front-loaded with the core action, then behavior, then parameters. The list of natural-language phrasings is useful but slightly padded, and the prose is a bit verbose overall, though nothing is truly wasted.

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

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

With no output schema, the description sensibly reports the return (a compact readiness summary) and enumerates the possible verdicts (ready / ready_with_accepted_residuals / blocked / insufficient_evidence). It is nearly complete, though it does not describe the summary's structure beyond the verdict.

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 0%, so the description must compensate, and it does: root is the repo to report on, write_to is optional with documented relative-path behavior, and risk_ledger_rows/context_bundle are inline overrides that take precedence over on-disk files and are validated first. It also clarifies that the two override params share the shape of the corresponding format_* tools.

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

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

The description states a specific verb+resource: compose persisted .sumo-qa artifacts into a local QA report and return a readiness summary. It clearly names the consumed artifacts (repo map, diff impact, risk ledger, context bundle), which distinguishes it from the formatting siblings. It does not explicitly contrast itself with sumo_qa_format_qa_scorecard, so sibling differentiation is only partial.

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

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

It provides concrete natural-language phrasings that map to the tool and explains the chat-flow case where inline overrides are needed instead of on-disk files. However, it never states when NOT to use it or names an alternative tool for producing an HTML report without persisting, leaving some selection 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?

No annotations exist, so description carries burden. It outlines the multi-step process with confirmation gates, and discloses critical behavioral constraint (defer writing until agreement). However, lacks details on failure modes or state changes.

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 wasted words. Front-loads sibling dependency. Could be structured with bullets for clarity, but current form 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?

Given zero parameters and no output schema, description covers usage and process adequately. Lacks mention of return values or next steps, but tool likely yields conversation prompts. Adequate but could be more thorough.

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

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

No parameters in schema, so baseline is 4. Description adds no parameter info (unneeded) but provides process context that adds value beyond schema.

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

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

The description clearly states this tool implements TDD after a decision from 'sumo-qa-deciding-approach', with a specific process (plan → risk → test idea → confirm → red → hand off → green → review). It distinguishes itself from siblings by specifying it's used only after a TDD approach is chosen.

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 after sumo-qa-deciding-approach picks...', provides example prompts, and warns 'Don't write the test until the test idea has been agreed.' This gives clear context for when and how to use the 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 declare the operation is a non-idempotent write (readOnlyHint=false, idempotentHint=false), and the description materially adds to that: it explains normalization, writes into a user-writable pack, discloses loader precedence (env var > project > global > bundled > repo root), and describes the unsupported_source failure mode. These are non-obvious behaviors beyond what 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?

It is front-loaded with the core action and well-organized into purpose, scope, precedence, and routing sections. It runs long and the example-phrasing list is slightly verbose, but nearly every sentence adds operational value for a mutating ingest tool.

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 3-parameter, no-output-schema mutation tool, the description covers purpose, accepted inputs, scope semantics, precedence, failure handling, and caller phrasing. There is no meaningful gap an agent would need to fill before invoking 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 0%, so the description carries the full burden and does so well. It explains scope's two values with concrete destinations ('project' → <cwd>/.sumo-qa, 'global' → user data dir), describes source as a path to a native file or directory, and maps content_type to the re-ingestion path for converted external sources.

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 precise verb and resource: 'Adds or replaces team QA knowledge/standards/rules from a local native file.' It goes further by enumerating exactly which file types are accepted (principles.md, standards-pack *.yaml, change_rules.yaml), which distinguishes it decisively from the read-oriented siblings like sumo_qa_load_principles and sumo_qa_load_standards.

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 with example phrasings ('add this to the knowledge base', 'replace our principles'), and it names an exclusion: PDF/PPTX/URL are not parsed here and must route through sumo_qa_suggesting_external_skill. It also flags the scope decision as a user choice worth confirming, which is actionable routing advice.

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 this as a non-readOnly, non-idempotent, open-world write. The description goes beyond them by disclosing the destructive-action gate: sumo-qa performs MCP elicitation with the user before writing and refuses hosts that cannot ask, plus the digest must still match the preview. This is meaningful safety context not present in 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 one-line purpose followed by a tight parameter glossary; every clause carries meaning. It is compact and well-organized, with only minor density in the elicitation 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?

For a 7-parameter, non-idempotent write with no output schema, the description covers the approval gate and digest contract well but is silent on what installation actually writes, how scope/agent/source affect the outcome, and any reversibility (the rollback sibling is not referenced). Adequate but with clear gaps.

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

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

Schema description coverage is 0% across 7 parameters, so the description must compensate. It explains confirmed, approved_digest, and elevated_trust clearly with semantics (e.g., approved_digest must equal the preview's content_digest), but leaves agent, scope, skill, and source undocumented beyond their names and defaults.

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 (Install) and resource (external skill) plus the mechanism (pinned Skills CLI), and the qualifier 'previewed' implies the preview workflow. It stops short of naming sumo_qa_preview_external_skill explicitly, so sibling differentiation is by implication rather than by name.

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 word 'previewed' and the digest-matching requirement imply that sumo_qa_preview_external_skill must run first, and the elevated_trust clause gives a clear when-to-set condition. However, no alternative tool is named and there is no explicit when-not-to-use guidance, so the routing 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds important behavioral details: local-only, no network/extraction/caching, deterministic, and error handling for unrecognised detail values.

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

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

The description is well-structured and front-loaded, but slightly verbose with repeated mentions of skill index arrays. However, every sentence adds value and the organization is logical.

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?

Without an output schema, the description fully describes the return format for both detail options, explains error handling, and provides context for how this tool fits with others (e.g., sumo_qa_load_skill_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?

Despite 0% schema coverage, the description exhaustively explains the single parameter 'detail' with two options ('compact' and 'full_index'), detailing what each returns, and notes behavior for unrecognised values.

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

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

The description explicitly states it returns deterministic metadata for every bundled skill as a JSON string and clarifies it is a routing/index aid, not skill bodies. This clearly distinguishes its purpose from sibling tools like sumo_qa_load_skill_context.

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

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

The description explains when to use this tool (for routing/index) and provides explicit alternatives: 'Once routing has chosen one skill, fetch that skill's section/module index with sumo_qa_load_skill_context(...)' and mentions that zero-argument skill tools still return full bodies unchanged.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe and idempotent. The description adds value by specifying that output is plain text, which helps set expectations. No contradictions 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?

Two concise sentences with no redundancy. The verb is front-loaded, and every sentence adds value. The description is efficiently structured.

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

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

Given zero parameters, annotations, and no output schema, the description is quite complete. It explains what the tool returns and why it is used. A slight improvement could be to define 'canonical QA approaches' or mention related tools, but it's adequate for a simple retrieval 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 no parameters, and the input schema coverage is 100%. The description does not need to explain parameters, and its focus on the return value is appropriate. It adds meaning beyond the schema by explaining the purpose of the output.

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 that the tool returns canonical QA approaches as plain text. It uses a specific verb ('Return') and identifies the resource ('canonical QA approaches'). While it doesn't explicitly differentiate from siblings like sumo_qa_deciding_approach or other load tools, the purpose is unambiguous.

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

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

The description mentions that the host LLM picks which approach fits a piece of work, implying usage for selecting approaches. However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., sumo_qa_deciding_approach). Usage is implied but not clearly delineated.

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

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

The description adds behavioral details beyond annotations: it is read-only and local-only, never raises errors (returns error envelope), and marks output with canonical flags. This complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is well-structured with bullet points and clear sections, but is slightly verbose. Every sentence adds value, though some redundancy could be trimmed without loss of meaning.

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

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

Given three parameters, no output schema, and many sibling tools, the description is thorough: it covers input combinations, output behavior (canonical flags), error handling, and ties to other loaders. The agent has all needed information to invoke correctly.

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

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

With 0% schema description coverage, the description fully explains each parameter: 'catalogue' must be one of four values, 'name' matches slug or heading text, 'format' has detailed semantics including defaults and canonical marking. This adds essential context missing from the schema.

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

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

The description clearly states it loads a single catalogue entry or whole catalogue as JSON, and distinguishes itself as 'a lighter alternative to the full-text loaders' for four specific prose catalogues. It explicitly names the catalogues and contrasts with sibling zero-argument loaders.

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

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

The description provides explicit when-to-use guidance: use with 'name' for a single entry, omit for whole catalogue; choose 'full' format for safe citation, 'compact' for navigation only. It also notes that the existing zero-argument loaders remain unchanged, helping agents decide between alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns plain text and that the host LLM picks applicable classifications, providing context beyond annotations without contradiction.

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

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

Two sentences front-load the purpose and succinctly cover return type and usage. No redundant information.

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

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

For a simple tool with no parameters and no output schema, the description completely covers purpose, return format, and usage context. No gaps.

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

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

No parameters exist, schema coverage is 100%, so the description adds value by explaining the return format and usage, meeting the baseline for zero-param tools.

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

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

The description clearly states it returns 'canonical change classifications as plain text', with a specific verb and resource. It distinguishes from sibling load_* tools that load other entities like approaches, rules, etc.

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

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

The description implies usage: when the host LLM needs to pick classifications for a change. It doesn't explicitly state when not to use, but the context is clear among siblings.

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, destructiveHint=false, idempotentHint=true. The description adds minimal behavioral context beyond the usage hint ('cites principles') and does not disclose any additional behavioral traits such as output size or performance implications.

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

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

The description is two sentences, front-loaded with the action, and contains no redundant information. Every word 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 zero parameters, no output schema, and a straightforward purpose, the description adequately explains what the tool returns. However, it could be more complete by specifying the format or length of the output, or by contrasting with similar load tools.

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

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

With zero parameters and 100% schema coverage, the baseline is 4. The description does not need to add parameter information, but it does clarify what the output contains, which is sufficient.

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

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

The description clearly states the tool returns ISTQB Foundation, Advanced, and ISO 25010 grounding as plain text, using a specific verb 'Return' and resource. It distinguishes from sibling load tools that handle different content types (approaches, classifications, etc.).

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

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

The description implies the tool is used when citing principles in recommendations, but provides no explicit guidance on when to use this versus alternative load tools (e.g., load_standards) or when not to use it.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns plain text and that 'no keyword inference' occurs, but could mention default behavior when no filter is applied.

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

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

Two sentences, front-loaded with the main purpose, 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?

For a simple read tool with one optional param, the description covers the main behavior and return format. Minor gap: no mention of what happens if no classification is provided.

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

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

Schema has 0% coverage for the classification parameter, but the description adds that it accepts 'single or comma-separated values', which is crucial for correct usage.

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

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

The description clearly states the tool returns 'the team's loaded change rules as plain text' and specifies an optional filter, distinguishing it from sibling tools like sumo_qa_load_classifications.

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 explains when to use the filter but lacks explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, local-only), and the description adds substantial context beyond them: never raises, error-envelope behavior, oversize-pointer fallback, content_hash/estimated_tokens return fields, and hash-based change detection with no hidden session cache. This is exactly the extra behavioral detail that structured fields cannot convey.

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

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

The core purpose is front-loaded and the mode list is bulleted, which aids scanning. However, the `bundle` bullet is a single run-on sentence with deeply nested parentheticals that is hard to parse, and the overall description is denser than it needs to 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 9-parameter read-only tool with no output schema, the description is complete: it explains the modes, the return fields, the hash-dedup mechanism, and the error behavior. An agent has everything needed to invoke it correctly across any mode.

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 0%, so the description must carry the burden, and it does: every mode is defined, and section, module, modules, classification, catalogues, include_body, and known_hash are each given semantics (comma-separated, exact-match, request order, omission behavior). Only `skill_name` is left implicit, which is minor.

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 ('Load just one slice of a skill's context') and immediately differentiates the slices via enumerated modes. It explicitly contrasts itself with the zero-argument skill tool and with `sumo_qa_load_catalogue_entry`, so an agent can place it precisely among its 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?

Each mode is described with its intended use (manifest for routing, section/module for a single slice, bundle for one-call working context), and it names alternatives such as `load_catalogue_entry` and `sumo_qa_load_standards`/`sumo_qa_load_rules`. It stops short of an explicit 'when not to use this tool' statement, but the routing intent is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: the filter is metadata-based (frontmatter) and returns plain text, which is not in annotations.

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

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

Two concise sentences with no fluff. The most important information (what it returns and the filter behavior) is front-loaded.

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

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

The description says 'as plain text' but doesn't specify the exact format or if there are size limits. While readOnlyHint ensures safety, more detail on the output structure would improve completeness.

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 0% schema description coverage, the description fully explains the classification parameter: it accepts comma-separated values, is metadata-based, and does no keyword inference, which is essential for correct usage.

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 specific verb 'Return' and noun 'loaded standards packs as plain text', clearly distinguishing from sibling tools like sumo_qa_load_approaches or sumo_qa_load_classifications which load different content types.

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 explains the optional classification filter and explicitly states 'no keyword inference', setting clear expectations. While it doesn't explicitly contrast with alternatives, the tool name and context make the use case obvious.

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, destructiveHint, idempotentHint. Description adds that output is plain text and describes usage pattern, which is beyond what annotations provide.

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

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

Two concise sentences with no wasted words. Information is front-loaded.

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

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

For a zero-parameter, read-only tool with rich annotations, the description fully covers purpose and 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?

No parameters; baseline 4 as schema coverage is 100% and description doesn't need to add param info.

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

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

Description clearly states it returns the test design technique catalogue as plain text, listing example techniques. This distinguishes it from sibling 'load_' tools like load_approaches or load_classifications.

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 host LLM picks one technique per named risk', giving context for when to use it. However, no explicit when-not-to-use or alternatives mentioned.

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 no annotations the description carries the full burden, and it does disclose the core behavior: it executes the repo's configured tool, accepts any output format, and writes a compact summary into .sumo-qa artifacts. It omits failure behavior, permissions, and idempotency, so it falls short of full transparency but is well above minimal.

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 routing precondition and trigger phrases, then the behavioral summary. Slightly dense with embedded quoted phrases but every clause contributes; 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?

No params, no output schema, and no annotations mean the description must carry the load, and it covers when to invoke, what it runs, and where results land. Failure-mode and permission details are missing, but for a zero-parameter action tool this is largely complete.

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

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

The tool takes zero parameters, so the baseline is 4; the schema has nothing to document and the description introduces no misleading parameter hints. There is simply no parameter surface to enrich.

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: runs the repo's configured coverage/mutation tool, reads its output, and persists a compact summary into .sumo-qa artifacts. This is distinguishable from siblings like record_coverage and record_mutation because it names its own run-read-persist pipeline.

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 after sumo-qa-deciding-approach routes here' and lists concrete trigger phrases ('run coverage', 'run mutation testing', 'record the survivors'). The agent knows both the precondition and the user intents that select 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?

With no annotations, the description carries the disclosure burden, and it does well: it names the concrete artifact produced, including the path pattern docs/qa/plans/YYYY-MM-DD-<feature>.md, and its downstream consumer. It stops short of stating that the call writes a file to the repo or what happens if a plan already exists, but for a 0-param tool this is solid context.

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

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

Two sentences, front-loaded with the usage condition and then the output contract. The parenthetical examples (story, PR, strategy phase) and the path template both earn their place, though the sentence is dense.

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 the description compensates by naming the produced file and its format, which is what an agent needs. Combined with the explicit upstream/downstream routing, an agent has enough to invoke it correctly, though the near-duplicate sibling relationship remains unexplained.

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 takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. All actionable input arrives as conversational context, which the description implies rather than specifies.

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 transformation: turning a chunk of QA work (story, PR, strategy phase) into a written plan of bite-sized, independently-executable tasks. It also names the upstream router (sumo-qa-deciding-approach) and the downstream consumer (sumo-qa-executing-qa-rollout). However, it never distinguishes itself from the very similar sibling sumo_qa_creating_test_plan, which is an obvious confusion risk.

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

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

Explicitly states when to use it (after sumo-qa-deciding-approach routes here) and the precondition that governs use ('before any test code is written'). It also names the follow-on step (subagent dispatch via sumo-qa-executing-qa-rollout), so the agent can place the tool correctly in the workflow.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose one real behavioral trait beyond the name: that this path omits formal entry/exit criteria and is intentionally lighter-weight than the test-plan tool. However, it says nothing about what the tool produces, whether it mutates any QA state, or what the agent should expect back.

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 filler. The routing precondition is front-loaded ahead of the trigger and the sibling comparison, so the most decision-relevant information arrives first.

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, no annotations, and no output schema, the description covers the invocation trigger well but leaves the outcome side blank: an agent does not know what this tool returns or what state it leaves behind. Adequate for a zero-arg workflow step, but not complete.

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

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

The tool takes zero parameters and the schema is trivially complete, so there is nothing for the description to compensate for. Baseline 4 applies; the description neither needs to nor does add parameter detail.

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

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

The description states a concrete activity (plan QA for a story, ticket, or piece of work before coding starts) and names the sibling it must be distinguished from, sumo-qa-creating-test-plan. It is not a clean verb+resource phrasing, but the scope is unambiguous enough that an agent can identify the tool's role in the workflow.

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 entry condition ('Use after sumo-qa-deciding-approach routes here'), an explicit trigger ('when the user asks to plan QA ... before coding starts'), and an explicit contrast with the nearest alternative ('Lighter-weight than sumo-qa-creating-test-plan; no formal entry/exit criteria'). This is exactly the when/when-not/alternative guidance 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=true, openWorldHint=true, destructiveHint=false. The description adds genuinely useful behavioral detail beyond that: the returned fields (resolved commit, content_digest, trust tier) and the fact that critical safety-lint findings block install.

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, front-loaded with the core action and its key limitation, then the return contents, then the usage instruction. Every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden well by enumerating the key fields. The remaining gap is parameter documentation, which is absent given 0% schema coverage.

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

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

Schema description coverage is 0% across three parameters (agent, skill, source), so the schema alone does not explain them and the description must compensate. The description says nothing about what 'skill' or 'source' accepts (e.g. URL format, skill identifier), leaving the agent to infer from defaults.

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 (preview) and resource (external skill install payload) and immediately clarifies the scope with 'installs nothing.' It clearly distinguishes itself from the install sibling conceptually, though it never names sumo_qa_install_external_skill explicitly.

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?

'Show it to the user before they confirm the install' gives a clear trigger for when to call it. It implies the dry-run-before-install workflow but does not name the alternative tool or state when-not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description adds real behavioral context: results are bounded and ranked, never return full artifacts, and the map is loaded from artifact_path with a live-scan fallback while artifacts for a different root are ignored.

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 return shape, then phrasings, then parameters. The examples list is longer than strictly necessary but earns its place by clarifying the NL matching contract; the parameter paragraph is dense but well-organized.

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, and the description compensates by naming the returned metadata fields (id, path, type, tags, match reason). Combined with full parameter coverage and artifact-vs-live-scan behavior, 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?

With 0% schema description coverage, the description carries the full burden and does so: it defines root as the repository, details query matching fields and ranking behavior, explains limit caps matches while total_matches reports the full count, describes types (node types and/or the literal "command"), and the artifact_path fallback 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?

States a specific verb (Search) and resource (the repo-map) plus the artifact classes it covers (components, tests, CI checks, configs, commands), and explicitly contrasts the bounded metadata result with 'never the full artifact'. An agent can distinguish this from sibling scan/analysis 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?

Provides concrete natural-language phrasings that map to the tool, which effectively describes when to reach for it. It does not, however, name a sibling alternative or state an exclusion (e.g. when to use scan_repo or analyze_diff_impact instead), so it stops short of explicit routing.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds substantive context beyond them: validation runs BEFORE any write, coverage is REPORTED and never gated, and the tool infers nothing. It does not address repeat-write behavior or what happens to an existing artifact, which is the one remaining gap for a non-idempotent write.

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 verb and the plumbing disclaimer, and each sentence carries distinct information (routing phrases, dict schema, validation ordering, path rules). It is dense and slightly long, with the all-caps disclaimer verging on redundant emphasis, 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?

For a three-parameter mutation tool with a nested free-form object, no output schema, and zero schema descriptions, the description covers validation semantics, gating behavior, provenance fields, and path safety. Only overwrite/idempotency behavior of an existing artifact is left 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 0%, so the description carries the full burden and does so: it enumerates the coverage dict keys with value domains (line_percent 0-100, freshness fresh/stale/unknown/absent, detail, source_tool, generated_at), explains the omit-for-not-measured case, and documents write_to's default and relative-path confinement to root.

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 and resource: 'Validate a host-collected coverage summary and persist it as the .sumo-qa/coverage.json artifact'. It also explicitly separates itself from the sibling sumo_qa_measuring_coverage by declaring 'the host skill runs the coverage tool ... this tool runs nothing and infers nothing', so an agent can route correctly 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?

Provides concrete natural-language trigger phrasings ('record the coverage result', 'save coverage into the QA report') that make selection straightforward, and rules out the measurement sibling. It stops short of stating explicit when-not conditions or naming alternatives by tool name for the write path.

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 real behavior beyond the annotations: validation fails BEFORE any write, the tool runs nothing and infers nothing, mutation evidence is REPORTED and never gated (so it won't block a report), and a relative write_to is confined to root. The safety/scope claims are substantial context that annotations alone don't convey; no annotation contradiction (readOnly=false matches a persisting write).

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 and the plumbing-only scope are front-loaded, and the mutation-dict and write_to semantics are organized in separate paragraphs. Slightly padded by the issue reference and three example phrasings, but each block carries 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?

For a 3-param nested-object writer with no output schema and no annotation detail on failure modes, the description covers validation ordering, what is persisted, provenance fields, and path resolution. It doesn't describe the returned error/shape on failure, but that is a minor omission given how much else is specified.

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 0%, so the description does the heavy lifting: it enumerates the mutation dict keys with constraints (survivors>=0, killed>=0, freshness enum of fresh/stale/unknown/absent, detail, source_tool, generated_at) and explains write_to's default and path confinement. root is only implied ('under the target repo'), which is the one gap.

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

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

Specific verb+resource: validates a host-collected mutation summary and persists it to .sumo-qa/mutation.json. The 'FILE/FORMAT PLUMBING ONLY — runs nothing and infers nothing' clause sharply distinguishes it from any sibling that would execute mutation testing, so an agent can disambiguate from the record_coverage/report 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 concrete natural-language phrasings that map to the tool ('record the mutation result', 'save the survivors'), giving clear usage context. It clarifies that the host skill runs the mutation tool and the LLM reads output, but does not name a specific sibling alternative or an explicit when-not-to-use condition, keeping it just short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description adds real value by disclosing duplicate detection (environment + domain + product/SKU + scenario overlap) and the exact write target path. It stops short of explaining what happens on an overwrite or what the return looks like.

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 usage phrasings, then the arg shape example. The example is long but earned given 0% schema coverage; a minor tightening of the phrasing list is possible but nothing is wasted.

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

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

For a single-param write tool with no output schema, the description supplies the operation, the dedup logic, the target file, and a full example payload — enough to call it correctly. Return-value behavior is the only real omission.

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 0% and the single param is a free-form nested object, so the description carries the full burden — and it does so with a complete literal dict example plus the explicit warning to pass a dict rather than a YAML string. This is exactly the compensation the low coverage requires.

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: 'Add or update a known-good test data entry in the local YAML catalogue.' It is clearly distinguishable from siblings like sumo_qa_find_test_data or sumo_qa_validate_test_data, and the write-vs-read distinction is 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 a list of natural-language phrasings that map to this tool ('save this as known-good test data', 'promote this record to known-good'), which meaningfully aids routing. It does not, however, name an alternative or state when NOT to use it (e.g., vs. load_catalogue_entry or validate_test_data).

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 no annotations, the description carries the full behavioral burden. It does disclose one genuine guardrail — it "refuses to claim safe-to-merge without fresh verification evidence" — which tells the agent the output is gated. But it omits whether the tool only reads or also mutates, what verification artifacts it requires, and what it returns, leaving significant gaps for a zero-annotation tool.

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 routing precondition front-loaded and no filler. The second sentence is somewhat compressed — the negation phrasing demands a re-read — but nothing is wasted.

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

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

For a zero-parameter workflow step with no output schema, the agent gets when-to-use and one guardrail but not what the review actually examines, what evidence counts as "fresh", or what the result looks like. Adequate to invoke, incomplete to anticipate.

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 takes no parameters, so schema coverage is moot and the baseline for zero-param tools applies. There is nothing for the description to disambiguate at the argument 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?

The trigger phrases ("review my changes", "is this safe to merge", "what could break") plus the name make the resource and intent identifiable as a pre-merge change review. However, the description never states the action explicitly (e.g. "reviews the diff and assesses merge risk"); the agent must infer it from quoted user utterances. It does distinguish itself from siblings by being the routed destination of sumo_qa_deciding_approach.

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

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

It states an explicit precondition ("Use after sumo-qa-deciding-approach routes here") and gives concrete user-intent triggers that select this tool over the ~45 siblings. Nothing about when to reach for 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?

Annotations already declare destructive=true, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds real value beyond that: user confirmation is mandatory, a shared skill is refused, and a host that cannot perform MCP elicitation is refused. It stops short of describing the resulting state or partial-failure 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-loaded with the action and precondition, then per-parameter notes in a compact two-paragraph form. Every sentence carries information, though the backtick fragments read like schema notes rather than prose flow.

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 destructive, non-idempotent tool with no output schema and 0% schema coverage, it covers the key behavioral questions: confirmation requirement, elicitation fallback refusal, and the shared-skill refusal. Two parameters (`scope`, `confirmed`) and the post-rollback state remain undocumented, so it is not fully complete.

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

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

Schema description coverage is 0% for 5 parameters, so the description must carry the load. It explains `agent` (the single recorded agent; shared skills refused) and `elevated_trust` (unlisted-source restoration), and implies the confirmation precondition, but leaves `scope`, `skill`, and the `confirmed` flag itself unexplained.

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 (restore/rollback) and resource (an external skill sumo-qa installed), and covers both branches of behavior: restoring the previous approved version or removing a first install. An agent can distinguish it from sumo_qa_install_external_skill 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 requires user confirmation before acting and states the condition for elevated_trust (only when the user grants it for an unlisted source). It doesn't name a sibling alternative or spell out when-not to use it, 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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description reconciles the surprising readOnly=false by disclosing the optional on-disk write via write_to. It also discloses determinism guarantees ('deterministic on the same repo state except for project.generated_at'). It does not address whether write_to overwrites an existing file, which is the main remaining behavioral 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-loaded with the core purpose and return shape, then usage phrasings, then parameter notes, so an agent gets the essentials first. It is somewhat long due to the five-item phrasing list, but each sentence earns its place and nothing is padded.

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 obligation to describe returns and does so concretely (counts by kind/type/confidence), plus the optional artifact path and its determinism caveat. Remaining gaps are minor: no mention of error conditions, repo size limits, or confidentiality of the written artifact.

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 0%, so the description carries the full burden and largely meets it: root is described as absolute or relative to the server's working directory, generator_version defaults to the installed version, and write_to is optional and writes the full artifact to a JSON path. It adds real meaning the bare schema lacks, though it omits any format expectations for generator_version.

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 first sentence states a specific verb and resource ('Walk a repository and return a compact summary of its QA-relevant shape') and enumerates exactly what is returned: node counts, likely_tests edges by confidence, command counts by kind, warning counts by kind. That is far more specific than a name restatement, though it never names a sibling such as sumo_qa_query_repo_map to disambiguate scanning from querying.

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 'Common natural-language phrasings that map to this tool' block gives concrete invocation contexts ('map this repo', 'generate the repo-map artifact for X'), which is clear when-to-use guidance. It stops short of 5 because it names no exclusions or alternatives (e.g., when to query an existing map instead of rescanning).

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 real context beyond the annotations: it pins one exact Skills CLI version, returns ANSI-stripped verbatim output, and includes a hint field for reading it. It also explains the deliberate choice not to parse structured output so format drift doesn't break the flow. Annotations already cover readOnly/openWorld, so this is valuable additional disclosure about the return shape and version discipline.

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 action and resource, followed by two short supporting paragraphs that each carry distinct information (version pinning, output shape). No filler, though the final sentence about format drift is slightly editorializing.

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 the description appropriately describes what comes back (identity, verbatim CLI output, hint). It covers the critical behavioral facts an agent needs to call and interpret this tool. The main gap is lack of explicit routing versus the install/execute/check siblings.

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 0% and the single 'query' parameter has no description anywhere. The description implies it's a search query over the registry but adds no syntax, matching behavior, or scope details. Baseline for one param is limited; addition here is modest.

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 (Search) and resource (Skills CLI registry for external agent skills). Sibling tools exist for checking installation and executing skills, but the description doesn't explicitly name them or distinguish this search step from those. Still, the resource is unambiguous enough for an agent to identify the discovery step.

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

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

Usage is implied by the 'search the registry' framing and the mention that raw output is meant to be interpreted by the host LLM. However, there is no explicit when-to-use vs the siblings (check_external_skill_installed, install_external_skill, execute_external_skill, suggesting_external_skill). The workflow position is inferable but not stated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about what the tool produces, what evidence it selects or returns, whether it mutates state, or what the caller should do next — for a tool with zero structured behavioral coverage this is a substantial 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?

A single front-loaded sentence with no padding; the precondition precedes the condition. It is slightly jargon-heavy ('grounded security gap', 'deeper evidence selection') but wastes no words.

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

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

For a 0-param workflow-step tool with no output schema, the trigger conditions are adequately specified, but with no annotations and no output schema the description should at least indicate the nature of the result or the next step in the chain. It is minimally sufficient rather than complete.

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

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

The schema has zero parameters, so there is no parameter semantics to document; the baseline for a 0-param tool is 4. Nothing in the description conflicts with the empty 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 identifies the trigger ('explicit security testing or a grounded security gap') and hints at the activity ('deeper evidence selection'), but never states what the tool actually does when invoked — no verb+resource beyond the name's 'security testing'. It is distinguishable from most siblings by topic, but the operation itself remains vague.

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 names the routing predecessor ('Use after sumo-qa-deciding-approach routes here') and gives the selecting condition (explicit security testing, or a grounded gap needing deeper evidence). That is a clear when-to-use, though it does not state when NOT to use this versus adjacent siblings like closing_qa_gaps or measuring_coverage.

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 no annotations, the description carries the full behavioral burden. It discloses one meaningful trait – 'Walks the repo with the host's file tools first' – so the agent knows repo reads happen before output. However, it says nothing about whether the tool writes artifacts, what the strategy deliverable looks like, or whether the operation is read-only versus mutating.

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

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

Two sentences, front-loaded with the routing condition before the example asks. The four examples are the bulkiest element but each maps to a distinct ask shape, so they largely earn their 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 zero-parameter, no-output-schema tool the description covers entry conditions and rough behavior, which is most of what an agent needs. The gap is the deliverable: it never says what the strategising produces or how the result should be consumed, leaving the agent to infer the outcome.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is no parameter semantics to add. Baseline 4 applies; nothing is missing or misleading.

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 activity (repo-wide / policy-shaped QA strategising) and grounds it with four concrete example asks, which lets an agent separate it from narrower siblings like sumo_qa_creating_test_plan or sumo_qa_measuring_coverage. The verb 'strategising' alone is abstract, but the quoted asks carry the meaning.

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

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

It states an explicit entry condition ('Use after sumo-qa-deciding-approach routes here') and enumerates the kinds of asks that belong here, which is stronger than implied usage. It does not state when *not* to use it or name a contrasting alternative, 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?

With no annotations, description carries full burden. It discloses that production code stays unchanged and outlines the step-by-step process with confirmation gates. However, it does not detail whether tests are automatically modified or what specifically changes in test files (e.g., assertions).

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 zero waste. Front-loaded with usage context, followed by workflow steps, and ends with a key behavioral constraint. Every sentence adds value.

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

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

Given no parameters, no output schema, and no annotations, description adequately covers purpose, usage, and workflow. It mentions what stays unchanged (production code) but could elaborate on effects on test files. Overall, it is sufficiently complete for a zero-parameter 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?

Tool has zero parameters, so baseline is 4. Description correctly omits any parameter details as none exist. No information is needed beyond what is already provided by schema (100% coverage of empty params).

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

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

Description clearly states the tool's purpose: strengthening tests after sumo-qa-deciding-approach picks strengthen-test-coverage. It specifies a workflow (survivor → tautology check → technique → strengthening test) and explicitly distinguishes itself from siblings by referencing a specific decision outcome.

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

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

Explicitly states when to use: 'Use after sumo-qa-deciding-approach picks strengthen-test-coverage.' Provides context (mutation-testing follow-up, raise-coverage tasks) but does not list explicit exclusions or alternatives. Still, it offers clear guidance for the intended use case.

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 no annotations, the description reveals key behaviors: confirmation before install, fallback on failure, and invocation constraints. However, it omits details about output, persistence of installation, authentication needs, or other side effects, leaving gaps in transparency.

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

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

The description is a concise single paragraph that front-loads usage scenarios. Minor redundancy ('through sumo-qa MCP tools') exists, but overall it is efficient and well-structured.

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

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

Given no output schema, the description fails to explain what the tool returns (e.g., success, result, or error). It also assumes domain knowledge and does not reference sibling tools within the suite, leaving the agent with incomplete context for a complex 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 input schema has no parameters, so schema description coverage is 100%. The description does not add parameter semantics because none exist, meeting the baseline of 3.

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

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

The description clearly states the tool's role: it finds, installs, and executes external skills when no native sumo-qa sub-skill fits or for ingestion conversion. It distinguishes itself from siblings by specifying the exact entry points (deciding-approach fallback or ingestion conversion) and the actions performed.

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 (as a fallback or for ingestion conversion) and notes it is never invoked cold. However, it does not explicitly exclude other scenarios or directly compare to sibling tools like sumo_qa_install_external_skill, though the dual install/execute behavior is 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?

With no annotations, the description carries the burden and does well: it discloses that the tool is diagnosis-only, does not patch, operates before any fix, and gates routing to a fixing skill on confirmation of a product-behaviour gap. It doesn't say what inputs it consumes (repo access? pasted failure output?) or what the diagnosis output looks like, so it falls short of fully rich 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?

Front-loaded with the 'use after' trigger, then examples, then behaviour, then scope boundary. Every sentence carries signal, though the four quoted example utterances are somewhat redundant with the preceding trigger phrasing.

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

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

For a no-param, no-output-schema tool with no annotations, the description covers when to invoke, what it does, its scope limit, and where it hands off. The main gap is how it accesses the failure output and what the classification result contains, which an agent might need to proceed.

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 takes zero parameters, so there is nothing to document and no schema gap to compensate for. Baseline 4 applies; the description adds no parameter meaning because none is needed.

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 'reads the failure output, classifies the likely cause, and names the smallest next isolation step'. The 'Diagnosis only — it does not patch' clause clearly separates it from fixing-oriented siblings like sumo_qa_strengthening_tests and sumo_qa_closing_qa_gaps.

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 entry condition (after sumo-qa-deciding-approach routes here), the triggering situation (test failing or flaky, cause unknown), and gives four concrete utterance examples. It also states the exit condition: routes to a fixing skill only once a concrete product-behaviour gap is confirmed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description is consistent with them. It adds real value beyond the annotations by disclosing the return shape (confidence level, freshness status, explained reason) and the two accepted input modes, which the annotations do not cover.

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 and scope, then the return contract, then the accepted inputs, then routing phrases. Every line is functional; the natural-language phrasing list is the only mild padding, but it serves as disambiguation aid.

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 correctly explains the return fields, and with no required parameters it clarifies the entry/entry_id alternatives. An agent has enough to call and interpret the tool, though precedence between the two inputs remains unspecified.

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 0%, so the description must carry the parameter burden, and it largely does: entry_id is 'looked up in the catalogue' while entry is 'a full record dict'. What is missing is guidance on which to prefer when both could be supplied, and the mutually-exclusive/optional nature of the pair.

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 and resource ('Validate a test data entry') and immediately bounds the scope with 'without provisioning or mutating downstream systems'. That boundary is what separates it from siblings like register_known_good_test_data or find_test_data, though those siblings are never named explicitly.

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

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

Usage context is clear from the negative scope clause and the list of natural-language phrasings ('is this test data still valid', 'check if X is fresh') that should route here. However, it never names an alternative tool or states an explicit condition for when NOT to use it versus the find/register 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?

With no annotations, the description carries the full burden, and it discloses the key behavioral trait: this is a router/entry point, not a tool that answers QA questions itself. It implies no side effects but never states whether the call mutates state or what it returns, leaving a minor gap for a mutation-free read router.

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 directive is front-loaded in the first sentence, and the trigger enumeration serves a real routing purpose. It is longer than necessary — 'test plan, test strategy, test approach' are near-synonyms — but the length is justified by the breadth of QA-shaped requests it must catch.

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

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

For a zero-param, no-output-schema router, the description is nearly complete: it says when to call it and that downstream work happens through siblings. It could briefly state what the call yields (e.g. a route selection) so the agent knows what to expect back, but 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?

Zero parameters and 100% schema coverage, so the baseline is 4. There is nothing to document, and the description correctly adds no parameter noise.

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 role: an entry router for all sumo-qa work that MUST be called first for QA-shaped requests. This clearly distinguishes it from every sibling, all of which are downstream work tools, so an agent can tell it apart 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?

Provides an explicit trigger list (test plan, regression scope, code review, safe-to-merge, TDD, mutation testing, etc.) and an explicit exclusion — do not answer QA questions from training-data knowledge. Both when-to-use and when-not-to-use are covered, plus the alternative (route through this tool instead of answering directly).

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