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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's marginal job is to add the state prerequisite, which it does ('must have status complete before a report can be generated'). That is useful non-obvious behavior; the only minor gap is not stating whether download is synchronous or costs credits, but with annotations covering the safety profile this is solid.

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 action, then the precondition, then the format decision guidance — no filler and every sentence 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?

For a 2-parameter read-only tool with full schema coverage and safety annotations, the description covers the key gating condition and format choice. It could note the asynchronous nature or that pdf yields a URL rather than inline content, but the schema already carries that detail.

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 format enum is already fully documented in the schema, including the pdf-returns-URL detail. The description repeats the format guidance rather than adding new syntax or constraints, so it lands at the baseline for a well-documented 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 (download) and resource (full penetration test report) plus the format dimension, which clearly distinguishes it from siblings like turbopentest_get_findings or turbopentest_get_pentest that return raw scan data rather than a formatted 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?

Gives a concrete precondition — the scan must have status 'complete' — which tells the agent when the call will succeed, and it explains which format to pick for which use case. It stops short of explicitly naming alternatives, but the gating condition and format routing are 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 declare this is a safe read-only, non-destructive, closed-world operation, and the description adds valuable domain context: credits are consumed on launch and each tier costs one credit of the matching type. This economics model is genuinely useful and not in the structured fields. Slightly short of a 5 because it doesn't mention whether the call itself costs anything or whether balances are cached/stale.

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, both front-loaded with actionable information: what you get, then when to call it. The credit-consumption clause earns its place because it explains the precondition's rationale; 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?

Even without an output schema, the description enumerates the return contents (balance, per-tier usage, available tiers with pricing), and the only sibling it interacts with is named. For a zero-param read tool, an agent has everything needed to call it and use 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?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly focuses its language on return-value contents rather than inventing parameter behavior.

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 precisely enumerates the resources returned: credit balance, usage breakdown by tier, and available scan tiers with pricing. This is clearly distinguishable from siblings like start_pentest or get_pentest, which deal with actual 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?

Explicitly tells the agent when to call it ('before turbopentest_start_pentest') and why ('to verify you have sufficient credits for the desired tier'). The alternative — just launching the test — is implicitly excluded by this precondition, leaving nothing to infer.

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 readOnly, non-destructive and closed-world, so safety needs no repeating. The description adds the useful 'up to 20 findings at a time' cap but never explains how to retrieve the rest — and the schema has no pagination, offset or cursor parameter, so the limit disclosure creates a question it does not answer.

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 core action and returning payload before the limit and the alternative. The field enumeration is slightly long but earns its place since there is no output 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?

With no output schema, the description responsibly enumerates what a finding contains (severity, CVSS, CWE, PoC, remediation). The one real gap is the unexplained 20-item cap versus an absent pagination parameter.

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%: both pentest_id and the severity enum are fully documented, including per-level definitions. The description only restates the severity filter's purpose, adding no format, default or combined-filter guidance beyond 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 (retrieve), resource (vulnerability findings) and scope (a completed penetration test). That scope distinguishes it from sibling tools that start or analyze tests, and the enumerated field list makes the payload concrete.

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 two concrete routing cues: use the severity filter to focus on risk levels, and use turbopentest_download_report for a full exportable report. It does not mention when to prefer turbopentest_workflow_analyze_findings instead, which is the closest ambiguous 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the returned sections and noting progress percentage is available, which tells the agent this is safe to poll during a run. It does not discuss response size or rate limits for polling, keeping it below 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?

Three compact sentences: purpose, payload contents, then usage and routing. The payload enumeration is front-loaded and every clause carries information the 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?

There is no output schema, so the description must describe return values — and it does so by naming the key sections (status, progress, findings summary, executive summary, attack surface, STRIDE). Combined with the follow-up pointer to get_findings, an agent has everything needed to call and interpret it.

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 description coverage on the single pentest_id parameter, the schema already explains the UUID format and where to obtain it. The description adds no syntax or format detail beyond that, 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 ('Retrieve full details for a specific penetration test by its ID') and enumerates what the response contains (status, progress, severity summary, attack surface, STRIDE model). This clearly separates it from turbopentest_get_findings, which is named as the drill-down sibling.

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 gives two usage contexts ('monitor a running scan or review completed results') and routes the agent to turbopentest_get_findings for detailed vulnerability data. It stops short of stating when not to use it (e.g., listing many tests via turbopentest_list_pentests), but the routing guidance 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: what fields come back and the account-level scope. It omits any note on result size or pagination, which keeps it below 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?

