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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description's 'save a new report' is consistent, adding the useful detail that a new artifact is produced rather than an in-place update. It does not disclose whether prior reports are overwritten, permission requirements, or how cached intelligence is refreshed.

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 that states the action, inputs, and outcome with zero filler. 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?

An output schema exists, so return values needn't be explained, and the operation is simple with one parameter. However, the description omits prerequisite/permission context and any routing advice relative to the many sibling tools, leaving the definition only minimally 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 the single report_id parameter, so the description must carry the burden. It refers to 'a saved inventory' and 'a new report' but never clarifies what report_id identifies or its required format, leaving the parameter's semantics under-specified.

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 scope: re-evaluate a *saved* inventory against *current cached intelligence* and save a new report. The word 're-evaluate' plus 'saved inventory' distinguishes it from siblings like audit_scan or audit_start, which imply fresh scans, without naming them 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?

There is no explicit when-to-use, when-not-to-use, or alternative routing. The phrase 'saved inventory' weakly implies an existing report is prerequisite, but the agent receives no guidance on choosing this over reports_compare, audit_scan, or intelligence_sync.

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 discloses real behavioral limits beyond the annotations: findings stay candidates, freshness and installed-build correspondence remain unverified, ipa_trust_policy does not verify Apple signer identity or revocation, and there is "No network or device mutation." This is strong for a non-read-only tool, though it never explains what state the readOnlyHint=false operation actually writes.

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

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

Purpose is front-loaded and each sentence conveys parameter-scoping or verification-limit information with little filler. It is dense to the point of being hard to parse in one read, which keeps it from 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?

An output schema exists, so return values need no explanation. Combined with the extensive caveat coverage the description gives an agent enough to call the tool correctly for the main artifact types, with only a few parameters 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?

With 0% schema description coverage and 11 parameters, the description carries the full burden and does compensate for most of it: apk_set_device, ipa_trust_policy, configuration, dependency_module, runtime_configuration, dependency_evidence, and specs all get usage context. sbom, source_module, device_info, and target remain undocumented, so it is not a clean 5.

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

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

The opening clause states a specific verb and resource set: "Inspect local source/APK/AAB/APKS/IPA using cached intelligence." An agent immediately knows the artifact classes covered. It does not, however, differentiate itself from siblings like audit_start or audit_reassess, so it stops 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?

Some conditional usage is given (APKS requires apk_set_device with sdkVersion, supportedAbis, screenDensity, supportedLocales), which is genuinely useful. But there is no guidance on when to choose audit_scan over audit_start, audit_reassess, or dependency_check; usage is implied 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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds substantial behavioral context beyond that: APKs are inspected individually without installation or manifest/resource merging, ipa_trust_policy anchors are for cryptographic chain checks only (no signer identity, revocation, or authenticity verification), and configuration does not undergo build-system merge. These 'what it deliberately does not do' statements are exactly the kind of disclosure annotations cannot carry.

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

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

The purpose is front-loaded, which is good, but the parameter explanation is one dense run-on block of semicolon-separated clauses with no structure. Every clause carries information, yet the lack of segmentation makes it hard to scan for a specific parameter.

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 covered, and the description handles most of the 11 parameters plus follow-up tools. However, for an 11-parameter tool with 0% schema coverage, the unexplained 'target' (the only required parameter), 'sbom', 'device_info', and 'source_module' leave a real gap.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it explains apk_set_device's required sub-fields (sdkVersion, supportedAbis, screenDensity, supportedLocales), the semantics of ipa_trust_policy, configuration, dependency_module, runtime_configuration, dependency_evidence, and specs. It leaves sbom, target, device_info, and source_module unexplained, so compensation is incomplete.

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 ('Start a persistent offline audit') and the 'persistent/offline' qualifier is meaningful scoping. It does not explicitly differentiate itself from the sibling audit_scan, so an agent must infer the distinction rather than being told.

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 names follow-up tools ('Use jobs_status for progress and jobs_cancel to stop it'), which is useful routing, but never states when to choose audit_start over audit_scan, specs_validate, or dependency_check. Usage is implied by the parameter descriptions 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description does not contradict these but also adds no behavioral context beyond listing what is discoverable. No information about response format, caching, or auth requirements 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?

