Launch Ready

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description earns credit by disclosing entitlement behavior (Agency-only), the api_locked failure mode on other plans, and that plan limits gate brandMode. It still doesn't say whether repeated calls mint duplicate links (relevant given idempotentHint=false) or what the returned value 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?

Two sentences with zero filler, front-loaded with the core action before the plan caveat. Every clause (entitlement, failure mode, brandMode gating) carries information an agent needs.

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 4-parameter creation tool with no output schema, the description covers the plan gate and key error path, and 'share URL' implies the return value. It stops short of covering link lifecycle details (re-invocation behavior, expiry default handling), which are minor given the schema's 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 100%, so the baseline is 3; the description adds value by explaining that plan limits determine which brandMode values are accepted, a constraint the enum description alone does not convey. scanId, expiresInDays, and hideTechnical are left entirely to the schema, which is acceptable at full coverage.

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 ('Mint a client-facing share URL') scoped to 'a completed scan', which no sibling tool (get_report, scan_site, etc.) overlaps with. An agent can identify the operation immediately 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?

Explicitly states the prerequisite (Agency plan) and the when-not path ('other plans answer api_locked and can share from the app'), which is a genuinely useful fallback. It does not name any MCP alternative because none exists, but the entitlement gating 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 already cover read-only/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful context beyond that: it never marks anything fixed (so a rescan is required to verify), and it warns that text from the scanned site is untrusted data, not instructions — a prompt-injection caveat annotations cannot express.

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, front-loaded with the core behavior and the field list before the workflow and safety caveats. The middle field enumeration is slightly dense, but every clause carries 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?

With no output schema, the description usefully enumerates the return fields and adds the untrusted-content warning and the rescan workflow, which is enough for an agent to call and interpret it correctly. Only minor gaps remain, such as error behavior for unknown findingIds.

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 schema already documents both parameters including where scanId and findingId originate. The description only restates 'by findingId' without adding format, validation, or sourcing detail. 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 and resource (get one finding of a completed scan) and enumerates the returned fields, which cleanly separates it from the sibling list_findings and list_blockers that return sets. An agent can identify it 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?

Usage is implied rather than stated: the 'by findingId' phrasing hints that identifiers come from a listing call, and the 'rescan once the fix is deployed' note gives workflow context. But no sibling is named as the alternative and no explicit when-to-use condition is given.

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, so safety is covered; the description goes beyond them with genuinely useful traits: pollAfterMs indicates polling while running, expiresAt explains when a Free scan stops being readable, and the closing line warns that zero blockers is not launch approval. It stops short of auth requirements or what happens for an unknown/expired scanId.

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-loads the core purpose and then orders the returned fields logically (identity/status, then post-completion metrics, then coverage, then interpretation). The first sentence is a dense run-on with many comma-separated clauses, but nearly every clause carries distinct information, so the length is largely earned.

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 full burden of explaining return values and does so thoroughly, including enum values for readiness and effectiveReadiness and the meaning of capped/htmlOnly coverage fields. Only failure modes (invalid or expired scanId) and any auth expectations are 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?

Schema coverage is 100% and the single parameter's schema description already points to scan_site, so the schema does the work. The description adds no format, constraint, or example for scanId, which is the correct baseline when coverage is complete.

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 ('Read one scan') and then enumerates exactly what the record contains: status, target URL, environment, score, readiness, blocker counts, category summaries and coverage. An agent knows precisely what this returns. It does not, however, distinguish itself from the sibling get_scan, leaving a plausible ambiguity unresolved.

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 naming the required scanId's provenance ('from scan_site') and by mentioning pollAfterMs for in-flight scans, so an agent can infer this is the detail call for a known scan. But there is no explicit when-to-use/when-not or routing to get_scan/get_finding/list_findings, and no prerequisite or error-condition 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds the crucial behavioral fact that the tool is deprecated and what the return contains (status, score, readiness), but says nothing about auth, rate limits, or how long deprecated access persists.

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 with zero waste; the deprecation warning is front-loaded so an agent reads the most consequential fact first.

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 summarizes the returned fields and the migration path. For a single-parameter read tool, that is nearly complete, though it stops short of describing the exact response shape.

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 (scanId) and schema description coverage is 100%, so the schema already documents its origin ('Scan id from scan_site.'). The description adds nothing about parameter format, and per the baseline rule a 3 is correct.

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 plus the fields returned: 'Reads one scan's status, score, and readiness.' It also names the replacement tool (get_report), which distinguishes it from siblings, though the differentiation comes from deprecation rather than scope.

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?

Explicitly tells the agent when NOT to use this tool ('Deprecated: use get_report'), naming the alternative. For routing purposes this is as clear as guidance gets.

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 (readOnly/idempotent/non-destructive), and the description adds substantial behavior on top: acknowledged and won't-fix items are counted as excused rather than fixed, scoreBlocker fires when the score alone makes the scan Not ready, minSeverity:critical narrows the list while counts stay complete, and site text is untrusted data. That is exactly the extra context the 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?