Three short sentences, front-loaded with what the tool returns, followed by the prerequisite and the out-of-band verification path. Nothing is redundant with the schema or 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 zero-parameter read-only list tool with no output schema, the description covers the returned fields, the account scope, and the downstream dependency on turbopentest_start_pentest. An agent has everything needed to call it 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?

The tool takes zero parameters, so the baseline is 4 and the input schema is trivially complete. No param guidance is needed in the description.

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 (domains) and names exactly what is returned: verification status and expiry dates. No sibling tool covers domains, so there is no ambiguity with turbopentest_get_pentest or turbopentest_get_findings.

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: a domain must be 'verified' to be used with turbopentest_start_pentest, and points out that verification is done out-of-band via the dashboard DNS TXT record. It does not state a 'when not to use' case, but there is no competing tool to exclude.

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 readOnly=true, destructive=false, and closed-world, so the safety profile is covered. The description adds useful context beyond that: default ordering is newest-first and each record includes status and finding counts, which tells the agent what the response looks like even without an output schema. It stops short of stating pagination behavior or whether results are scoped to the caller's account, leaving a small 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?

Three tight sentences, front-loaded with the core behavior, then use cases, then the sibling alternative. Every sentence carries distinct information with no redundancy.

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-only list tool with full schema coverage and no output schema, the description supplies return contents and default ordering, which is what the agent needs. Nothing required to invoke it correctly 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%, so the schema already documents both the limit range and every status enum value. The description only restates that filtering by status and limiting results are supported, adding no syntax or behavioral detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 all your penetration tests') plus the return contents (status, finding counts) and ordering (newest first). It also distinguishes itself from turbopentest_get_pentest, which returns full details for a single ID.

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 three concrete use cases (find pentest IDs, check running scans, review past results) and explicitly names the alternative turbopentest_get_pentest with the condition that selects it. Nothing 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.

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

Annotations only say readOnly=false, destructive=false, openWorld=true; the description adds real behavioral detail beyond that — the tool self-checks domain verification and returns isError rather than launching, and it consumes a credit tied to the tier. It does not describe what happens after launch beyond returning an ID, but that is low risk for a non-destructive, open-world operation.

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, then preconditions, then the return value. The aside 'so there is no need to bypass this check' is slightly redundant once the refusal behavior is stated, but no sentence 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?

Covers the action, both hard preconditions, the failure mode, and the returned handle for monitoring — everything needed to call it correctly with no output schema present. Minor gaps are the lack of any cost magnitude or concurrency limit, which the tier enum partly offsets.

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, but the description adds meaning the schema does not: the tier selection determines which credit is consumed, tying a parameter to a real precondition. The repo_url white-box behavior is already in the schema, so no credit there.

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 ('Launch an AI-powered penetration test against a target URL') plus the scope implied by the tier enum. It is clearly distinguishable from siblings like turbopentest_workflow_run_pentest or turbopentest_list_pentests because it launches a new scan rather than reading or orchestrating.

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 preconditions: the domain must be verified and a credit must be available, and it points at turbopentest_get_credits and turbopentest_get_pentest for the surrounding steps. It stops short of contrasting against turbopentest_workflow_run_pentest, so an agent must infer which launch path applies.

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 readOnly, openWorld, and non-destructive. The description adds valuable context beyond them: it is a public unauthenticated endpoint and returns metadata plus blockchain proof only if anchored. It could mention rate limits or behavior for unknown hashes.

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 the core action followed by return contents and public-access note. No wasted phrasing.

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 read tool without an output schema, the description covers input semantics, return contents, authentication requirements, and the anchoring condition. An agent has enough to call it 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 coverage is 100% and the single hash parameter is fully documented in the schema as the SHA-256 attestation hash included in reports. The description only restates that it is a SHA-256 hash, adding no syntax or format detail beyond 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 ('Verify a blockchain-anchored penetration test attestation by its SHA-256 hash') and clearly distinguishes this lookup/verification action from sibling workflows like get_pentest or download_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?

Explains the use case ('independently confirm that a pentest was performed and its results are tamper-proof') and notes it is public with no API key. It lacks explicit when-not-to-use guidance or named alternatives, but the context 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context by clarifying the tool returns instructions rather than performing the analysis, and explains why it exists as a prompt workaround. It doesn't describe the shape of the returned instructions, but that's a minor gap given 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 behavior, with the client-compatibility guidance following. 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?