A single tight sentence with no filler. It is front-loaded with the verb and enumerates the discovery scope compactly. However, the enumeration of four categories in one sentence is dense without structuring, and there is no elaboration on any of them.

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

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

There is an output schema, so the description need not explain return values, and with zero parameters the schema burden is minimal. Still, for a capability-discovery tool the description could clarify what an agent should do with the results or when it is worthwhile to call it. It is minimally viable but leaves usage context to the agent's inference.

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 calibration the baseline is 4. There are no parameter semantics to misrepresent, and the description appropriately does not invent any.

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 what is being discovered (input types, evidence states, runtime requirements, interfaces), but the verb is essentially 'Discover' and the tool is a metadata/capability introspection endpoint. It does not clearly distinguish itself from siblings like specs_validate or runtime_devices, which also touch on runtime and specs concerns. The purpose is inferable but 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?

No guidance on when to call this tool versus any of the 23 siblings. An agent has no indication whether this should be called at startup, before audits, or only in certain contexts. The description gives no when/when-not/alternatives information.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the external-write profile is partly covered. The description adds genuinely non-inferable behavior: excluded packages are never transmitted or marked checked from cache, and batched queries preserve per-package pagination and partial failures. It still omits what happens to the existing report being overwritten and any auth or rate-limit constraints.

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?

Four sentences, no filler, purpose front-loaded before the parameter and behavior details. Each sentence conveys a distinct actionable fact (mode semantics, exclusion glob syntax, exclusion side effects, batching behavior).

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. Still, for a five-parameter tool with zero schema documentation the description leaves gaps: report_id is unexplained, the relationship to audit_reassess/reports_checklist is unstated, and whether the saved report overwrites or appends is unclear.

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 largely succeeds: it enumerates the query_mode values (auto/legacy/batch), the auto threshold, and the case-sensitive glob semantics for the three exclude_* lists. The report_id parameter is never mentioned at all despite having a 'latest' default, leaving one of five params 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?

States a specific verb and resource pair ('Query OSV for inventoried package versions') plus a second effect ('save a reassessed report'), which is more than a restatement of the name. However it never distinguishes itself from closely related siblings such as audit_reassess or reports_checklist, so the agent must infer the boundary.

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

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

The description gives conditional guidance for the query_mode parameter ('auto batches above 100 packages'), which implicitly tells the agent which mode to pick. It never states when to call dependency_check instead of a sibling like audit_reassess, and no prerequisites (e.g. an existing report or inventory) are named.

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 usefully discloses that refresh=true mutates state by fetching the official CNA record into a cache, which explains the otherwise surprising readOnlyHint=false on a tool whose description starts with "Read". It does not cover error behavior for unknown CVE IDs or rate limits, so it falls short of 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 front-loaded sentence with the primary action first and the optional flag's effect second. No filler, no redundancy, instantly 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?

An output schema exists, so return values need not be described, and the non-obvious cache side effect of refresh is covered. The remaining gap is the accepted format/validation of cve_id, which an agent should not have to guess.

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. It explains refresh (fetches the CNA record into cache) but says nothing about cve_id format (e.g. CVE-YYYY-NNNN) or whether an unknown ID is an error, leaving one of two parameters 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?

States a specific verb+resource ("Read an exact CVE") and the word "exact" implicitly distinguishes it from the lookup-by-query sibling intelligence_search. It is clear what the tool does, but it never names the sibling it differs from, so differentiation is inferred 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 only implied: "exact CVE" suggests this is the direct-ID path versus intelligence_search, and refresh=true is given a condition, but there is no explicit "use this when / use X instead" guidance and no statement of when to set refresh.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description reinforces locality by stating results are cached and that no network call is made, which tells the agent results may be stale, but adds nothing about latency, cache-freshness, or rate 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?

Two short sentences, zero padding, with the primary action and the key constraint (no network) front-loaded. 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?

