CertScore.ai MCP Light

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavior beyond that: the 25000-byte MCP Light ceiling, the 5000-byte floor with priority ordering, truncation semantics, provenance restrictions, reuse-implies-same-scan semantics, and strong interpretive limits (no compliance inference, no extrapolation). The disclosure is rich, though its value is undercut by garbled passages and a verbatim repeated sentence.

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 overly long, disorganized, and redundant: the evidenceUrlTemplate sentence appears twice verbatim, and the text jumps among return format, budgets, provenance, compliance caveats, and reuse warnings without clear structure. Several sentences are confusing ('encode in TextContent opposite canonical text'; 'returned structuredContent will not include fields omitted from the canonical content list'). The front-loaded 'Call after' precondition is good, but the rest does not earn every sentence.

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 — detail tiers, byte budgets, truncation, provenance, reused-scan semantics — the description covers the essential operating context: when to call, how budgets behave, what takes priority at the floor, how to handle provenance, and what interpretations are forbidden. The output schema exists, so return-value documentation is not the description's burden. Remaining gaps are minor: no explicit sibling routing and the garbled wording weakens some guidance.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all five parameters. The description earns credit by adding relational meaning: detail tier progression ('findings increases the default finding allowance, evidence adds bounded evidence digests... full adds all available bounded sections'), the byte-budget interplay between maxBytes and truncation, and the priority behavior at the floor. This goes beyond restating the schema.

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

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

The description makes clear this tool retrieves the completed scan bundle ('Every usable completed bundle returns a self-contained concise TextContent digest plus matching structuredContent') and states the precondition 'Call after completed or completed_limited status.' It is distinguishable from siblings by role — this returns results, whereas get_scan_status checks status and scan_site initiates — but the differentiation is implicit rather than explicitly named.

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 opening line 'Call after completed or completed_limited status' is an explicit, actionable precondition that tells an agent when in the workflow this tool applies. It also gives concrete rules for reused scans ('use only persisted scanFrom and timestamps; never infer its original region') and for the detail tiers. However, it never names the alternatives (e.g., 'use certscore_get_scan_status to poll progress') or states when not to use this tool.

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 read-only and idempotent, so the description focuses on non-obvious behavior: active vs terminal responses, specific fields returned, provenance handling rules, and explicit 'stop polling' instruction. This richly exceeds what annotations provide and adds critical guidance.

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 efficiently structured: purpose first, then active/terminal response summaries, then crucial provenance cautions, and a stop condition. Each sentence adds value without unnecessary fluff, though it is moderately long.

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, the description covers the essential behavioral context: what to expect, when to stop, and how to handle edge cases like reused scans. Minor omissions like error handling for invalid scanIds are not critical given the schema and workflow clarity.

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%, with scanId already described as the stable ID from certscore_scan_site. The description reinforces 'only the stable scanId' but doesn't add new parameter details beyond what the schema covers. 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?

The description clearly states the tool polls for scan status using a scanId from certscore_scan_site, distinguishing it from the sibling tools (bundle retrieval and site scanning). It specifies the resource and action precisely.

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 explicit context on when to use it (after certscore_scan_site), how to handle reused scans (use persisted scanFrom, never infer region), and when to stop polling (terminal status). It does not explicitly name the alternative sibling tool, but the implied workflow is clear.

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 hint at non-read-only, non-idempotent behavior, but the description discloses a rich behavioral contract: the 25-second total budget, creation-time deduction, polling retention of scanId, terminal states to stop polling, and the compliance caveat ('No-go and limited coverage are observations, never proof of compliance'). This goes far beyond annotation hints and sets correct expectations.

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 every sentence serves a purpose: scanning scope, budget, polling workflow, terminal states, and a compliance caveat. It is front-loaded with a clear purpose statement and avoids redundancy. Given the tool's complexity, the length is warranted and well-structured.

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 entire lifecycle: initiation, budget management, polling behavior, terminal outcomes, and the follow-up bundle call. It references sibling tools appropriately and adds the compliance caveat. With the output schema present and the description guiding the full workflow, nothing an agent needs to call this tool effectively 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?

Though the schema already documents all parameters (100% coverage), the description adds crucial nuance: scanFrom region selection rules, freshness semantics distinguishing 'ordinary' vs 'explicit refresh' requests, maxWaitSeconds budget behavior, and waitForCompletion default with its asynchronous exception. This extra guidance materially improves correct invocation beyond the schema alone.

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 precise verb and resource: 'Use CertScore.ai to scan a public website...' and enumerates specific observable signals (cookies, trackers, CMP behavior, TLS, etc.). It unambiguously distinguishes itself from sibling tools certscore_get_scan_status and certscore_get_scan_bundle by focusing on initiating/reusing scans, while the siblings handle status and bundle retrieval.

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 guidance on when to use this tool: 'Starts or reuses a public-web scan' and when to use alternatives: 'poll certscore_get_scan_status' and 'call certscore_get_scan_bundle' for usable completion. It also instructs on parameter choices ('Use refresh only when the user explicitly requests...', 'Do not use multiple regions unless comparison is requested') and defines the budget and terminal states.

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