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

No annotations are provided, so the description must define the safety profile. It does: "This only looks, it will not install anything" establishes a non-mutating, read-only operation. It also explains a non-obvious behavior, that missing scanners are reported as failures rather than skips, though it says nothing about how detection is performed or how costly it is.

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

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

The description is dense and front-loaded, stating purpose first, then parameter modes, then usage triggers, and finally the read-only guarantee. The clause "the ones `draugr doctor` requires" is slightly awkward, but every sentence still contributes useful 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?

An output schema is present, so the return format does not need to be explained. For a single optional parameter, the description covers both invocation modes and the failure semantics that motivate calling the tool. The only gap is detection mechanics and expected latency.

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

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

Schema coverage is 100%, so the single parameter is already documented. The description still adds meaning: with a path, only the tools a scan of that descriptor runs are checked; without a path, everything Draugr knows about, including tools this project never runs, is checked.

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

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

The first sentence gives a specific verb and resource: report which external scanners Draugr can find on this machine. It also distinguishes the tool from siblings like `scan` and `validate_saga`, because the point is detection only, with no installation and no scanning.

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 tells the agent exactly when to call this tool: when a scan fails, or before suggesting a scan. It also gives a supporting reason: a control whose scanner is absent is reported as a failure rather than a pass. It never names a concrete alternative such as `scan` or `validate_saga`, so it stops short of full when/when-not routing.

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

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

No annotations are provided, so the description carries the safety and behavior burden. It clearly describes comparison and reporting behavior and adds useful nuance about inherited findings and PR gate evaluation, though it does not explicitly state read-only status or side-effect profile beyond the inherent diff semantics.

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

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

Three sentences, front-loaded with the core action and immediately followed by the sibling-routing condition and a parameter use case. Every sentence contributes specific guidance 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?

The tool is a report-diff operation with an output schema and fully described inputs, so return values and parameter formats do not need to be repeated. The description supplies the selection rationale, behavioral nuance, and gate-evaluation purpose an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents basePath, headPath, limit, and failOnNew. The description adds meaningful intent for failOnNew by tying it to whether a pull request gate would fail, exceeding the schema's parameter definition.

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: compare two scans and report introduced versus resolved findings. It also explicitly distinguishes the tool from summarize_report by naming the question it answers better, so an agent can select it without opening the schema.

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

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

Gives a clear when-to-use rule: use this rather than summarize_report when the question is whether a change made things worse. It explains the inherited-findings failure mode and adds a concrete use case for failOnNew, leaving little ambiguity about routing.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that the answer comes from the scan report on disk, what is returned, and why the alternative help URI is often worse. It does not explicitly state read-only safety or error behavior, but the read-from-disk framing strongly implies a non-mutating operation.

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

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

The description is three tightly written sentences. It front-loads the core purpose, then return behavior, then usage guidance, with no redundant or filler content.

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

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

For a two-parameter tool with full schema coverage and an output schema, the description provides everything needed: what it does, what it returns, where the data comes from, and when to prefer it over the help URI alternative.

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

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

Schema description coverage is 100%, and both parameters already have clear schema descriptions, including an example of partial ruleId matching. The tool description reinforces the report source but does not add new syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'explain' with the resource 'rule/finding' and scopes it to the scan's own report. It also states that it returns the full check and scanner-published remediation, which clearly distinguishes it from sibling reporting and listing tools.

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

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

It explicitly says to prefer this tool over fetching a rule's help URI and explains why: the answer is already on disk and the URI may lead to a registration form or PDF. This gives a clear usage decision, not just implied 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?

With no annotations, the description carries the burden and does so: it declares read-only behavior ('It only reads') and discloses the remediation path – returning a `draugr feeds update` command rather than mutating state itself. It stops short of noting cost/latency or cache-location details, but for a zero-param status read it covers the safety-relevant 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?

Three sentences, front-loaded with what is reported, then when to call it, then the behavioral note. Every sentence adds distinct information with no repetition of the name or 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?