An output schema exists, so return values need not be documented, and annotations cover the safety profile. The remaining gap is query semantics and result-set control, which are undocumented in both the description and the 0%-coverage schema for a search tool.

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

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

Schema description coverage is 0% for both parameters: 'query' and 'limit' have no descriptions, defaults, or accepted formats. The description does not explain query syntax (CVE ID vs free text) or what limit controls, leaving the agent with no semantic guidance where the schema fails to provide any.

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 (cached CVEs and OWASP tests) plus the provenance angle, which is more specific than a generic 'search'. It separates itself from intelligence_sync by implying local cached data, though it never names the sibling tools it competes with.

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?

'Search cached CVEs and OWASP tests' plus 'Does not contact the network' implies this is the offline/local lookup option versus intelligence_sync, which presumably refreshes data. However, no explicit when-to-use or when-to-prefer-intelligence_get guidance is given, 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the agent knows this reaches external sources and mutates local state without being destructive. The description usefully adds that it updates a local cache and reports per-source failures plus scope, but omits whether the sync is blocking, whether it overwrites existing cached advisories, and any auth or rate-limit constraints.

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 with no filler, and the primary action is front-loaded ahead of the return-value note. It is efficient, though 'scope' is left unexplained and reads as an afterthought.

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 restated, and the description does gesture at per-source failures. However, for a non-read-only tool with an open-world dependency and two completely undocumented parameters, the definition leaves too much unstated to call it complete.

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

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

Schema description coverage is 0% and neither of the two parameters is described in the schema. The description never mentions 'limit' or 'sources', so an agent gets no help understanding what limit bounds or what source identifiers are valid — a real gap for a tool whose only inputs are these two fields.

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 (fetch + update local cache) and a concrete resource (official public mobile advisories), which separates it from read-only siblings like intelligence_get and intelligence_search. It stops short of explicitly naming those siblings as the non-sync alternatives, so it is clear but not fully differentiated.

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 guidance on when to run a sync versus calling intelligence_search or intelligence_get directly, no mention of prerequisites, freshness needs, or how often it should be invoked. The agent must infer the trigger condition entirely from the name.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about timing. The description adds that this is a *request* (not synchronous) and that the job reaches a terminal state observable via jobs_status — genuinely useful context beyond the annotations. It stops short of noting reversibility or permission requirements.

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

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

One sentence, front-loaded with the action and followed by the essential next step. 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?

Output schema exists, so return values need not be explained, and the async workflow is conveyed. For a mutation tool with no explicit permission or reversibility notes, a small gap remains.

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% for the single job_id parameter, so the schema gives no semantic help. The description only implies through 'authorized job' that the id must belong to a job the caller is permitted to cancel, adding minimal meaning.

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

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

States a specific verb and resource ('Request cancellation of an authorized job') and implicitly contrasts with the polling tool it names, jobs_status. It doesn't distinguish itself from other job-related siblings like jobs_list, but the action 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?

Provides clear follow-up guidance: 'poll jobs_status until terminal,' which tells the agent this is asynchronous and how to complete the workflow. It does not state when cancellation is inappropriate (e.g., already-terminal jobs) or name any exclusion.

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 presents a pure enumeration operation ('List background jobs'), while the annotations declare readOnlyHint=false, meaning the tool is not guaranteed to be side-effect free. The description offers no explanation of what non-read-only behavior occurs, and no pagination or ordering behavior is 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?

One short, front-loaded sentence with no filler, so it reads cleanly. It is terse to the point of under-specification, but there is no wasted or redundant text to penalize.

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

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

