FSV

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

No annotations exist, so the description carries the full burden, and it does disclose the diff categories returned, the risk-score delta, the improved/regressed verdict, and that triaged-away findings are excluded to avoid false-positive skew. It never states that this is a non-mutating analysis operation or whether the two scans must share a target/scan profile, which is the remaining material gap.

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

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

Two sentences, front-loaded with the action and its inputs, then the return contents and the exclusion rule. Every clause adds information; nothing is redundant with the schema or title.

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

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

An output schema exists, so the description is not obliged to enumerate return fields, yet it usefully names the verdict categories anyway. For a two-param read-style analysis tool with no annotations, the main thing still missing is any statement about preconditions or comparability of the two scans.

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 both parameters (baseline_id, current_id) are bare strings, so the description must compensate. It references 'scan_id' generically and the before-vs-after framing loosely maps 'before' to baseline and 'after' to current, but it never explicitly binds baseline_id to the older scan or states whether the IDs must be from comparable targets.

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

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

The description states a specific verb and resource ('Compare two scans by scan_id') and immediately characterizes the output: resolved, new, persisting findings plus a risk-score delta and a verdict. That is far more discriminating than any sibling, which are scan/check/list/triage operations rather than pairwise comparison.

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?

'e.g. before vs after a fix' gives a concrete usage scenario, and the exclusion of triaged-away findings flags a meaningful filtering behavior. It does not name alternatives such as fsv_target_trend or fsv_list_scans, so there is no explicit when-not routing, which keeps it out of the 5 tier.

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 load and does disclose non-obvious behavior: only actually-found issues produce a snippet, and CSP is emitted report-only rather than enforced. It never explicitly states that the tool is read-only/non-mutating or what access prerequisites apply, which is the remaining gap for an unannotated tool.

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

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