For a single-parameter, read-only workflow tool with full schema coverage and no output schema, the description tells the agent exactly what it will get back (instructions) and why it exists. Nothing needed to call it correctly 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 pentest_id parameter is fully documented in the schema. The description adds a semantic constraint beyond the schema by tying the input to a 'completed' pentest, implying the ID must reference a finished engagement.

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: returns step-by-step instructions for producing a prioritized remediation plan from a pentest's findings. An agent can distinguish this from data-retrieval siblings like turbopentest_get_findings, which return raw findings rather than workflow instructions.

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?

Names a clear triggering condition: use it in MCP clients such as Codex that don't support the 'analyze_findings' prompt directly. The alternative (the native prompt) is identified, though it doesn't state when to prefer raw get_findings data instead.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds important context by clarifying that this tool returns instructions rather than performing the comparison itself, which is behavior 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?

The description is two sentences, front-loads the tool's output behavior, and then gives the client compatibility condition. Every sentence contributes useful information without 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?

For a two-parameter, read-only workflow helper with full schema coverage and no output schema, the description is mostly complete. It explains what is returned and when to use the tool, though it could say more about the shape of the returned instructions.

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%, with both baseline_id and current_id documented as earlier and later pentest UUIDs. The description adds only that the pentests should be on the same target and implies baseline/current ordering; it does not add syntax or format details beyond 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 uses a specific verb and resource: it returns step-by-step instructions for diffing two pentests on the same target. It also clarifies that the output shows what's new, fixed, and persistent, distinguishing this workflow helper from direct pentest retrieval 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?

It explicitly says to use this in MCP clients like Codex that don't support the 'compare_pentests' MCP prompt directly. That gives a clear condition, though it does not name any sibling tool alternatives or exclusion cases beyond the unsupported prompt.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description is consistent with it (it returns instructions, not actions). It adds useful context beyond that: the step sequence including a credit check and domain-verification gate implies prerequisites and potential cost. It does not disclose the shape of the returned instructions or behavior when the target domain is unverified.

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 padding. The purpose and the full lifecycle scope come first, and the client-compatibility condition is placed last where it belongs.

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 workflow-guidance tool with a fully documented schema and no output schema, this is nearly complete: it says what it returns, what the sequence covers, and when to prefer it. A brief note on what the instructions reference (e.g. that they call the start_pentest/get_findings tools) would close the last 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% and the tier enum is fully documented in the schema (agent counts and durations), so the baseline of 3 applies. The description adds only 'against a target' and echoes the verified-domain requirement that the schema already states. No extra meaning about tier selection trade-offs is provided in the description.

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 ('Returns step-by-step instructions') and enumerates the lifecycle it covers: domain verification, credit check, launch, progress monitoring, findings summary, report offer. It also makes clear it is a guidance tool rather than an executor, which separates it from turbopentest_start_pentest. It stops short of explicitly naming that sibling as the alternative, so it is clear but not fully 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 an explicit when-to-use condition and a counterfactual: use this in MCP clients (like Codex) that don't support the 'run_pentest' MCP prompt. That routes the agent meaningfully. It doesn't address when an agent should instead call turbopentest_start_pentest / get_pentest / get_findings directly, which are the obvious sibling alternatives for a client that does support multi-step calls.

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 that this is a safe, read-only, non-destructive, closed-world operation. The description adds important behavioral context by clarifying that it returns step-by-step instructions rather than performing the briefing or pentest itself, and that the scope is the 5 most recent pentests. It does not detail the instruction format or whether fewer than five pentests changes the output, but the key 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 two concise sentences with no wasted language. It front-loads the primary purpose and then provides the client-compatibility condition.

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 workflow-instruction tool with no output schema, the description is nearly complete: it states what is returned, the scope of pentests, and the client condition. A minor gap is that it does not describe the structure or limitations of the returned instructions, but the essential information for correct invocation is present.

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 has zero parameters, so there is no parameter semantics for the description to compensate for. The baseline for a zero-parameter tool is 4, and the description does not need to explain parameters.

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 and resource: it returns step-by-step instructions for producing an executive security posture briefing across the 5 most recent pentests. This clearly distinguishes the tool from data-fetching and pentest-execution siblings by emphasizing that it generates guidance rather than running analysis itself.

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 explicitly says to use this in MCP clients that don't support the 'security_posture' MCP prompt directly, which gives a clear usage condition and implies the prompt is the alternative when supported. It does not explicitly state when not to use the tool or mention sibling workflow tools as alternatives, but the context is clear.

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