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

Annotations mark it non-read-only and non-idempotent, and the description adds the reasons: write_overlay writes a file to a fixed path, artifact_path=None saves nothing, and probable_mapping_gap is a naming gap rather than zero coverage. These are genuine behavioral disclosures beyond the annotations, though it doesn't say whether the overlay is overwritten or merged.

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 before parameter detail, and each clause carries real information (semantics of None, the mapping-gap caveat). It is dense but not padded; a light trim of the parentheticals would earn a 5.

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 does the work by naming what the result contains (tests, risk surface, affected nodes, staleness). Side effects and the mapping-gap nuance are covered, making it adequate for a 5-param analysis tool, though the exact output shape is only sketched.

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 across 5 params, the text explains changed_files (repo-relative), base_ref (merge-base diff), artifact_path (source vs live scan vs None saves nothing) and write_overlay (writes a specific path). Only root is left unelaborated, which is nearly self-evident.

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: 'Map changed files onto the repo-map' and enumerates the outputs (likely tests, risk surface, affected nodes, staleness). This distinguishes it clearly from the read-only query_repo_map sibling, though it never names that alternative 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?

Gives concrete operating modes: 'Pass changed_files (repo-relative) or base_ref (diffed from its merge-base with HEAD)' and explains the map source resolution. It states how to invoke but does not explicitly contrast when to pick this over query_repo_map or scan_repo.

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 already declare the safety profile (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely non-structured behavior: no auto-capture, mandatory user confirmation per write, and a rejection policy for raw diffs, secrets, code and pasted issue/PR bodies. The only tension is that a 'delete' action is offered while destructiveHint=false; that is a mild inconsistency worth noting but the description itself supplies the operational detail the annotation lacks.

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

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

The purpose is front-loaded in one sentence, followed by a compact action/parameter map and then the confirmation and rejection rules. Dense backtick notation is efficient, though the action block is close to schema restatement and the line-wrapped formatting slightly hurts scannability.

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

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

For a four-parameter mutation tool with no output schema and no annotation nuance, the description covers actions, scope resolution, nested entry fields and write preconditions well enough to call it correctly. The one remaining gap is that it never says what `list` returns (e.g. whether entries carry the `entry_id` needed for update/delete), leaving an agent to infer the lookup flow.

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% and `entry` is an opaque anyOf object with additionalProperties:true, so the description carries the full burden — and it does, naming the entry fields (`scope`, `trigger_signal`, `recommended_probe`, `source_note`, optional `last_reviewed`) and stating which parameters each action needs. It also documents scope's enum-like values and its error behavior ('else an error') plus the requirement that `entry` carries its own scope. Only field-level types are left implicit.

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 opening sentence states a specific verb and resource — managing a user-confirmed memory of recurring review lessons — and immediately qualifies it as 'advisory hints that never override the catalogues', which separates it from the catalogue/rule loader siblings. The action enumeration ('list'/'capture'/'update'/'delete') makes the CRUD surface explicit 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?

Each action is tied to its required inputs, defaults are named ('list' is default, 'project' is default scope), and the description states that writes require explicit user confirmation and that nothing is auto-captured — a real usage constraint. It does not say when to prefer this tool over catalogue-loading siblings or when capturing feedback is warranted versus simply recording a mutation, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=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?

The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds that this is an explanatory output covering entity characteristics, state, preconditions, dependencies, edge cases, and exclusions, but it does not describe the response format or any operational limitations.

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

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

The description is a single front-loaded sentence with a compact list of what the explanation covers. It contains no repeated boilerplate or wasted clauses.

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

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

The description is sufficient for understanding the tool's explanatory purpose but incomplete for its inputs, since domain and environment are undocumented, and there is no output schema to explain the answer format. For a three-parameter explanation tool, this is minimally adequate but has 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%, so the description must compensate for all three parameters. It clarifies the required 'question' parameter through the example phrase, but it does not mention what 'domain' or 'environment' mean or how they affect the explanation.

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: 'Explain the test data a scenario needs', and lists the dimensions of that explanation. It distinguishes itself conceptually from sibling data tools like find_test_data by focusing on explanation, but it does not explicitly name or contrast those alternatives.

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

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

The quoted example 'what data do I need to test X' implies when the tool is appropriate, but the description gives no explicit when-not-to-use guidance or routing to siblings such as sumo_qa_find_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?

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 readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing result ranking dimensions (confidence, freshness, suitability) and pagination via the response's next_offset. It stops short of saying whether an empty result is possible, how ranking ties break, or whether the catalogue is pre-populated.

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

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

Two sentences, zero filler, and the core intent is front-loaded before the narrowing and pagination details. Every clause carries information an agent would otherwise have to infer.

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?

Pagination and the narrowing filters are covered, and referencing 'the response's next_offset' usefully compensates for the absent output schema. But with 8 parameters at 25% coverage, an agent still cannot tell what sku/domain/product_id/environment filter on, which is a substantive gap for a search tool whose whole job is filtering.

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

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

Only 25% schema description coverage across 8 parameters, so the description has to compensate and only partly does: scenario_tags, known_valid_for, offset and limit behaviour are addressed. The four filter parameters sku, domain, product_id and environment are never mentioned, leaving half the surface undocumented in both places.

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, returning ranked matches with confidence, freshness and suitability. That is far more than a restatement of the name. It does not, however, distinguish itself from the similarly named sibling sumo_qa_finding_test_data, so an agent must guess which of the two to call.

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 parenthetical 'find me test data for X' gives a clear implied trigger, and 'scenario_tags and known_valid_for narrow it' explains how to refine a query. But there is no when-not guidance and no named alternative (e.g. finding_test_data, load_catalogue_entry), which matters given the crowding of siblings in this namespace.

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 declare read-only, idempotent, closed-world, non-destructive; the description is consistent and adds real behavioral content: the host gathers the data (no fetching), and 'only a fresh pass supports safety' states a decision rule the agent must honour. It stops short of describing truncation behaviour or output shape details beyond 'compact markdown brief'.

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

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

Front-loaded with purpose and the no-network constraint, then a compact telegraphic enumeration of bundle keys. Dense but every clause carries information; the only cost is that the key listing is terse enough to be 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?

No output schema exists, and the description does state the return is a compact markdown brief, plus it documents the otherwise-undocumented nested bundle. Given a free-form nested object and three parameters, an agent has enough to call it correctly; only `max_files` truncation behaviour is unaddressed.

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

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

Schema coverage is 0% and `bundle` is a free-form object with no property documentation, so the description carries the load — and it does, enumerating issue_summary, pr_summary, head_sha, changed_files ({path, change_kind}), test_evidence/ci_status ({result, freshness, source}), and user_constraints, plus the freshness enum semantics. `max_files` (default 40) is left unexplained, which is the main 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: 'Render a host-gathered issue/PR context bundle as a compact markdown brief', with an explicit boundary ('no repo or network access'). An agent can distinguish it from the other formatter siblings (format_risk_ledger, format_qa_scorecard) by the 'context bundle' input, though it doesn't name those alternatives directly.

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?

'no repo or network access' and 'host-gathered' imply the tool is a pure formatting step that must be preceded by data collection elsewhere, which is useful implied guidance. However, there is no explicit when-to-use / when-not / alternative-tool routing among the many sibling formatters and report generators.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real behavioral content beyond them: the four verdicts, the refusal rule for uncovered blockers and stale evidence, and the hard dependency that a bundle naming a head_sha cannot support 'ready' without local_head_sha. It stops short of describing what the returned scorecard contains (e.g. the reasons list / truncation).

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 verdict list and the refusal invariant are front-loaded, and every sentence (including the parenthetical ledger field enumeration) earns its place by disambiguating inputs. It reads as a dense run-on with multiple nested parentheses, which slightly hurts scanability, but there is no filler.

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

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

For a 7-parameter, no-output-schema tool this description is close to complete: it defines the decision space, the refusal conditions, and the input contracts that matter for correctness. What is missing is the shape of the result (reasons, and how max_reasons bounds them), which matters more here because no output schema exists to document it.

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

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

With 0% schema description coverage, the description must carry the parameters, and it largely does: it enumerates the ledger_rows fields and their status/residual value spaces, points to sumo_qa_format_context_bundle for the context_bundle shape, explains that absent coverage/mutation means 'not measured', and states the local_head_sha constraint. The notable gap is max_reasons, which is 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 opens with a specific verb and resource ('Compute QA readiness... from existing evidence') and enumerates the exact verdict space (ready / ready_with_accepted_residuals / blocked / insufficient_evidence), so an agent knows precisely what this tool produces. It does not, however, name or contrast itself with close siblings such as sumo_qa_generate_qa_report or sumo_qa_reviewing_before_merge, which an agent choosing among merge-gate tools would want.

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?

'from existing evidence' and the list of optional inputs imply the precondition (you supply ledger rows / a context bundle) and the invariant 'an uncovered blocker or stale evidence refuses ready' hints at when a 'ready' answer is trustworthy. There is no explicit statement of when to prefer this over sibling reporting/review tools, so the usage guidance is inferable 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds that rows are validated against fixed status vocabularies, but does not say what happens on an invalid row (rejected, coerced, dropped) nor that max_rows=25 silently truncates output. Useful but incomplete behavioral context.

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

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

The action is front-loaded in the first clause, followed by a compact field-level spec; there is no filler. Slight awkwardness in 'the host names the risks' and the fragmentary row spec, but overall tight and scannable.

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

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

For a two-parameter formatter with no output schema, the description tells the agent the output is a markdown table and defines the row contract well. It leaves open validation-failure behavior, truncation via max_rows, and whether the markdown string is the sole return value, which an agent would need before calling.

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 burden: it fully documents the `rows` item shape with field names, allowed enum values, and which field is optional, which is genuinely valuable. However, `max_rows` is never mentioned, so half the parameters remain undocumented and truncation behavior is invisible to the agent.

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

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

States a specific verb pair (validate and render) plus an unambiguous resource (risk-to-test ledger as a markdown table), and the caller role is clarified with 'the host names the risks.' The enumerated row fields distinguish it clearly from formatting siblings such as 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?

No statement of when this tool should be chosen over sumo_qa_generate_qa_report, sumo_qa_format_qa_scorecard, or sumo_qa_record_coverage, and no preconditions (e.g. risks must already be identified). Only vague implication from 'the host names the risks' that the caller supplies the risk list.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, closed-world tool. The description adds meaningful behavior beyond that: degraded artifacts are surfaced as missing/stale rather than passing, and the write side effect only occurs when `write_to` is supplied, which is exactly the kind of mutation caveat an agent needs.

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

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

Front-loads the core action and result in the first sentence, then layers the degradation rule and parameter overrides. Dense but every clause earns its place; the backticked path convention is useful rather than padding.

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

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

With no output schema, the description states the return is a compact readiness summary and explains how missing/stale artifacts appear. For a 4-parameter tool with zero schema descriptions, it covers the essential behavior, though it leaves the readiness-summary shape and the override object expectations 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 carries the burden and largely does: `root` scopes the artifact lookup, `write_to` is explained with a conventional path, and `risk_ledger_rows`/`context_bundle` are described as file overrides. It stops short of stating shapes or formats for the override objects, but all four parameters get semantic meaning.

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

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

States a specific verb (compose), resource (`.sumo-qa` artifacts under `root`), and outcome (local QA report plus compact readiness summary). It implicitly distinguishes itself from the format_* siblings by naming `risk_ledger_rows` and `context_bundle` as inputs it consumes rather than produces, though it never names an alternative tool 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?

The conditional behavior is clear for `write_to` (writes the page, otherwise nothing is written) and for degenerate artifacts (shown as missing/stale, never passing). However, there is no explicit guidance on when to call this versus `sumo_qa_format_qa_scorecard` or the other format_* siblings, so the agent must infer placement 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 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?

Beyond the readOnly/idempotent annotations, it discloses real behavior: slices carry content_hash, passing known_hash short-circuits with changed=false and no body, oversized bodies return an `oversize` pointer, and bad input returns an error envelope listing valid choices. That is genuinely useful context an annotation could not carry; only the return payload shape itself is left thin.

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

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

Dense and largely front-loaded, with mode described first, but the single paragraph with deeply nested parentheticals makes the bundle semantics hard to parse. Every clause carries information, so it earns its length, but the lack of structure works against it.

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

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

For a 9-param, zero-coverage tool with no output schema, the description covers modes, hashing, error behavior and failure signaling. But it leaves skill_name unexplained, doesn't say what a 'skill' is or where to get the name, and doesn't note which mode is the default when mode is omitted.

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 9 params, so the description must carry the load — and it does for most: mode values, section/module singletons vs comma-separated modules/catalogues/classification, include_body=false, and known_hash semantics. The notable omission is skill_name, the primary identifier, whose format and source (presumably from list_skill_manifests) 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: it loads one slice of a skill, with enumerated modes (manifest, section, module, full, bundle). It implicitly distinguishes itself from sibling loaders (load_rules, load_principles) by operating on skill slices, but never states that distinction outright, and the concept of a 'skill' is never defined.

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 mode breakdown implies usage (use 'bundle' for one call, 'manifest' to discover ids), which is better than nothing. However there is no explicit instruction on when to call this versus sumo_qa_load_rules, sumo_qa_load_catalogue_entry or sumo_qa_load_techniques, nor any stated prerequisite such as a prior manifest call.

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 safety, and the description adds real behavioral value on top: matching is case-insensitive across listed fields, results are ranked and capped at `limit`, `total_matches` reports the full count, and the whole map is never returned. It omits where the map comes from and what happens if the artifact is absent, which is the missing piece for a 5.

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

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

A single dense paragraph that front-loads the verb and resource, then layers matching semantics, result capping, and the `types` filter. Every clause carries information; slightly run-on, but no filler.

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

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

With 5 parameters, no output schema, and zero schema description coverage, the description covers the search semantics well but leaves `root`, `artifact_path`, and the map's existence dependency unexplained. An agent could invoke it, but might not know how to point it at the right map.

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 is the only source of parameter meaning. It explains `query` (case-insensitive over ids/paths/names/types/tags), `limit` (cap with `total_matches` for the full count), and `types` (node type or 'command'). It says nothing about `root` or `artifact_path`, leaving 2 of 5 parameters semantically undocumented.

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 ('Search') plus resource ('repo-map') and an explicit enumeration of what can be matched (components, tests, CI checks, configs, commands) and over which fields (ids, paths, names, types, tags). It does not explicitly distinguish itself from sumo_qa_scan_repo, which likely builds the map this tool queries, so it falls short of a 5.

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

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

The clause 'never the whole map' implies this is for targeted lookups rather than exhaustive enumeration, but no alternative tool is named and no prerequisite is stated (e.g., whether sumo_qa_scan_repo must run first to produce the map). Usage is implied rather than prescribed.

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

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

The annotations already establish that this is a non-read-only, non-destructive, non-idempotent write operation. The description adds meaningful behavior beyond that: it validates before saving, writes to a default QA coverage path, confines relative `write_to` values inside `root`, and states that coverage is 'Reported, never gated.' It does not clarify overwrite behavior when the target file already exists.

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

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

The description is compact and front-loaded: the core action and destination appear first, followed by path-safety details, coverage field semantics, and gating behavior. Every clause carries information useful for calling the tool, with no filler.

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

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

For a write tool with a nested coverage object and no output schema, the description covers the essential call semantics: validation, destination path, relative path confinement, coverage field meanings, and that the result is reported but not gated. The missing pieces are the meaning of `root` and whether existing coverage files are overwritten, which are minor but real 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%, so the description must carry parameter meaning, and it does so well for the nested `coverage` object by naming `line_percent`, `freshness`, `detail`, `source_tool`, and `generated_at` with useful value notes. It also explains relative `write_to` path behavior. The required `root` parameter is not described, which keeps this from being fully complete.

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

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

The description starts with a specific verb pair (validate and save) and a precise resource (a host-collected coverage summary) written to `.sumo-qa/coverage.json` for the QA report. The 'host-collected' qualifier distinguishes it from the sibling `sumo_qa_measuring_coverage`, which implies measurement rather than recording.

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

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

The description makes the usage context clear: this is for validating and recording an already-collected coverage summary for the QA report, and relative `write_to` paths are confined under `root`. It does not explicitly say when to use `sumo_qa_measuring_coverage` instead, so it stops short of full when/when-not guidance.

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

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

Annotations already declare write, non-destructive, non-idempotent, closed-world. The description adds meaningful behavior: it validates input, enforces path containment for relative write_to, and clarifies that results are reported rather than gated. Overwrite semantics are not mentioned, but the key behavioral traits are disclosed.

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

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

The description is front-loaded with the primary action and uses compact notation for parameter fields. It is dense but waste-free, with minor readability cost from semicolons and backticks.

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

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

For a write tool with no output schema and 0% schema coverage, the description covers the essential behavior: validation, artifact location, path safety, parameter fields, and non-gating reporting. Minor gaps remain around root semantics and overwrite behavior, but the definition is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden. It thoroughly describes the mutation object fields (survivors, killed with >=0 and omission semantics, freshness enum values, detail, source_tool, generated_at) and explains write_to path containment and default. The root parameter is only implicitly described via containment, leaving a small 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?

States a specific verb+resource: validate and save a host-collected mutation summary to a defined artifact path. The resource (mutation summary) is distinct from sibling tools like record_coverage, though the description does not explicitly differentiate from siblings.

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

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

Clear context is given: use for a host-collected mutation summary to feed the QA report, and note that results are 'reported, never gated'. No explicit when-not conditions or named alternatives are provided, but the intended usage is sufficiently 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 the write/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's job is to add behavior, and it does: it discloses a duplicate-detection rule keyed on environment, domain, product/SKU plus overlapping scenario_tags and known_valid_for. Gaps remain on what actually happens when a duplicate is flagged (rejected, overwritten, or only reported) and whether the write creates the file when absent.

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 target file and the duplicate rule before the field list; nothing is padding. The first sentence is dense — the duplicate criterion is parenthetically packed in — but every clause conveys actionable 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 mutation tool with a nested-object parameter and no output schema, the description covers inputs well but leaves the post-call picture undefined: no return value, no duplicate outcome, no error conditions. An agent can call it, but cannot predict what it gets back or how to react to a flagged duplicate.

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% and the single parameter is an untyped object with additionalProperties=true, so the description carries the full burden — and it enumerates every expected key plus the confidence enum values and its 'low' default. It does not mark which keys are required versus optional, and gives no type hints for list-like fields such as scenario_tags or known_valid_for.

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 ('Add or update') and resource ('an entry in knowledge/test_data/<domain>/known_good.yaml'), so an agent knows exactly what is written and where. It does not, however, distinguish itself from closely named siblings such as sumo_qa_validate_test_data or sumo_qa_find_test_data, which the description never mentions.

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

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

Usage is only implied: the agent must infer that this is the tool for persisting a validated test-data entry into the known-good catalogue. There is no explicit 'use when', no prerequisite (e.g. validate first), and no statement of what to do instead if the entry already exists.

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 already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds useful behavioral context beyond that: it says the normal return is a compact summary with specific count categories, and that `write_to` changes behavior by writing the full repo-map JSON. It does not discuss permissions, performance, or failure behavior, but the annotations carry much of the safety profile.

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

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

The description is two sentences, front-loads the main action and return value, and has no wasted wording. The parenthetical count list adds useful detail without becoming verbose.

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 tool with no output schema, the description explains the summary return values and the `write_to` side effect. However, it omits `generator_version` entirely and does not describe the structure of the full repo-map JSON or any failure conditions. It is adequate but incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It explains `root` as the repository to scan and explains that `write_to` writes the full repo-map JSON, but `generator_version` is not mentioned at all. That is partial compensation, not full coverage.

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

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

The description states a specific verb and resource: scan the repository at `root` and return a compact QA-shape summary. It lists the exact counts included, so the purpose is clear. It does not distinguish this from the related sibling `sumo_qa_query_repo_map`, which is a notable sibling-differentiation 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?

The description explains what the tool does but gives no guidance on when to use it instead of `sumo_qa_query_repo_map` or other repo-analysis siblings. There are no exclusions, prerequisites, or decision criteria for invoking 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?

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description's 'without touching downstream systems' usefully reinforces the no-side-effects guarantee, but it does not disclose what validation actually checks or how failures are surfaced, adding only modest context over the annotations.

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

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

A single sentence with the action and the key constraint front-loaded; every clause earns its place, and the parenthetical efficiently disambiguates the two input modes.

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 should say what a validation result looks like (validity flag, error list, etc.), which it omits. For a two-optional-parameter tool with no schema descriptions, the input side is covered but the outcome side is not.

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 explain both parameters: `entry_id` comes from the catalogue, while `entry` is a full dict. That adds real meaning beyond the bare anyOf definitions, though it omits what happens if both are supplied or neither is (precedence/error behavior).

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

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

The description pairs the specific verb 'Validate' with the resource 'test data entry' and clarifies the two acceptable input forms (catalogue `entry_id` or a full `entry` dict). It implicitly separates this from mutation siblings by stating it does not touch downstream systems, though no sibling is 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?

The phrase 'without touching downstream systems' implies a dry-run/check-only usage context, which helps an agent choose this over sumo_qa_record_mutation or sumo_qa_register_known_good_test_data. However, it never states when to prefer validation over those tools or what prerequisites exist, leaving the routing decision 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 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.