CertScore.ai — Light mode

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

The description goes well beyond the readOnlyHint/openWorldHint annotations by explaining exactly what every response contains: detail and byte-budget metadata, omittedSections, retrieval URLs, and nextRecommendedMaxBytes when truncated. It also adds a critical interpretive warning about not treating no-go/not-observed/limited coverage as proof of compliance, which is valuable behavioral context.

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

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

The description is dense but well-organized: precondition first, then detail levels, then response metadata, then an interpretive warning. Every sentence earns its place, and there is no redundant repetition of schema or annotation 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?

Given the tool's complexity—multiple detail levels, byte budgets, truncation, and open-world caveats—the description covers the essential operational context. Preconditions, return behavior, metadata, and a critical interpretation warning are all present, and the output schema covers the exact return structure.

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

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

The input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds meaningful semantics for the 'detail' parameter by explaining what summary, findings, evidence, and full actually return, and it contextualizes maxBytes via the nextRecommendedMaxBytes hint. It does not elaborate on maxFindings or maxPreConsentRows, but their schema descriptions are sufficient.

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

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

The description clearly identifies when to call the tool (after completed or completed_limited status) and what it returns at different detail levels, but it does not explicitly distinguish it from sibling tools like get_scan_status or scan_site. The verbs 'returns', 'reserves', and 'adds' convey the core retrieval purpose well.

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 provides explicit timing guidance ('Call after completed or completed_limited status') and explains when different detail levels are appropriate. However, it does not mention alternative tools or situations where this tool should not be used, so it lacks full exclusionary 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 readOnlyHint and openWorldHint annotations already indicating safety, the description adds valuable behavioral detail: it enumerates active response fields (phase, heartbeat, estimated progress, stalled state, retry delay) and terminal response fields (score, risk, coverage, timestamps, report URL, next action), plus the stop-polling rule. This goes beyond annotations without contradicting them.

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 action verb. Every sentence adds value: what to poll, what responses look like, and when to stop. No wasted words or redundancy with schema/annotations.

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 one-parameter polling tool with an output schema, the description covers the full lifecycle: how to initiate polling, what to expect in both active and terminal states, and the stopping condition. It is complete without needing to describe return formats since the output schema exists.

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

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

Schema description coverage is 100%, and the scanId parameter is fully documented in the schema. The description merely repeats the schema's note that scanId is stable and returned by scan_site, adding no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose with a specific verb ('Poll') and resource ('stable scanId returned by scan_site'). It distinguishes itself from siblings by defining its scope as a status polling tool tied to scan_site, which is unambiguous.

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

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

The description gives clear usage context: poll only with the stable scanId from scan_site and stop at any terminal status. However, it does not explicitly mention when to use the sibling tool get_scan_bundle instead, so it lacks an explicit exclusion or alternative 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?

The description adds significant behavioral context beyond the annotations, such as the 45-second default wait, scan reuse via freshness, the need to poll with the exact scanId, and the caveat that no-go/limited coverage observations are not proof of compliance. This goes well beyond the openWorldHint and readOnlyHint 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?

The description packs a full workflow into four dense, purposeful sentences. It front-loads the primary action ('First call') and then provides ordered, actionable follow-up steps without any filler or 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?

The description covers the complete lifecycle: scan initiation, waiting behavior, polling statuses, terminal conditions, and the next-step call to get_scan_bundle. It also addresses edge cases like scan reuse and status interpretation, making it fully sufficient given the rich output schema and sibling 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 input schema already provides 100% coverage of all five parameters, including detailed descriptions, enum values, and constraints. The description adds minimal new parameter-level detail, only indirectly referencing maxWaitSeconds and waitForCompletion, so it meets the baseline for high schema coverage but does not exceed 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?

The description uses a specific verb phrase 'starts or reuses' and identifies the resource as a 'public-web scan', clearly distinguishing it from the sibling follow-up tools. It explicitly labels itself as 'First call', which immediately signals its role in the workflow.

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

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

The description provides explicit workflow instructions: retain the scanId, poll get_scan_status, stop at terminal statuses, and call get_scan_bundle for usable completion. It also clarifies when to use waitForCompletion=false for an asynchronous workflow, giving clear context for when this tool should be used versus alternatives.

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