Front-loaded with the core rule and dense with signal, but the tail mixes return-value facts, reporting imperatives, and a prompt-injection warning into one long paragraph, which costs some scannability. Nothing is purely filler, though several sentences are agent-behavior instructions rather than tool semantics.

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 two-parameter read tool with no output schema, the description discloses what comes back (readiness, effectiveReadiness, counts) and covers the important edge case that zero blockers is not launch approval, plus the untrusted-content caveat. An agent has everything needed to call it and interpret the result.

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 description largely restates the schema's minSeverity semantics ('critical lists only Block Launch items') plus the scanId origin. It adds no syntax or format 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 and resource ('What blocks launch on a completed scan') and defines the exact rule: critical and high findings not acknowledged or marked won't-fix. That definition immediately distinguishes it from the sibling list_findings, which returns all findings regardless of state.

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 clear sequencing guidance ('Report blockers before anything else') and explains the minSeverity branch so the agent knows which mode to pick. It does not explicitly name a sibling (e.g. list_findings) as the alternative when the agent wants unfiltered findings, so it stops short of 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds ordering semantics (worst first), default-state behavior, the resolved-then-refound-is-open rule, the omission of evidence, and an explicit prompt-injection warning about untrusted scanned-site text.

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: purpose first, then state/filter/identity/trust notes. Each sentence adds value, though the parenthetical offset tip partially repeats the schema.

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 must characterize returns; it names findingId and fingerprintHash and notes evidence is excluded. It stops short of enumerating all finding fields but covers the agent-critical traits.

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. The description adds nuance beyond the schema: severity ordering, nextOffset-to-offset round-tripping, and the resolved-refound interpretation that the schema's 'closed findings' wording only hints at.

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), resource (a completed scan's findings), plus ordering (worst first) and pagination mode. Clearly distinguishable from sibling get_finding (single item) and get_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?

Gives clear context: findings of a completed scan, filtered by category and state, paged via nextOffset. It does not explicitly name sibling alternatives such as get_finding for a single result, so routing is only implicit.

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, idempotent, non-destructive behavior, so the bar is lower. The description adds useful context beyond them: the score field is conditional ('when one exists'), implying nullable output, and the returned ids have a downstream purpose. Pagination and empty-workspace behavior are still unstated.

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 returned-resource scope front-loaded and the sibling routing second. 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?

With no parameters and no output schema, the description must carry the return-value burden, and it does name the returned entities plus the conditional scan score. It omits pagination/ordering and the full shape of a project record, but is sufficient for a zero-arg list call.

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. Baseline 4 applies; no parameter-level misinformation is present.

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 ('List every website'), scopes it to this API key's Launch Ready workspace, and notes the enriched field (latest completed scan score). An agent can distinguish it from list_findings/list_blockers, which target findings rather than projects.

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?

Explicitly ties usage to a sibling: 'Use the ids when scan_site answers project_ambiguous.' That is a concrete when-to-use condition. It stops short of stating when NOT to call it or naming the other listing tools 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?

Adds substantial behavior beyond the annotations: background execution with required polling, Free-plan binding_required flow, credit-spending and subscription gating, withdrawal acknowledgment, and target_mismatch on redirects. It also explains that the idempotencyKey is what makes retries safe, which is consistent with (not contradictory to) idempotentHint=false.

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-loads what the tool does and the async contract, then layers operational rules; nearly every sentence carries information an agent needs. A few clauses are dense or loosely worded ('checks that one site for good'), but there is 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 an 8-param, mutation-flagged, no-output-schema tool it covers the polling loop, error outcomes, and consent preconditions well. It stops short of describing the queued response itself (scan identifier, pollAfterMs shape) and does not address the start_scan sibling.

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 100% schema coverage the baseline is 3, but the description adds real meaning for the trickiest params: when confirmDomain may be set ('ask the user before repeating', 'never confirm on their behalf') and how project resolution proceeds from the URL. scanMode and allowCredit guidance still largely restates 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?

States a specific verb and resource ('Queue a launch-readiness scan of a URL') plus the key async trait ('return at once; the crawl runs in the background'). The distinction from the sibling start_scan is left unexplained, so it does not fully separate itself from the other scanning entry point.

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 sequencing ('Poll get_report after pollAfterMs until status is completed or failed') and when-not conditions ('Scan a deploy only once it is live'), plus consent rules for confirmDomain. It does not, however, clarify when to pick this over the near-identically named start_scan sibling.

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 it is a non-read-only, non-idempotent, open-world write, and the description adds the key behavioral fact those annotations don't convey: the operation is asynchronous and must be polled via get_report until completed/failed. It does not explain the idempotencyKey's retry behavior, but that detail is already in 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?

Two short sentences with the deprecation warning and its replacement front-loaded, followed by the essential async workflow. Every clause carries weight; nothing is 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?

For a two-parameter tool with no output schema, it covers purpose, deprecation, and the polling loop needed to get a result. The one small gap is that it doesn't say what the queued scan returns (an id or handle) to poll with, though get_report is named.

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 projectId and idempotencyKey are fully documented in the schema. The description only restates 'by id' and adds no format or constraint detail beyond it, so the baseline of 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 and resource ('Queues a scan of a project by id') and immediately distinguishes itself from the sibling that supersedes it ('Deprecated: use scan_site'). An agent can tell exactly what this does and why it might not want it.

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?

Explicitly names the preferred alternative (scan_site) and gives the downstream workflow step ('Poll get_report until status is completed or failed'), which defines when the job is finished. Nothing about selection or follow-through 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.