Two sentences, front-loaded with the verb and resource, then constrained by platform values and output rules. Every clause carries information: platform list, per-issue emission, report-only CSP, and the user-facing follow-up.

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 shape need not be explained, and the description still covers output semantics (snippets only for found issues, report-only CSP). Missing is provenance for scan_id and whether scan ownership must be verified first (note sibling fsv_verify_ownership).

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% with no enum on 'server', so the description does critical compensating work by listing the exact five accepted values and clarifying what each emits ('express' means helmet/cookies, 'dns' means SPF/DMARC/CAA plus dangling-record removal). It implies scan_id must come from an existing scan but never says where to obtain one.

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 transformation ('turn a scan's findings into paste-ready remediation') plus an explicit scope of one platform, and enumerates the accepted platform values. An agent can distinguish it from fsv_scan (which finds issues) and fsv_get_report (which reports them) without opening a schema.

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

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

Gives concrete follow-through guidance — 'show the user the snippets and remind them to test on staging' — which frames the correct usage context. It stops short of naming alternatives or stating when not to use it (e.g., versus fsv_triage or fsv_get_report), so exclusions are absent.

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

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

With no annotations, the description carries the full behavioral burden. It usefully signals that the scan must be "completed" and clarifies that html is self-contained and sarif targets CI, but it says nothing about what happens on an incomplete/unknown scan_id, whether output is size-limited, or that this is a read-only retrieval.

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

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

A single sentence, front-loaded with the action and resource, followed by a terse enumeration where each item contributes a valid value absent from the schema. No filler or repetition.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the format enumeration covers the main ambiguity. The remaining gap is practical: the agent is never told where a scan_id comes from (e.g., fsv_list_scans) or what failure looks like for an incomplete scan.

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 format field has no enum in the schema, so the exhaustive value list with per-value meaning and the stated default ("md") adds real value that the schema cannot provide. The scan_id parameter, however, is left entirely undocumented — no mention of what it is or how to obtain it.

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 ("Get a formatted report") plus the precondition ("for a completed scan"), which is enough to distinguish it from fsv_scan and fsv_list_scans. It does not explicitly name a sibling or say where scan_id comes from, so it stops just short of full differentiation.

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

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

Usage is only implied: the reader infers the tool applies to already-completed scans and infers format choice from the parenthetical hints ("for CI/code-scanning"). There is no explicit when-to-use/when-not statement and no pointer to alternatives such as fsv_fixes for remediation output.

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

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

With no annotations, the description carries the full burden, and it does signal a pure read operation ('List all') with no mutation implied. It also discloses the shape of the content returned (category, scope, checks, profiles). It stops short of saying the enumeration is complete/static or that no auth or targeting is required, but for a zero-argument listing call the remaining risk is low.

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

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

A single dense sentence that front-loads the verb and resource, then lists the payload in priority order. No filler, no restatement of the tool name.

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

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

For a zero-param tool with an output schema, the description only needs to establish what the catalog contains, which it does thoroughly. The one missed opportunity is a forward pointer that module/profile identifiers from this call feed into fsv_scan, which would complete the workflow story.

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

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

The schema has zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. The description correctly spends no words on arguments.

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

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

Specific verb ('List') plus resource ('FSV scan modules') with the exact fields returned enumerated: category (passive/active), scope (site/url), what each checks, and scan profiles. That level of detail makes it unmistakably the catalog/discovery tool, distinct from the action-oriented siblings like fsv_scan, fsv_waf_check, and fsv_get_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?

The tool's role as a static catalog is implied by 'list all ... plus the available scan profiles', which tells an agent this is where module and profile names come from. However, it never states when to reach for it versus fsv_scan or fsv_quick_check, nor that it should be called first to discover valid module/profile values.

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; it partially does by disclosing the returned fields, which implies a safe read. It says nothing about ordering (newest first?), what 'recent' means, whether results are truncated, or pagination behavior for the default limit of 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?

Two tight sentences with the core capability front-loaded and the optional filter second. Nothing is wasted, though the space saved could have been spent on the undocumented limit 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-value explanation is not required. Still, for a listing tool with zero annotation coverage and 0% schema description coverage, the description should cover ordering, default limit behavior, and when to use siblings; those gaps keep it at minimum viable.

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 compensate. It usefully specifies that 'target' is a host substring match (a real semantic addition the schema lacks), but it never mentions the 'limit' parameter or its default of 20, leaving one of two 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 ('List') and resource ('recent scans') and enumerates the returned fields (IDs, targets, status, risk grade, finding counts). It implicitly separates itself from the scan-launching sibling fsv_scan, but never names alternatives such as fsv_scan_stats or fsv_get_report to sharpen the boundary.

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

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

The only usage cue is 'Optionally filter by target host substring'; there is no statement of when to prefer this over fsv_scan, fsv_get_report, fsv_scan_stats or fsv_target_trend. An agent must infer that this is the browsing/lookup entry point.

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

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

With no annotations provided, the description carries the behavioral burden well: it explicitly says no payloads are sent, calls the check passive and safe, and requires authorized=true after user confirmation. It does not discuss rate limits, result retention, or other operational details, but the core safety and authorization 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?

The description is front-loaded with the core purpose and safety profile, then lists the checks efficiently. Every sentence contributes useful scope or usage information, and the authorization instruction is placed clearly at the end.

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

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

Given the presence of an output schema, the description need not explain return values, and it covers the key behavioral and authorization context for a passive security check. It is nearly complete, though it could more explicitly scope when this tool is preferable to active-scan 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 must compensate for both parameters. It explains that target is a single URL and clarifies the authorization condition for authorized=true, adding meaningful semantics beyond the bare schema. It does not specify URL format or validation details, which is a minor gap.

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

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

The description states a specific verb and resource: a fast, passive check of a single URL. It also enumerates the checks performed, making the tool's scope clear. It does not explicitly name or differentiate itself from siblings such as fsv_scan or fsv_waf_check, which keeps it from 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?

It gives clear usage context with 'Safe for a first look' and specifies the authorization prerequisite for the authorized parameter. It does not explicitly state when not to use it or name alternative sibling tools, so it falls short of full when/when-not/alternatives 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?

With no annotations, the description carries the full burden and does so well: it discloses that aggressive mode raises rate/concurrency, that the scan is time-boxed by max_minutes with partial results kept, that the crawl skips logout/asset links, that ct_logs sends the domain to a third party (crt.sh) and requires consent, and that authenticated scanning should use a test account. These are the exact behavioral facts an agent needs and that structured fields do not 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?

The description is front-loaded with the core action and the profile enum, and nearly every clause adds a fact an agent needs (consent for crt.sh, time-boxing, authorization). It is a dense single block, though, and the parameter notes would read better as a short list than as an inline stream of clauses.

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

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

This is a complex 14-parameter, potentially intrusive scanning tool with no annotations; the description covers authorization, third-party data exposure, time-boxing, and mutating scan behavior, and an output schema exists so return values need not be detailed. The main gap is that module selection and the crawl/depth/max_urls limits are left entirely to the schema titles.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does: it explains profile values and default, max_minutes default and partial-results behavior, use_ct_logs' third-party implication, allow_external's effect, seed_urls' role, and the headers/cookies authentication intent. It leaves crawl, depth, max_urls, modules and exclude_paths undocumented (notably module names are never explained or pointed to fsv_list_modules).

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

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

The description opens with a specific verb and resource: 'Run a web vulnerability scan against a target URL', then specifies what the scan does (crawl same-origin, run modules by profile). This is clearly a full scan rather than a quick check or WAF check, but the description never explicitly names the sibling tools (fsv_quick_check, fsv_waf_check) to route the agent. Solid but no explicit sibling differentiation.

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

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

It gives clear when-to-use guidance for each profile ('passive' sends no payloads vs 'balanced' adds active checks vs 'aggressive' higher concurrency), for use_ct_logs (only with user consent), for allow_external, and for headers/cookies (authenticated scan with a test account). It also states the authorization precondition and that authorized=true should only be passed after confirmation. It does not explicitly say when to prefer a sibling tool like fsv_quick_check instead, so 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 behavioral burden. It implies a read-only operation and lists returned metrics, but says nothing about whether the scan must be finished, what happens with an invalid or in-progress scan_id, whether data is cached or live, or any 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?

A single front-loaded sentence with the verb and resource first and the metric list parenthetically appended. There is no filler and nothing redundant.

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

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

An output schema exists, so the return shape need not be explained, and the metric enumeration aligns with it. However, for a tool that hinges on a scan_id, the missing guidance on sourcing that identifier and on scan-state preconditions 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?

Schema description coverage is 0% and the single required parameter, scan_id, is completely undocumented. The description does not explain the expected format or, more importantly, where the agent obtains a scan_id (presumably from fsv_scan or fsv_list_scans). With low coverage the description should compensate, and it does not.

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 ('Get the HTTP statistics of a scan') and enumerates the metrics returned, which lets an agent distinguish it from fsv_list_scans or fsv_get_report. It stops short of explicitly naming which sibling to use instead, but the resource specificity is strong.

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 use this tool versus fsv_get_report, fsv_compare_scans, or fsv_target_trend, and no preconditions (e.g., that the scan must exist or be complete). The agent must infer usage entirely from the name and metric list.

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

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

With no annotations, the description carries the full burden, and it does disclose one real behavioral trait: results come back in chronological order ('oldest first'). It never confirms the operation is read-only, and says nothing about how many points are returned or how the limit interacts with history depth.

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 resource and the ordering rule, with the motivating use case trailing. Every clause carries information; nothing is padded.

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

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

An output schema exists, so return-value explanation is not needed, and the ordering note covers the main surprise an agent would hit. The remaining gap is parameter-level guidance given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It only weakly implies that 'target' is a host and that history is bounded, but never states the accepted identifier format for target or what limit actually caps (number of scans returned vs. returned rows).

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 ('Show the risk-score trend for a host across its scan history') plus a notable ordering constraint ('oldest first'). It implicitly separates itself from siblings like fsv_compare_scans and fsv_scan_stats, but 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?

The clause 'useful for reporting whether a site's posture is improving over time' gives a concrete motivating scenario, which is better than nothing. However, there is no when-not guidance, no prerequisites, and no pointer to which sibling to use for a point-in-time or multi-host comparison.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the triage decision persists across future scans, that 'open' clears it, and that several statuses are excluded from the risk score, which gives useful mutation context; it does not discuss permissions or conflict 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?

The description is compact and front-loaded: it starts with the core action and persistence behavior, then gives status semantics, then finding identification. Every sentence contributes useful information without redundant restatement.

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

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

Given that an output schema exists, the description need not explain return values, and it covers the main operational semantics well. It is slightly incomplete because the optional note parameter and exact scan_id role are not described, but overall it is sufficient for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds strong meaning for 'status' by listing allowed values and effects, and for 'finding' by noting id or fingerprint identification, but it does not document the optional 'note' parameter or explicitly clarify 'scan_id'.

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: record a triage decision for a finding, and it explains that the decision persists across future scans. That is much clearer than a generic update tool, though it does not explicitly distinguish this from sibling tools such as fsv_fixes or fsv_scan.

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

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

The description implies usage by saying the finding is identified from a scan result and by explaining status effects, but it does not explicitly state when to use this tool versus alternatives like fsv_fixes. It provides context without clear when-to-use or when-not-to-use guidance.

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

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

With no annotations, the description carries the burden well: it discloses the gating precondition, that check=false is a read-only instruction-producing call, and that check=true has a side effect ("records the proof"). It does not cover failure behavior (e.g., what happens if the record is absent or not yet propagated) or any 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?

Two sentences, zero filler, with the purpose and gating condition front-loaded before the mode breakdown. Every clause carries information the schema does not.

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; the description instead supplies exactly the missing pieces — the deployment gating and the two-call workflow. Nothing critical for a correct invocation is absent.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains the semantics of both check values (publish-then-verify) rather than just echoing the names. The host parameter is only inferable from context and never explicitly described as the target being proved.

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?

"Prove control of a host" is a specific verb+resource, and the description immediately situates it as a precondition for payload-sending scans, which separates it from sibling scan/report tools like fsv_scan and fsv_get_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?

It states the triggering condition explicitly (FSV_REQUIRE_VERIFICATION=1) and describes the two-step workflow via the check flag, so an agent knows when this tool is required. It stops short of naming a when-not case or pointing to a sibling for the case where no verification is needed.

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, and it does disclose the essential traits: passive (non-intrusive), a single request (low footprint), and an explicit authorization precondition tied to user confirmation. It does not mention logging/detectability or failure behavior, but the safety-relevant profile is conveyed.

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, front-loaded with the capability, followed by the operational profile and the authorization instruction. 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?

An output schema exists so return values needn't be explained, and the authorization prerequisite — the main risk in invoking this tool — is covered. The only material gap is target format, which matters for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'authorized' parameter well ('after the user confirms'), giving the semantic trigger for setting it. However, 'target' gets no format guidance (URL vs. hostname, scheme handling), leaving half the parameters 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 ('Detect') and resource ('whether a target sits behind a WAF or CDN'), and enumerates concrete vendors so the agent knows exactly what signal it produces. No sibling tool in the list covers WAF/CDN fingerprinting, so it is clearly 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?

Gives the key gating condition ('Pass authorized=true after the user confirms') and characterizes the call as 'Passive, single request,' which tells the agent when this is appropriate versus heavier tools like fsv_scan. It stops short of explicitly naming alternatives such as fsv_quick_check, so no exclusion guidance.

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