An output schema exists, so return values need not be explained here. Combined with explicit triggers and the read-only/remediation disclosure, an agent has everything needed to decide to call it and to interpret the result.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The text correctly implies a no-argument, whole-cache check by saying 'each dataset a scan reads from'.

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 (report cache status per dataset) and enumerates the exact feeds involved (CISA KEV, FIRST EPSS, Go vuln DB). No sibling tool covers this ground, so the agent can route to it unambiguously.

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 three explicit trigger conditions: a report marking a feed stale, govulncheck failing offline, and before relying on exploitability ranking. That is when-to-use guidance with concrete conditions rather than vague implication.

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 does well: it discloses that lists come back in a fixed order of kind, that only priority is comparable across lists, that actions tie on priority/exploitation/severity/findings-cleared with meaningless intra-tie order, and that every action is returned unless limit is set. It stops short of saying whether the call reads only or has side effects, but the framing as report analysis makes the read-only nature evident.

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, but the prose is dense and run-on, with clauses like "each action saying how many findings it clears and what it ranks by" and the tie-breaking sentence stacking four conditions. The second half drifts between output semantics and tool-selection advice, which could be split for faster scanning.

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

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

An output schema exists, so return shape needn't be described, and the description still covers ordering, cross-list comparability, tie semantics, and filtering behavior. Combined with the fully documented three-parameter schema, an agent has nearly everything needed; only an explicit statement of read-only behavior is missing.

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

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

Schema coverage is 100% and the kind enum and limit default are already documented in the schema, so the description adds little parameter-specific meaning beyond restating that limit bounds results. The one useful addition is that omitting kind yields every list, which the schema also implies. Baseline 3 is appropriate.

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

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

"Turn a report into the things to do about it, one list per kind of work" states a specific transformation plus the grouping, and the parenthetical enumerates the kinds (bump, code, infrastructure, credential, wait, decide). It also explicitly names the sibling it is not (summarize_report), so an agent can separate the two without reading 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?

"Ask this rather than summarize_report when the question is what to change" gives an explicit alternative and the condition that selects it, reinforced by the rationale that one upgrade clears many findings and a shared image is one action. It also notes "which list to work from is the reader's choice", so no implicit workflow is assumed.

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 disclose meaningful traits: the schema is pinned to the running build, unknown keys are rejected, and the schema is authoritative over guesses. It doesn't state that the call is side-effect free or versioned, but the 'Return' verb plus output schema largely covers that.

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 the core purpose front-loaded and no filler. The second sentence is a comma splice ('...field names, the schema is the authority...') that slightly muddles the strictness point, but the content 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-parameter read tool with an output schema, the description supplies what structured fields can't: the versioned nature of the schema and its strictness. A note on how it relates to validate_saga would close the last 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?

Zero parameters, so the baseline of 4 applies. The description correctly adds nothing about parameters and instead spends its text on what the returned document governs.

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

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

States a specific verb and resource: 'Return the JSON Schema for the Saga descriptor (*.saga.yaml)'. It also scopes the schema to 'this build of Draugr', which distinguishes it from validate_saga and propose_saga in the sibling list.

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 it to write or correct a descriptor rather than guessing at field names' gives a clear triggering context and names the anti-pattern it replaces. It stops short of naming sibling alternatives such as validate_saga, which an agent might reasonably confuse it with.

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 must carry the behavioral burden. 'List' implies a read-only operation and the description discloses the kind of information returned, but it does not explicitly state side effects, auth requirements, or rate-limit behavior. For a simple zero-parameter list tool this is adequate, but not rich.

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 tightly written sentences with no wasted words. Purpose and return content are front-loaded, followed immediately by the key usage instruction. It is appropriately sized for a simple list 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?

The tool takes no parameters and has an output schema, so the description does not need to enumerate return fields or parameter details. It covers what the tool lists, what the agent will learn, and when to call it. Nothing critical is missing for correct invocation.

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

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

This tool has zero parameters, so parameter semantics are inherently minimal. The description correctly avoids introducing nonexistent inputs. 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 gives a specific verb and resource: list the security controls Draugr can run. It also previews the returned fields, which helps an agent understand what kind of controls these are. Sibling differentiation is only implicit through the word 'controls' and the Saga workflow context, so it falls short of a perfect 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?

