SecScan

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

With only openWorldHint in the annotations, the description carries the disclosure burden and does well: it warns that a full baseline scan runs immediately and consumes one of the user's scans. It stops short of stating any ownership/verification requirement or whether monitoring can be removed, but the quota side-effect disclosure is meaningfully beyond the annotations.

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

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

Two sentences, front-loaded with the core action, then the side-effect and return-value facts. No filler or repetition of the 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?

No output schema exists, so the description correctly closes the loop by naming the return value (scan_id) and the follow-up tool (get_scan_status). Combined with the quota warning, an agent has everything needed to call this correctly and set expectations.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents url, its length bounds and format example. The description adds no additional syntax or constraint detail, which is the expected baseline when the schema does the work.

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 ('put a site under continuous monitoring') and enumerates the concrete capabilities: hourly uptime checks, CVE matching, certificate alerts, rescans. It implicitly separates itself from the one-off sibling scan_url via 'continuous', but never names the sibling, so the differentiation is inferable 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?

It states a prerequisite ('a site the user owns') and the cost condition ('free for plan holders'), which is useful. However, it gives no explicit guidance on when to choose this over scan_url or monitor_scan_now, so usage context 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 idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it explains the success semantics (domain becomes verified, next scan includes active tests) and the eventual-consistency caveat that DNS changes can take a few minutes, which an agent needs to interpret a negative 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?

Three short sentences, zero waste, front-loaded with the core action before the outcome and timing notes. Every sentence earns its place.

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

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

With no output schema, the description correctly compensates by explaining what a successful result means and why a negative result may be transient. For a single-param, idempotent check tool, nothing essential is missing.

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

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

Schema coverage is 100% and the single parameter is already documented as 'The domain passed to start_domain_verification'. The description reinforces that linkage but adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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 (check) and resource (domain verification) and explicitly frames it as the follow-up to start_domain_verification, distinguishing it from that sibling and from list_verified_domains. An agent can tell exactly what it does without opening the schema.

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

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

It clearly situates the tool in the flow by tying it to start_domain_verification (checking the file/DNS record that action produced), which tells the agent when to invoke it. It stops short of explicit when-not guidance, but the sequencing context is unambiguous.

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

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

Annotations only carry destructiveHint=true; the description adds real context beyond that: the effect is persistent across future scans and scoped to this site, and the action is undoable (in the app). It doesn't state auth/permission requirements, but the suppression semantics and reversibility are valuable disclosures.

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 core effect followed by the safety constraint. Every clause earns its place with no filler.

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

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

For a simple two-parameter mutation tool with no output schema, the description covers purpose, persistent effect, scope, reversibility, and the critical when-not-to-use guard. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so scan_id and finding_name are fully documented in the schema itself. The description adds no per-parameter syntax beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Mark a finding as a false positive for this site') and the concrete consequence ('future scans of it stop reporting it'). It is clearly distinguishable from siblings like get_report or scan_url.

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

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