With an output schema present, return values need not be explained, and the tool's complexity is low (one optional parameter). However, the limit/pagination semantics and the tension with the non-read-only annotation leave real gaps 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% and the single 'limit' parameter (default 20) is never mentioned in the description, so its meaning, range, and pagination implications are undocumented anywhere. The description does not compensate for the coverage 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 (List) and resource (background jobs) plus a scoping qualifier ('visible inside this server's configured roots'), which is more than a tautology. It does not explicitly distinguish itself from siblings jobs_status and jobs_cancel, but the verb choice makes the read/enumerate role inferable.

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 'inside this server's configured roots' implies the context in which listing makes sense, but there is no explicit when-to-use guidance and no mention of the sibling alternatives jobs_status or jobs_cancel for inspecting or cancelling a specific job.

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 asserts a pure read operation ("Read durable job state and progress"), but the annotations declare readOnlyHint=false, meaning the tool may modify state. That is a direct contradiction of the behavioral claim in the text. The remaining sentence adds no concrete behavior such as polling cadence, terminal state semantics, or error conditions.

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, front-loaded with the action, which is good. The second sentence is atmospheric and ambiguous rather than informative, so it does not clearly earn its place in a definition this terse.

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, but for a job-polling tool the description omits the essential context: how the job_id is obtained, how to interpret completion vs. failure, and how this differs from jobs_list. Combined with the annotation contradiction, this leaves the agent under-informed.

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 the single job_id parameter, and the description says nothing about its format, or where the id comes from (presumably audit_start or jobs_list). The name is largely self-explanatory, which prevents a 1, but the description does nothing to compensate for the missing schema documentation.

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?

"Read durable job state and progress" states a specific verb (Read) and resource (job state/progress), so the core purpose is unambiguous. It does not, however, distinguish itself from sibling job tools such as jobs_list or jobs_cancel, leaving the agent to infer the boundary from the name alone.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative guidance. The agent must infer that this is called after audit_start to poll a job, and the cryptic line "an interrupted worker never becomes a successful audit" reads as an aphorism rather than a usage rule. None of jobs_list, jobs_cancel, or audit_scan are referenced as 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the 'without changing reports' clause largely restates structured data. What the description does add is the scope of evaluation (thresholds, coverage requirements, waivers), which is genuine behavioral context the annotations do not carry. It omits what happens on an invalid policy file or what a failed evaluation looks like.

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

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

One compact sentence with the subject matter front-loaded and no filler. Minor deduction because the trailing 'without changing reports' clause repeats what the annotations already assert, spending words on 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?

An output schema exists, so return values need not be documented, but for a five-parameter tool with 0% schema coverage and no routing guidance the description is materially incomplete. An agent cannot determine how baseline selection works or when this tool should be chosen over its many validation-adjacent 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% across five parameters, and the description addresses none of them. The baseline_id / baseline_path / baseline_sha256 trio is genuinely ambiguous (identifier vs. file vs. integrity hash) and the required policy_path is never explained, so the description fails to compensate for the coverage gap.

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

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

The description gives a specific verb (evaluate) plus the concrete subject matter being evaluated: team thresholds, explicit coverage requirements, and expiring waivers. That is far more informative than a name restatement. It does not, however, distinguish this from plausible siblings such as specs_validate, verify_finding, or audit_scan, so it stops 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?

There is no statement of when to reach for policy_evaluate versus specs_validate, verify_finding, or audit_scan, and no preconditions or exclusions are given. The only usage-flavored clause ('without changing reports') is a safety property, not routing 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 this as a safe, idempotent, closed-world read. The description adds genuinely new behavioral context: the set of possible statuses and the crucial semantic caveat that 'none is a pass', which prevents the agent from misreading the output. It stops short of describing scoping or pagination, but the output schema covers 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?

Front-loaded with the action, then the checklist options, then the status taxonomy. Dense but essentially waste-free; the status clause is long but carries real semantic payload.

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 output schema means return values need not be explained, and checklist sources plus statuses are covered. However, for a tool sitting among eleven reports_* siblings, the absence of selection guidance and of report_id semantics leaves notable 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 carries extra weight. It does explain the 'checklist' parameter's accepted values (masvs-v2 or a TOML path) and what those checklists contain, but says nothing about 'report_id' or how the 'latest' default resolves, leaving one of two parameters semantically 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+resource ('Map a report onto a checklist') and enumerates the checklist sources (built-in masvs-v2 or a TOML file under an MCP root). That is clear enough to act on, but it does not contrast itself against siblings like reports_get or reports_compare, which also consume a report.

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

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