It explicitly says to call this before writing or editing a Saga descriptor and explains the reason: so enabled controls are ones that exist. That gives clear usage context. It does not name when-not-to-use conditions or specific alternative tools, 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?

No annotations are provided, so the description carries the full disclosure burden and it does deliver the essentials: the return content (names plus what each discovers) and a hard prerequisite relative to survey. It stops short of stating that the call is side-effect free or cheap to repeat, which for a zero-parameter list is a minor residual gap rather than a risk.

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

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

Two short sentences, zero filler, with the enumeration purpose front-loaded and the sequencing advice second. Every clause carries distinct 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 no-argument, read-style enumeration tool with an output schema covering the return shape, the description supplies the only things the structured fields cannot: what is listed and when to call it relative to survey. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline applies. The description correctly adds no pseudo-parameter detail, though it also doesn't note that the scope is implicitly "this build" as opposed to all builds.

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 ("Name") and resource ("the surveyors this build has") plus the payload ("what each discovers"). This is immediately distinguishable from the survey sibling, which performs the survey rather than enumerating available surveyors.

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 prescribes ordering ("Call it before survey") and gives the reason ("so the surveyor you ask for is one that exists"). It names the alternative tool and the condition that should route the agent here first, leaving nothing to inference.

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

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

With no annotations, the description carries the behavioral burden and clearly states that the tool writes nothing and only returns a proposal. It also explains the intended user-review workflow, though it does not detail file-read permissions or 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?

Three sentences, front-loaded with the core purpose and followed by usage and safety context. Every sentence contributes distinct information with no 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 is complete for this tool given the rich input schema and the presence of an output schema. It covers purpose, usage condition, side-effect profile, and user workflow without needing to restate return structure.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including `path` and `perDirectory`. The description adds only general context about proposing for a directory and does not add parameter-specific meaning beyond the schema.

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

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

The description states a specific verb and resource: return the Saga descriptor `draugr init` would write for a directory, as YAML. It distinguishes this from writing a descriptor and names the sibling tool `get_saga_schema`, so the agent can tell what this tool 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?

It gives an explicit usage condition: call this when a project has no descriptor, before writing one from `get_saga_schema`. It also tells the agent what to do with the result: show the proposal to the user, who decides whether and where to save 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?

With no annotations supplied, the description carries the full burden and does so thoroughly: it discloses cost ('expensive'), concrete side effects (clones repositories, executes external scanners, reaches the network), an implicit config merge from the server's working directory, and a human-approval gate for scanners that probe live hosts or exfiltrate results. That is exactly the behavioral context an agent needs before invoking a side-effecting 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?

The core purpose, cost and alternative are front-loaded well, but the middle section is a long run-on ('If the question was whether a repository is safe to ship rather than whether it passes this gate, keep looking after this returns, the findings here are the part that can be checked...') that restates the earlier 'not a substitute for reading the code' point. The description would be stronger with that redundancy cut.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description instead spends its length on the things structured fields cannot express: scope limits, side effects, and when results are not the whole answer. Nothing an agent needs to decide whether and how to call this is missing.

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

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

Schema description coverage is 100%, so path, limit and minPriority are already documented in the schema; the description adds no syntax, defaults, or interaction detail for them. The one parameter-adjacent fact it adds, the draugr.config.yaml merge from the working directory, is not an input parameter at all.

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 ('Run a scan for a Saga descriptor') plus the return shape ('verdict with findings ranked by priority'). It also distinguishes itself from the sibling summarize_report by naming it as the cheaper alternative when a recent report exists.

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

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

Explicit when-to-use routing ('Prefer summarize_report when a recent report already exists'), explicit scope boundary ('runs the controls the descriptor declares... and nothing else'), and explicit exclusions of what the scan will not answer (trust boundaries, secrets in build context, credential passing, protocol assumptions). The approval prerequisite for side-effecting scanners is also 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 burden and does real work: it discloses deduplication, priority ranking, the presence of documentation links, and the important caveat that coverage is a 'floor' limited to what the scan ran. It also explains how to treat accepted findings ('report it as a decision and do not propose fixing it'). It stops short of stating the read-only/non-mutating guarantee outright or what happens when the named file is 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?