Explicit when-to-use ('ONLY use this after the user has confirmed the finding is wrong') and when-not ('never dismiss a real problem to improve a grade'). It also anchors the behavior to the equivalent in-app action.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds useful context by enumerating what the payload contains (free vs plan scans vs credits), but says nothing about auth requirements, staleness of the quota data, or rate limits.

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 the return content front-loaded and the usage cue second. Every clause earns its place; the only minor issue is the slightly breathless dash-bounded enumeration.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the four quota components. For a zero-parameter read tool this is close to complete, though it stops short of describing units or what a zero/exhausted quota looks like.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no inputs are needed — it is a pure account-state read.

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 the resource (the user's scan quota and plan) and enumerates the returned quantities — free scans, plan scans, credits, plan. It is a clear account/quota lookup distinguishable from siblings like scan_url or list_recent_scans, though the verb is implicit ("How many...") rather than a stated action.

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?

"Check this before starting several scans" gives a concrete trigger condition, which is more than most zero-param tools offer. However, it names no alternatives and gives no threshold for what counts as "several," leaving the when-to-use decision partly 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=true, so safety is covered. The description adds beyond that: page size and ordering behaviour, the pagination mechanism, and an important interpretive caveat that a clean grade says nothing about skipped areas and the agent should say so. That caveat is genuine behavioural context not derivable from the schema.

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

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

Dense but front-loaded: report contents first, then pagination and filtering mechanics. Every sentence carries information, though the parenthetical honesty caveat briefly interrupts the flow of the field enumeration.

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 no output schema, so the description carries the return-value burden and does so by enumerating returned elements and pagination shape. It is close to complete for calling the tool correctly; only edge details like max offset behaviour or finding count metadata are 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 description coverage is 100%, so all four parameters are already documented, including the enum and default for limit. The description only adds the 'most severe first' ordering and reiterates offset/min_severity usage, so it sits at the baseline for a fully-covered schema.

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

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

States a specific verb and resource ('the finished report for a scan') and enumerates exactly what the report contains: grade, tested/skipped areas, prioritised findings with fixes and evidence, and a fix prompt. It is clearly distinguishable from siblings like get_scan_status (status vs full report) and list_recent_scans (discovery vs content).

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

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

Gives concrete operating guidance: findings paginate 25 per page most-severe-first, use offset for the next page, or min_severity to focus. It also routes the agent on scan_id provenance implicitly via the schema. It stops short of stating when NOT to call it or explicitly contrasting with sibling tools.

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

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

Annotations cover the safety profile (readOnlyHint=true), and the description adds real context: the wait_seconds mechanism blocks up to 60s and returns the full report the moment the scan finishes. It does not disclose polling/timeout failure behavior, but the added value is genuine.

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

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

Two sentences, no waste, and the state enumeration plus the wait behavior are front-loaded so an agent can decide immediately whether to wait.

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

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

With no output schema, the description usefully notes that a completed wait yields the full report, and it lists the terminal states. It could say more about what a non-complete status returns, which is the main remaining 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 100%, so both parameters are already documented, and the description largely restates the wait_seconds cap. The 'returns the full report as soon as it does' phrasing is return behavior rather than added parameter semantics, so baseline 3 is right.

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 ('Status of a scan') and enumerates the possible states (queued, scanning, analyzing, complete, failed), which makes it clearly distinguishable from siblings like get_report or list_recent_scans.

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

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

Usage is implied by the wait_seconds behavior (poll after scan_url), but the description never says when to use this rather than get_report or list_recent_scans, nor when not to wait. Adequate but no explicit 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 only declare readOnlyHint=true, and the description adds substantive behavior: the returned record fields are enumerated (grade, last/next scan, uptime, CVE alerts, new problems, cert expiry), which substitutes for the missing output schema. It does not mention pagination, ordering, or auth needs, keeping it short of a 5.

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

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

Two dense sentences with the subject front-loaded and no filler; the field enumeration carries real information given there is no output schema. The comma-separated field list is slightly dense but nothing is wasted.

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

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

For a zero-parameter read tool with no output schema, the description supplies the one thing structured data cannot: what each monitor entry contains. Missing only operational details like result ordering or pagination, which are minor here.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline for this dimension is 4. The description correctly introduces no parameter syntax or confusion.

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 the resource (sites under continuous monitoring) and enumerates exactly what each entry contains — grade, scan times, uptime, CVE alerts, findings, cert expiry. That is far more specific than the title, and the closing reference to monitor_scan_now hints at its role versus siblings, though it does not explicitly contrast with list_recent_scans or get_scan_status.

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 line 'Use the monitor id with monitor_scan_now' tells the agent what to do downstream with the returned id, which implies this is the discovery step before triggering a scan. There is no explicit statement of when to prefer this over sibling listing tools such as list_recent_scans, and no 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?

readOnlyHint=true already tells the agent this is a safe read. The description usefully adds sort order ('newest first') and returned field ('status'), but says nothing about the cap on results, default page size, or pagination behavior despite a bounded limit parameter.

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 the ordering constraint and returned field front-loaded; nothing is wasted, though it is arguably too terse given gaps elsewhere.

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

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

For a simple read-only listing tool with annotations covering safety and no output schema, the description conveys the essential shape of the result (scans with status, newest first). It stops short of covering the limit parameter's behavior, which is the only 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?

The single parameter (limit) has 0% schema description coverage, so the description carries the full burden and it never mentions limit at all — no default, no reference to the max of 25. 'Most recent' hints at a bounded window but does not explain the parameter's semantics.

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

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

States a specific resource (the user's most recent scans), what each item includes (status), and the ordering (newest first). It is distinguishable from the singular get_scan_status and from list_monitors, though it never explicitly names a sibling or a verb.

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 when-to-use guidance, no mention of when to prefer get_scan_status or list_monitors instead, and no prerequisites such as an authenticated user context. The 'recent scans' scoping is the only implicit signal.

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?

readOnlyHint=true is consistent and the description adds real context beyond the annotation: verified domains receive active testing (injection, XSS, SSRF, access control) while others get only passive checks. That behavioral distinction is not present in any structured field. It omits return shape/pagination, but for a zero-arg listing tool this is minor.

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

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

Three short sentences, front-loaded with the core definition and followed by scope consequence and a next-step link. Every sentence carries information, though the opening fragment is slightly terse and the URL sentence is mildly promotional.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description supplies enough: what the list contains and why it matters for scanning behavior. Only the return format (domain objects, pagination) is unspecified, which is a small 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?

The tool takes zero parameters, so there is nothing for the description to clarify; per the baseline, this scores 4. The schema's empty properties object is consistent with the description's lack of parameter talk.

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 the resource precisely ('domains the user has proved they own') and conveys that this is a listing of them. It is clear what the tool returns, but it never explicitly names or contrasts a sibling (e.g. check_domain_verification or list_monitors), so sibling differentiation is left to inference.

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 usage by explaining that only verified domains get active testing, which tells the agent when the list matters, and it points to a URL for verifying more. However, it does not say when to call this versus check_domain_verification or start_domain_verification, so the routing 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?

With only openWorldHint annotated, the description carries the behavioral burden and does so well: it discloses the quota/billing consequence (free for plan holders, otherwise consumes one scan) and that it triggers a full scan. It omits whether the call is async or how to track completion, which would have pushed it higher.

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: the action and its contrast come first, followed by cost implications and the id source. No filler.

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

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

For a single-param trigger tool with no output schema, the description covers purpose, timing, and cost side effects. It could note how to observe the resulting scan (e.g. get_scan_status), but nothing essential is missing.

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

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

Schema coverage is 100% for the single monitor_id parameter and the schema already names its sources, so the description's 'takes the monitor id from list_monitors' is largely redundant. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('run a full scan of a monitored site now') and explicitly contrasts with the scheduled path ('instead of waiting for its schedule'), which distinguishes it from the sibling monitors/scan 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?

Gives a clear triggering condition ('e.g. to confirm a fix') and points to list_monitors for the required id, but does not say when to prefer it over siblings like scan_url or how it relates to get_scan_status for follow-up.

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 is otherwise rich — it discloses the return artifact (a publishable file or a DNS TXT record), the practical deployment path, and the unlocking effect on scan coverage. However, 'Calling it again returns the same token, so a record already published stays valid' describes idempotent repeat behavior, which conflicts with the idempotentHint=false annotation; an agent may reasonably be misled about repeat-call semantics.

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

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

Three tight sentences, front-loaded with purpose then the concrete return artifact and the next step. No filler, and every clause carries actionable information.

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

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

For a single-parameter tool with no output schema, the description covers what is produced (file vs DNS TXT record), how it is used operationally, what it unlocks, and the required follow-up call. Nothing an agent needs to invoke it correctly 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents the domain format with examples. The description adds no additional syntax or constraint detail beyond what the schema provides, which matches the baseline for fully-covered schemas.

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 ('Begin proving the user owns a domain') and immediately names the payoff ('unlocks active tests (injection, XSS, SSRF, access control) on its scans'). It is clearly separable from the sibling check_domain_verification, which is positioned as the follow-up step.

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

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

It gives explicit sequencing ('Then call check_domain_verification') and explains repeat-call behavior ('Calling it again returns the same token'), which is exactly the context an agent needs before invoking it twice. It stops short of stating when NOT to use it (e.g. for already-verified domains, where list_verified_domains would answer instead).

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