There is no when-to-use or when-not-to-use guidance. The agent is not told when checklist mapping is preferable to reports_get, reports_compare, or reports_history, so selection among the many reports_* siblings must be inferred from the name alone.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, yet the description adds substantive behavior: coverage differences are retained, remediation states are only reported as proven/unproven, disappearance of a finding never proves remediation, and binary/runtime bindings stay strict. That is meaningful disclosure beyond the annotations, though terms like "scope/build/assertion pairing" remain opaque.

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 the first clause, and little is pure filler, but the middle sentence is a dense run-on of jargon ("scope/build/assertion pairing," "identical, complete canonical SHA256 source inputs") that is hard to parse on first read. Length is justified by tool complexity, but structure could be cleaner.

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 and annotations cover safety, so return values and side effects need not be spelled out. However, for a comparison tool with conditional verification modes, terms like "unproven remediation states" and the scope-matching rule are left under-defined, and nothing says what happens on mismatched or invalid report IDs.

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, and it does: before/after are identified as "exact report IDs," and both booleans are explained along with their dependency (portable_inputs requires verification) and the narrow condition under which absolute targets are normalized. It stops short of describing ID format or provenance, 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 and resource ("Compare exact report IDs") and pins the scope to exact IDs, which implicitly separates it from fuzzy or historical lookups like reports_history or reports_get. It is clear what the tool does, though it never names a sibling or contrasts behavior 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?

Gives conditional guidance for the two flags ("verification=true adds source traces", "portable_inputs=true requires verification"), which helps pick a mode. It never says when to use this tool versus reports_get/reports_history, nor states prerequisites such as how to obtain valid report IDs, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety profile is partly covered. The description adds meaningful context beyond that: approval must be genuine and pre-existing, output is confined to configured roots, and the return includes an artifact hash meant to be pinned in reviewed CI — implying integrity/auth requirements not captured by annotations.

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

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

Two compact sentences with the core purpose front-loaded and the guardrail second. Nothing is wasted, though the terseness leaves gaps rather than trimming redundancy.

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

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

An output schema exists so return values needn't be described, and the description covers the key approval/integrity concerns. But with 0% param coverage on a 4-required-param mutation tool and no differentiation from siblings, it is only partially complete for the task.

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% with 4 required params, so the description carries the full burden. 'Inside configured roots' hints that output_path is constrained and 'Do not invent approval' loosely gestures at approved_by/approval_reference, but no format, origin, or expected value for report_id or the approval fields is given, leaving most parameter semantics 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?

States a specific verb (Export) and resource (an explicitly approved baseline), with an added scoping condition (inside configured roots). It is clear what the tool does, but it never distinguishes itself from the many reports_* siblings (reports_get, reports_list, reports_compare), so an agent must infer the difference.

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 actionable constraint guidance ('Do not invent approval', 'pin the returned artifact hash in reviewed CI configuration'), which implies the intended workflow. However, it offers no explicit when-to-use/when-not or naming of alternative tools among the many reports_* 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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds some useful behavior beyond that: immutable report_id continuation, finding_id evidence paging, and that oversized records remain in local exports rather than being returned.

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 short sentences with no filler, and the pagination continuation is stated up front after the opening purpose sentence. The terseness and jargon ('bounded context pages') slightly hurt immediate clarity, but the structure is efficient.

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

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

This is an 8-parameter tool with 0% schema description coverage and no annotations explaining parameter roles. Although an output schema exists, the description does not explain the pagination/filter parameters or when to use it over sibling report tools, so it is incomplete for the tool's complexity.

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

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

Schema description coverage is 0% for all 8 parameters, so the description must compensate but does not. It gives only partial meaning for report_id and finding_id and leaves limit, cursor, status, section, severity, and max_bytes 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?