The core purpose and the usage caveat are front-loaded well, but the middle sentences drift into return-value documentation ('descriptor.exclusions[].gitHistory', fingerprint naming) that the output schema already covers. The git-history sentence is dense and tangential to invoking the tool, and the report.json/sarif sentence duplicates the path parameter description.

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

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

Output shape is covered by an output schema, so the description only needed purpose, routing, and caveats — all present, including the scope limitation and accepted-finding handling. Missing only an explicit statement that the operation is read-only and what surfaces if the SARIF file is missing or malformed.

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

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

Schema description coverage is 100%, so path, limit and minPriority are already documented, including the report.json-beside-it relationship that the description repeats almost verbatim. The description adds no new syntax, default, or interaction detail (for example how minPriority interacts with the returned ranking) beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The opening sentence gives a specific verb and resource ('Read the results.sarif an earlier draugr scan wrote') plus the output shape (ranked, deduplicated, with rule documentation links). The clause 'without starting a new one' cleanly separates it from the sibling 'scan' tool, and 'what should I fix first?' pins the intent.

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 the use case clearly ('from a scan that already ran') and rules out the obvious alternative (starting a new scan), and it tells the agent to pass report.json's sibling results.sarif. It does not reference other plausible siblings such as fix_list, diff_reports or explain_rule, so the routing guidance stops one step short of complete.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool reads a live system using credentials already present on the machine, and that it returns YAML rather than writing a file, establishing a read-only, non-destructive profile. It stops short of stating failure behavior, credential prerequisites, or latency for live API calls.

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

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

Three sentences, front-loaded with the purpose, followed by the selection rationale and the operational profile. No filler; every sentence adds decision-relevant 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?

An output schema exists so return values needn't be detailed, and all three parameters are documented. Combined with the safety and credential disclosure, an agent has nearly everything needed; only credential setup and error behavior are unaddressed.

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

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

Schema description coverage is 100%, including per-field notes for ref, surveyor, name, and version, so the baseline is 3. The description adds the merge semantic implicitly (multiple surveys combine into one descriptor) but nothing about parameter syntax or format beyond what the schema already states.

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

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

The description names a specific verb and outcome — discover the real composition of a system (namespaces, images and digests, repos) and return a Saga descriptor. It is clearly distinguishable from siblings like list_surveyors, propose_saga, and get_saga_schema, since it produces a descriptor from live observation rather than from a provided 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?

"Prefer this over writing a descriptor from the schema" gives an explicit alternative and the reason to choose this tool (real namespaces, images, and digests cannot be guessed). It lacks an explicit when-not or the prerequisite step of calling list_surveyors first to learn surveyor names, which is only implied via the schema.

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 does so well: 'free and has no side effects' explicitly declares a read-only, safe operation, and 'report what's wrong' sets expectations for the result. It stops short of describing granularity of findings, but an output schema exists to cover the return shape.

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

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

Two tight sentences with zero filler. The core action is front-loaded, followed by input options and then the usage recommendation in priority order.

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-optional-param tool with full schema coverage and an output schema, the description covers purpose, input alternatives, and safety profile — enough to invoke correctly. Only marginal detail, such as what happens if both inputs are supplied, is left unaddressed.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds value by framing path and content as mutually exclusive alternatives ('give either... or...'), resolving the ambiguity of both being optional; the content parameter's pre-write use case is reinforced in prose.

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 pair: check a Saga descriptor against the schema and report what's wrong. This is clearly distinguishable from siblings like get_saga_schema (retrieves the schema) or explain_rule (explains rules), though it never names an 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?

Explains the two input modes (path on disk vs. YAML content) and gives a clear usage directive: 'prefer it over assuming an edit was correct.' That establishes when to call it, but there is no explicit when-not condition or named alternative for edge cases.

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