The description gives a verb, 'Read,' and a vague object, 'bounded context pages,' then later names report_id and finding_id/evidence. It never plainly states that it retrieves report or finding data, and it does not distinguish itself from siblings such as reports_list or reports_history.

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 implies pagination continuation by saying to keep using the returned immutable report_id and that finding_id pages its evidence. However, it provides no explicit when-to-use alternatives or when-not-to-use guidance relative to the many reports_* 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine semantic context beyond that: the caveat that an unobserved finding is not proof of remediation unless the same checks completed, which steers interpretation of the result.

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

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

Two sentences: the first front-loads what is returned, the second delivers a decisive interpretation caveat. No filler, and the most important constraint is not buried.

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 need not be explained. However, for a tool in a dense reports_* family, the description omits how it differs from reports_compare/reports_get and leaves the 'target' identifier ambiguous, so an agent still lacks enough to call it confidently.

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 the single 'target' parameter, so the schema does not help. The description only implies scope via 'one target' and adds no format or identifier guidance (ID, name, URL?). Marginally informative but not compensating for the coverage 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 resource and scope: first/last observation of each finding across saved reports of one target. This is a clear verb-resource statement, but it never distinguishes itself from siblings like reports_compare or reports_get, which an agent must disambiguate before choosing.

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 'for inspection and remediation records' implies intended usage, but there is no explicit when-to-use, when-not-to-use, or named alternative tool. Given four sibling reports_* tools, the routing guidance is thin.

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

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

Annotations only cover the safety profile (write, non-destructive, closed-world). The description goes well beyond them: imported results stay candidates with origin external, add no APSA coverage, are linked to APSA findings of a related weakness at the same location, and that result text is untrusted data. This is rich, non-obvious 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?

A single front-loaded paragraph that begins with the action and then adds constraints. Dense but earns its sentences; could benefit from slight separation of the security note but is 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?

An output schema exists, so return values need not be described, and the behavioral effects are well covered. However, for a write tool with 0% parameter coverage, the meaning and format of path, tool, and sarif_root are left entirely 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?

Schema description coverage is 0% across 4 parameters. The description only implicitly references report_id as the source for the new report and says nothing about path, tool, or the sarif_root default, leaving most parameters 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?

States a specific verb and resource: import SARIF 2.1.0 results into a new report derived from report_id. Names concrete source tool examples (Android Lint, CodeQL, Semgrep) and clearly distinguishes this ingestion action from sibling read/list/compare 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?

The context of when this applies (importing an external tool's SARIF output) is implied and the examples aid recognition, but there is no explicit when-to-use guidance relative to siblings like reports_get or reports_history, and no stated prerequisites or exclusions.

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 completely (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is low. The description adds the content type of the result ('saved audit IDs'), but says nothing about pagination or ordering despite the presence of a limit parameter with default 20.

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 short sentence with the action front-loaded and no filler. It is efficient, though its brevity shades into under-specification rather than tightness.

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

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

With an output schema present, return-value shape needn't be explained, and annotations cover safety. However, for a listing tool whose entire purpose is paging through IDs, the missing explanation of the limit parameter and pagination behavior leaves a real 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?

There is one parameter (limit) with 0% schema description coverage, so the description must carry the burden and does not mention it at all. It gives no hint about paging, default page size, or how many IDs are returned per call.

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

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

States a specific verb (List) and a specific resource (saved audit IDs), so an agent immediately knows this is a discovery/enumeration tool. It implicitly distinguishes itself from reports_get and reports_history by framing its output as IDs 'for exact follow-up reads,' though it never names those siblings 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 'for exact follow-up reads' implies the workflow (list first, then fetch precisely), but there is no explicit when-to-use versus reports_history / reports_get / reports_export_baseline, and no stated preconditions. Usage is inferable rather than directed.

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, covering the safety profile. The description's 'without changing app state' largely restates readOnlyHint rather than adding new behavioral context like environment prerequisites or discovery scope.

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 that states the action and its resources with no filler. 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. For a zero-parameter discovery tool the description is sufficient, with only minor room to note environment or prerequisite 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies for a parameterless tool.

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 (List) and two concrete resources (adb devices, iOS simulators). It is unambiguous about what the tool returns, though it does not explicitly contrast itself with its sibling runtime_plan.

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

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

There is no explicit statement of when to use this tool versus alternatives such as runtime_plan. The phrase 'without changing app state' hints at a safe-discovery context but is not framed as 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 the safety profile is covered. The description adds genuine value by clarifying that generation does not execute the scenario or log out the app, but it omits permissions required, what the generated plan contains, and whether the report_id source affects the output.

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

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

Two short sentences with no filler, and the core action is front-loaded ahead of the negative constraint. It is efficient, though the second sentence is a caveat rather than a positive usage signal.

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 presence of an output schema means return values need not be explained, which lowers the burden. Still, with three fully undocumented parameters and only an abstract artifact noun, an agent lacks enough to call this correctly or to select it confidently over execution-oriented 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%, so the description carries the full burden for package, platform, and report_id — and it supplies none of them. The only implicit hint is the report_id default of "latest"; what package or platform accept, and how they shape the generated scenario, is entirely 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?

States a specific verb and artifact ("Generate an editable test scenario"), which distinguishes it from execution-oriented siblings like audit_start or runtime_devices. However, "test scenario" remains somewhat abstract and the description never names an alternative tool, so the differentiation is implicit rather than explicit.

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?

"Does not run it or log out the app automatically" implies this is a planning/authoring step rather than an execution step, which gives the agent a usable context cue. But it names no alternatives and states no when-to-use condition relative to siblings like audit_start or runtime_devices, so guidance is only implied.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds real behavioral context beyond that: it explains the source/sink content model and, importantly, that proposed specs require human review before findings are baselined.

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 scoped tightly to format, semantics, and the review gate. Dense and mostly waste-free, though the middle sentence about sources/sinks is somewhat compressed and the final governance sentence could arguably be split or trimmed.

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

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

An output schema exists, so return/validation-result structure need not be explained here. The description covers purpose, accepted format and version, the source/sink model, and the downstream review workflow; the remaining gap is the ambiguity of the path parameter.

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

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

There is a single required parameter (path) with 0% schema description coverage, so the description carries the burden. The description implies the path targets a project taint specification, but never states whether it is a file path, directory, or project root, nor acceptable extensions, leaving the parameter under-specified.

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 (validate a project taint specification), pins the accepted formats and version (TOML/JSON, version = 1), and ties the tool to the sibling it feeds (audit_scan), so an agent can place it precisely 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?

It gives a clear use context: validate before audit_scan consumes the spec, and proposed specifications must pass human review before their findings enter a baseline. It stops short of naming explicit alternatives or when-not-to-use conditions, so it is strong context rather than full routing guidance.

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

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

Adds real behavior beyond the annotations: the default-to-latest-report rule, the fact that rescan writes a new saved report (consistent with readOnlyHint=false), the full enumerated verdict set, and the crucial semantic 'APSA never refutes a claim.' No permission/rate-limit context is given, so it is not a full 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?

Front-loaded with the purpose, then inputs, then report behavior, then verdict values. Dense but each clause carries information; the long verdict enumeration is the only mildly costly element.

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 verification tool with an output schema already covering return values, the description supplies everything else an agent needs: accepted identifier forms, report/report_id/rescan interaction, and the meaning of every possible verdict 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?

Schema description coverage is 0% across 7 parameters, so the description must carry semantics and largely does: it maps rule/weakness to accepted ID formats, describes path plus line as an optional locator, and explains report_id and rescan. Target formatting and the exact difference between rule and weakness inputs remain slightly under-specified.

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 (cross-check) and resource (a mobile finding claimed elsewhere) against a named evidence source for a named target. The parenthetical example of an AI code reviewer makes the scenario concrete, and no sibling tool (reports_*, audit_*, intelligence_*) does this, so an agent can differentiate it 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?

Explains the input contract (MASWE-NNNN or CWE-N weakness or APSA rule ID, optionally path/line) and the report-selection rule (latest report unless report_id is given; rescan=true scans first and saves). It does not name an alternative tool or state when not to use this one, so it stops short of explicit routing.

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