MCP ZAP Server

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

With no annotations provided, the description must carry behavioral weight. It does add meaningful context: the server chooses direct vs queued execution, and authSessionId is limited to prepared form-login sessions. Yet it omits what the tool returns, whether the call blocks, whether the scan runs asynchronously, and what side effects beyond initiating a scan occur.

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 filler, with the main purpose front-loaded. Every clause earns its place by adding a distinct piece of context: purpose, execution-mode behavior, and auth limitation.

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 5-parameter action with no output schema and no annotations, the description is thin on operational essentials. It never says what the caller receives (e.g., scan ID, status reference), whether the scan starts immediately, or how to monitor it via sibling tools like zap_attack_status. An agent could invoke it correctly but be unable to interpret the result or know next steps.

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 some useful context that aligns with parameters, particularly explaining that the server decides direct vs queued mode, which clarifies when idempotencyKey matters. It mostly restates what the schema already captures for targetUrl and authSessionId, so it does not substantially exceed the baseline.

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 specific verb and resource: 'Start a guided active scan for a specific target host or base URL.' This clearly identifies the operation and differentiates it from siblings like zap_crawl_start and zap_passive_scan_wait. The phrase 'after crawl/import setup' adds sequencing that further anchors its role.

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 clear context for when to invoke this tool: after crawl/import setup, when an active scan is needed. It also notes that the server, not the client, decides direct vs queued execution. However, it does not explicitly name alternatives or state when not to use it, 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?

The word 'Get' implies a read-only operation, which is useful, but no annotations are provided and the description does not explicitly disclose non-mutating behavior, polling semantics, or behavior when the operation no longer exists. It leaves an important lifecycle behavior to inference.

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 a single sentence and has no filler or irrelevant detail. It front-loads the core purpose and stays appropriately minimal for a status-query tool.

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 one-parameter status endpoint, the description is close to sufficient: it states the resource and the schema documents the parameter. However, with no output schema and no lifecycle or polling guidance, the description does not fully prepare an agent for interpreting status outcomes or knowing when this tool applies.

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 single operationId parameter is already well documented, including its provenance as a return value from zap_attack_start. The description adds no further parameter-level meaning beyond that.

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, 'Get status', and a specific resource, 'a guided active-scan operation.' This clearly differentiates it from passive-scan, crawl-status, and history tools, and does not simply restate the tool name.

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 does not state when an agent should call this tool, such as after zap_attack_start or while polling an attack operation, and it does not mention any alternatives or exclusions. The usage is only implicit from the name and schema, not explained.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the stop action without explaining whether stopping is asynchronous, whether it is idempotent, whether results are preserved, or what side effects occur. This is a meaningful gap for a mutation-style tool.

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 a single clear sentence with no filler or redundant elaboration. It front-loads the action and the object, making it immediately scannable for an agent.

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 stop operation, the core invocation is adequately specified: the agent knows the action and the required operationId. However, with no annotations and no output schema, the description leaves uncertainty about the post-condition of the operation, such as whether further status polling is needed or whether the operation can be stopped more than once.

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 operationId parameter is already well documented as the ID returned by zap_attack_start. The tool description adds no parameter-level detail beyond what the schema provides, so the baseline score 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?

The description uses a specific verb, 'Stop', and a specific resource, 'guided active-scan operation'. This clearly identifies the tool as the counterpart to zap_attack_start and differentiates it from sibling tools like zap_crawl_stop and zap_passive_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?

Usage context is implied by the phrase 'guided active-scan operation' and by the operationId parameter being described as returned by zap_attack_start. However, the description does not explicitly say when to use it versus alternatives, such as stopping a crawl or waiting for an attack status.

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 no annotations, the description carries the full burden. It usefully discloses an authorization constraint ('the requested target must remain on the profile's authorized origin'), which is genuine behavioral context. It does not, however, disclose whether preparing a session mutates server state, what happens to a previously prepared session, or what the operation returns.

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 with the core purpose front-loaded, then routing guidance, then the constraint. Nothing is padded, though the kind-based guidance sits slightly off to the side of the actual parameters.

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 stateful 'prepare' tool with no annotations and no output schema, the description covers purpose, profile-kind routing, and an origin constraint, but omits side effects, session lifetime, and return behavior. Adequate but with clear gaps for an agent to invoke it confidently.

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 (profileId, targetUrl) are already documented in the schema and the baseline is 3. The description reinforces the targetUrl origin constraint but adds no syntax, format, or example detail beyond what the schema 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?

States a specific verb and resource ('Prepare a guided auth session from an operator-managed profile'), which is clear enough for an agent to know it sets up authentication rather than validating it. It does not explicitly contrast itself with the sibling zap_auth_session_validate, so it falls short of full sibling differentiation.

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 second sentence gives real routing guidance ('kind=browser profile for Client Spider, or kind=form for HTTP spider and active scans'), which tells the agent which profile kind fits which downstream workflow. However, 'kind' is a property of the operator-managed profile, not of this tool's parameters, and no alternative tool or when-not condition is named, leaving the guidance indirect.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'validate' without revealing whether it is read-only, what happens on success or failure, or any side effects. This is a notable gap for a tool that might be called in an automated flow.

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, efficient sentence that front-loads the action and resource. Every word earns its place, with no redundancy or 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 one-parameter tool, the description covers the essential 'what' and 'when' but omits behavioral details such as return format, error conditions, and whether the validation is a side-effect-free check. Given no annotations or output schema, the description is adequate but leaves gaps that an agent might need to infer or discover.

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 schema description for sessionId already states it is the session ID returned by zap_auth_session_prepare, and the tool description aligns with that. Since schema coverage is 100%, the description adds minimal extra meaning beyond reinforcing the 'prepared' nature. This meets the baseline but doesn't 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 clearly states the tool's purpose: to validate a prepared guided auth session. It uses a specific verb ('validate') and identifies the resource (auth session), and the context ('before authenticated crawl or attack flows') distinguishes it from sibling tools like zap_auth_session_prepare.

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 implies when to use this tool: after preparing a session and before initiating crawl or attack flows. It provides clear contextual timing but does not explicitly mention when not to use it or alternative tools. It stops short of naming alternatives or exclusions, but the sequencing is evident.

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 no annotations, the description carries the full burden and does so well: it discloses that the server decides direct vs queued execution, the narrow AJAX fallback condition, the Client Side Integration add-on and headless Firefox dependencies, and that auto does not detect JavaScript coverage. This is unusually rich behavioral context for a start 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?

Front-loads purpose then strategy guidance, and every sentence is informative. However, it is a dense run-on paragraph and some statements (e.g., 'Auto does not detect JavaScript coverage') are repeated verbatim in the schema, slightly reducing efficiency.

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 strategies, auth pairings, and the idempotency caveat, which is comprehensive for a crawl-start tool. It stops short of telling the agent what the call returns or how to track progress (e.g., via zap_crawl_status), which with no output schema would have been the natural closing 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 coverage is 100% and the schema already documents all four parameters in detail, so the baseline is 3. The description adds interpretable value by explaining the strategy trade-offs and the authSessionId compatibility rules, edging above baseline, though much of it is echoed in the schema descriptions.

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 ('Start a guided crawl for a target host or root URL'), making it clearly distinct from siblings like zap_attack_start, zap_crawl_stop, and zap_crawl_status. An agent can identify the operation 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 maps each strategy value to a situation ('strategy=http for traditional server-rendered sites, strategy=client for JavaScript-driven apps...') and states the precise fallback trigger. It also spells out the auth-session pairing rule ('prepared browser authentication sessions require strategy=client').

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?

No annotations are provided, so the description must carry full behavioral disclosure. It only says 'get status,' implying a read operation, but does not specify whether this is safe, whether it has side effects like consuming resources, or what the operationId represents (e.g., a unique identifier returned by the start tool). It lacks details about what the status response contains or any state changes, leaving a significant gap given the absence of 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 a single, concise sentence that gets to the point immediately. It does not waste words, and the purpose is front-loaded. The only minor issue is that it could have added a bit more context without becoming verbose, but for a one-parameter status tool, this is 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 tool has a simple input schema and no output schema, and annotations are absent. Given that it is a status-checking tool for a crawl operation, the description should clarify what kind of status information the agent can expect (e.g., progress, completion) and any prerequisites (e.g., the operation must have been started). It does not provide enough context for an agent to know what to do with the result, making it incomplete for effective use.

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 schema already describes the operationId parameter as 'Guided crawl operation ID returned by zap_crawl_start' with 100% coverage, so the baseline is 3. The description adds no additional information about the parameter (e.g., format, whether it is required), but it does confirm the parameter is an operation ID, which is helpful. Since the schema covers fully, this is adequate.

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 purpose: get status for a guided crawl operation, distinguishing it from status tools for other operations like zap_passive_scan_status and zap_attack_status. However, it could be more explicit about what 'guided crawl' entails and how it differs from related crawl tools like zap_crawl_stop, though the name and input schema suggest 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?

The description implies usage when you need to check the status of a crawl started with zap_crawl_start, as indicated by the parameter description. However, it does not explicitly state when to use this tool versus other status tools (e.g., zap_attack_status) or provide any alternatives, leaving the agent to infer based on the operation type.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but doesn't disclose whether the operation is idempotent, what happens to in-progress crawl data, whether it requires an active operation, or what the response looks like. For a control operation, this is a notable 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?

The description is a single, short sentence that is front-loaded with the action and resource. It earns its place with no wasted words, though it could add a bit more context without becoming verbose.

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 control operation with no annotations and no output schema, the description is thin. It doesn't mention prerequisites (e.g., operation must be running), side effects, or return behavior. An agent would need to infer these from the parameter name and sibling tools.

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 schema already documents the single parameter. The description adds no extra meaning beyond the schema, but the baseline of 3 applies because the schema fully covers the parameter 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?

The description states a specific verb ('Stop') and resource ('a guided crawl operation'), which clearly identifies the action. It doesn't explicitly distinguish from sibling tools like zap_attack_stop, but the resource term 'guided crawl' differentiates it from other stop operations.

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 implies usage: call this when you need to stop a guided crawl. It doesn't explicitly state when to use it versus alternatives like zap_attack_stop or zap_crawl_status, but the resource-specific wording provides enough context for an agent to infer the right scenario.

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 no annotations, the description carries the full burden and does well: it discloses the default behavior (grouped details), the opt-in mode and what it yields (bounded raw occurrences with URLs/params/evidence/attack samples), and an access prerequisite (baseUrl must be covered by scan evidence visible to the caller). It stops short of return-format or pagination/limit behavior detail.

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 purpose and prerequisite, then the default behavior, then the opt-in flag. No filler or repetition of schema text.

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 must convey returns and does so at a useful level (grouped blocks vs. bounded raw instances). It is nearly complete for a 5-parameter, single-required read tool, though the shape of a 'grouped detail block' remains unspecified.

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 goes beyond the schema by clarifying that includeInstances switches between grouped and raw-instance output and that results are bounded, and by framing baseUrl as an evidence-coverage requirement rather than just a string.

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 ('drill into findings') and explicitly positions itself relative to a sibling ('after reading the summary'), so an agent can distinguish it from zap_findings_summary without opening either schema. The two operating modes (grouped vs. instances) are also 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?

Gives a clear sequencing rule ('after reading the summary') and an explicit trigger for the includeInstances flag. It does not spell out when NOT to use this tool or name the alternative in a negative form, so it falls short of the 5-level 'when/when-not/alternatives' standard.

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 no annotations, the description carries the full burden and does real work: it discloses that results are live/partial during running scans, that counts must not be read as completion, coverage, or safety, and that access is scoped to evidence visible to the caller. It omits read-only confirmation, pagination, and result-shape details.

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 what the tool does, followed by a skeptical caveat and the precondition. No filler; every sentence changes how an agent would use the tool.

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 tool with no output schema or annotations, the description covers purpose, valid timing, access scoping, and an interpretation warning. The only gap is no hint about grouping dimensions or response size.

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's wording ("nonblank target baseUrl covered by scan evidence visible to the caller") essentially restates the schema's own parameter text. Baseline 3 applies since the schema already does this 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 ("Read currently recorded alerts") plus the output form ("concise grouped risk summary for fast triage"), which separates it in spirit from zap_findings_details. It does not name that sibling explicitly, so the differentiation is implied rather than stated.

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?

"Including while scan work is in progress" and "for fast triage" give clear, actionable conditions for reaching for this tool over the status/detail tools. It stops short of stating an explicit exclusion or naming zap_findings_details as the alternative when full per-alert detail is wanted.

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?

No annotations are provided, so the description carries the full burden. It implies a read-only status check ('Get') but does not explicitly state that it is non-blocking, does not trigger scans, or has no side effects. It is not misleading, but it lacks explicit behavioral disclosure for a tool with zero annotation support.

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 a single, focused sentence that front-loads the verb 'Get' and the key resource. There is no redundancy, and it is appropriately concise for a zero-parameter status query.

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, no-output-schema tool, the description covers the basic action. However, it omits context about how it relates to zap_passive_scan_wait, which an agent might need to choose correctly. It also does not specify whether the status is a snapshot or whether it returns immediately, leaving some ambiguity.

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 and the schema confirms this (empty properties, 100% coverage). With no parameters to describe, the baseline of 4 applies, and there is nothing additional the description needs to clarify.

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 a specific verb 'Get' and a clear resource: 'passive scan backlog and completion status.' This distinguishes it from sibling tools like zap_attack_status and zap_crawl_status, which target other scan types. It is clear but does not explicitly contrast with zap_passive_scan_wait, so it misses full differentiation.

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 guidance on when to use this tool versus alternatives. The sibling list includes zap_passive_scan_wait, which likely serves a different purpose (waiting vs. checking status), but the description does not mention this distinction or provide any contextual cues for selection.

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 no annotations, the description carries the full burden. It does disclose the key behavioral trait — this is a blocking wait that enforces ordering before reads/reports — but it says nothing about what happens if the backlog never drains or on timeout (though timeout semantics are partly covered by the schema's timeoutSeconds field).

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 front-loaded sentence that states the action and the sequencing rationale with zero waste. Nothing is redundant or padded.

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 low-complexity tool with two optional, fully documented parameters and no required inputs, the description covers purpose and ordering adequately. It would be stronger if it mentioned what the call returns or how the blocking status tool relates, but no output schema exists to demand that.

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 pollIntervalMs and timeoutSeconds are already documented with ranges and defaults. The description adds no parameter meaning beyond the schema, which is the expected baseline 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?

The description gives a specific action and resource: waiting for the passive-scan backlog to drain. It is unambiguous about what the tool does, but it never contrasts itself with the closely related sibling zap_passive_scan_status (the non-blocking check), 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 states a clear usage context: run it before reading findings or generating reports. That is real sequencing guidance. However, it names no alternative and gives no exclusion, so an agent is not explicitly told when to use zap_passive_scan_status instead of blocking here.

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?

No annotations are provided, so the description carries the full disclosure burden. It adds a real behavioral precondition (run it only after the passive scan backlog drains) and signals that 'guided defaults' are applied, but says nothing about where the artifact lands, whether it is persisted, or how it is later retrieved (a sibling, zap_report_read, exists for that).

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 action, and the second sentence is pure routing information. No filler, no restatement 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?

Adequate on selection but thin on the lifecycle: with no annotations and no output schema, the agent is told what to generate but not what it receives back or how to read the resulting artifact. The schema partially compensates by spelling out scoping and theme behavior.

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 schema already explains theme, format and baseUrl, including the non-obvious rule that omitting baseUrl scopes to the full session. The description contributes nothing param-specific ('human-shareable' loosely hints at the html format), so 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+resource ('Generate a human-shareable report artifact') and immediately separates itself from sibling triage tools (zap_findings_summary/zap_findings_details). An agent can tell what this produces versus its nearest siblings without opening any 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?

Gives an explicit precondition ('after passive scan backlog drains') and an intent ('export or handoff artifact'), plus a named alternative for interactive triage. It stops short of disambiguating the other report-related siblings (zap_report_read, zap_scan_history_export, zap_scan_history_customer_handoff), which would be the natural follow-up question.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses that output may be truncated and routes complete retrieval to a sibling, and 'Preview' signals a non-mutating read operation. It does not cover permissions, authorization, or error behavior, so it is not fully complete.

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, front-loaded with purpose and then the truncation fallback. No filler or 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 simple two-parameter read tool with no output schema, the description covers purpose, prerequisite, and truncation handling. It could specify the artifact format or return shape, but the core decision information 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?

Schema coverage is 100%, so reportPath and maxChars are fully documented in the schema. The description adds no parameter-level semantics beyond the dependency on zap_report_generate, so 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?

Names a specific verb (Preview) and resource (generated report artifact), ties it to the producing sibling zap_report_generate, and distinguishes it from zap_report_read_chunk for truncated output. An agent can select 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?

States when to use it (after zap_report_generate) and names the alternative when output is truncated (zap_report_read_chunk). This is explicit routing with no inference required.

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 no annotations, the description carries the full burden and does so well: page ordering, termination signal (endOfFile), integrity verification (expectedSha256 rejects a changed report), code-point counting semantics, and a 50 MiB artifact limit. These are exactly the operational traits an agent needs and none are derivable from the schema alone.

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?

Four dense sentences, front-loaded with the core action, then the calling protocol, then units and limits. Every sentence contributes a distinct fact; nothing is filler or restated from 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?

There is no output schema, so the description appropriately surfaces the return-side fields an agent must act on (nextOffset, endOfFile, artifactSha256) alongside the pagination and integrity rules. Complete for a chunked-read tool with four parameters.

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 genuine value beyond it: it clarifies that offset/maxChars count Unicode code points (not bytes), explains the artifactSha256-to-expectedSha256 handshake across pages, and notes the SHA-256 identifies the full original file rather than the page.

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) and resource (a generated UTF-8 report) and immediately qualifies the mode as 'bounded JSON pages', which distinguishes it from the sibling zap_report_read without needing to name it. An agent can tell this is the paged/chunked reader rather than a one-shot fetch.

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 explicit procedural context: append pages in order, follow nextOffset until endOfFile=true, and pass the first page's artifactSha256 as expectedSha256 on later calls. It does not name zap_report_read as the non-paged alternative or state when-not to use chunking (e.g. small reports), so it stops short of full when/when-not routing.

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 no annotations, the description carries the transparency burden, and it does provide meaningful behavioral detail: the output is Markdown, customer-safe, and stripped of raw internal IDs, backend references, workspace IDs, and metadata. It does not explicitly state whether the operation is read-only or whether the summary is returned directly, but the wording strongly implies a non-destructive generation action.

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 a single, tight sentence that leads with the primary action and output, then adds the most important constraints. There is no filler, repetition of the tool name, or unnecessary detail.

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 low-complexity tool with three optional parameters, no output schema, and no annotations, the description is largely sufficient: it defines what the tool produces)Skip, in what format, and what it intentionally omits. It could be more explicit about whether the summary is returned inline or written somewhere, but the core invocation-relevant information 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 schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond the schema, but the schema already explains limit, target, and handoffName sufficiently, including the note that the raw target selector is never echoed in customer-facing output.

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 ('Generate') and names a distinct resource: a customer-safe Markdown handoff summary from scan history. It distinguishes itself from siblings like raw list/export or report tools by emphasizing the sanitized, customer-facing output and the explicit exclusion of internal IDs and metadata.

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 intended use is implied by the purpose: it creates a customer-safe summary rather than a raw or internal-facing view. However, it never explicitly states when to prefer this over close siblings such as zap_scan_history_export, zap_scan_history_release_evidence, or zap_report_generate, and it gives no exclusion criteria.

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?

No annotations exist, so the description carries the full burden and does so well: it discloses the surprising destructive side effect ('querying may delete expired stored ledger entries under the configured retention policy'), that no file is created, that there is no pagination and results are capped by limit, that it does not start scans or contact targets, and that it does not refresh outcomes from ZAP.

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 action and the no-file caveat, then alternatives, then return shape and behavioral caveats. Every sentence carries information, though the enumerated return fields and the alternate-tool list make it longer than strictly necessary.

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 compensates by naming the return keys (version, generatedAt, retentionDays, entryCount, entries) and warning that entries contain internal IDs and paths. Combined with the filter semantics and the retention side effect, an agent has everything needed to call it correctly and warn the user.

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 per-parameter semantics are already documented, making 3 the baseline. The description adds cross-parameter behavior the schema cannot express: omission/blank semantics for all filters, AND-combination of supplied filters, the limit cap, and the empty-array result when nothing matches.

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 (export) and resource (scan history), specifies the output form (inline JSON text, no file created), and names the three sibling tools it is not. An agent can distinguish it from zap_scan_history_list, zap_scan_history_release_evidence, and zap_scan_history_customer_handoff without opening any 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 routes the agent: readable listing -> zap_scan_history_list, summary bundle -> release_evidence, customer-facing summary -> customer_handoff, internal evidence processing -> this tool. Also states when filters apply ('omitted or blank filters select all accessible records; supplied filters combine with AND').

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?

No annotations are provided, so the description must carry the behavioral burden. The verb 'Read' clearly signals a non-mutating operation, which is useful, but the description does not disclose behavior for missing/invalid IDs, permissions, or what the returned entry contains. It is adequate for a simple read but not fully transparent.

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?

One sentence, front-loaded with the action ('Read') and the resource ('one ... entry'), with zero filler. Every word earns its place for a single-parameter getter.

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 combined with the fully documented parameter is enough for an agent to invoke the tool on a simple get-by-ID operation. However, with no output schema and no annotations, the description leaves return format and error behavior unspecified; this is a minor gap given the low complexity.

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, the parameter is already documented: 'Entry ID returned by zap_scan_history_list.' The description only restates 'by ID' and adds no new meaning about format, constraints, or relationship to other tools 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 precise verb ('Read'), a specific resource ('one scan history or release-evidence entry'), and an access pattern ('by ID'). The singular 'one ... by ID' differentiates it from the list-oriented sibling zap_scan_history_list, and naming both entry types removes ambiguity about what can be fetched.

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 read-by-ID wording implies the tool is for retrieving a single previously obtained entry, but the description does not explicitly state when to prefer it over zap_scan_history_list, zap_scan_history_release_evidence, or other sibling tools. There is no when-not or alternative routing, 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?

With no annotations, the description carries the burden of behavioral disclosure. 'List' strongly implies a read-only operation, and the description adds the included entry types. However, it does not disclose default ordering, pagination, limit behavior, or output shape, which would be useful given no output 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?

The description is a single front-loaded sentence with no filler. Every phrase adds useful information: the verb, the resource, and the specific entry categories.

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 schema fully covers parameters, and the operation is simple with no required inputs. However, the absence of an output schema and annotations, plus no mention of how this list relates to the sibling get/export tools, leaves some context gaps for an agent deciding whether this tool is sufficient.

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 parameters are already fully documented in the schema. The description adds little beyond the 'recent' context and the general categories, which does not substantially improve parameter understanding.

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 ('List') and resource ('recent scan history and release-evidence entries'), and enumerates concrete included categories. This clearly differentiates it from sibling tools like zap_scan_history_get or zap_scan_history_export without needing to open 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?

The description implies when to use the tool: when a recent list of scan history and evidence entries is needed. However, it provides no explicit guidance about when to prefer this over zap_scan_history_get, zap_scan_history_export, or zap_scan_history_release_evidence, nor any 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?

The description discloses what the export contains ('summary counts, target coverage, warnings') and that ledger entries are bounded, which is useful behavioral context. However, with no annotations, it does not clarify whether the export is returned directly, written to a file, or requires permissions, and does not explain side effects or response format.

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, front-loaded sentence states the purpose and key output characteristics with no wasted words. Every element contributes to understanding what the tool does.

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 tool with only three optional, well-described parameters, the description is adequate but not rich. It omits the export's return shape or delivery mechanismché, and there is no output schema or annotations to fill that gap, leaving an agent uncertain about what invoking the tool actually yields.

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 each parameter already has a meaningful description. The tool description adds little beyond 'target coverage', which loosely maps to the target parameter, but does not expand on limit, target, or releaseName 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?

The description clearly states the action ('Export') and a specific resource ('release or pilot handoff evidence bundle') with distinctive contents (summary counts, target coverage, warnings, bounded ledger entries). It does not explicitly name sibling alternatives like zap_scan_history_customer_handoff or zap_scan_history_export, but the resource qualifier makes the purpose reasonably distinct.

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?

There is no guidance about when to choose this tool over similar siblings such as zap_scan_history_export, zap_scan_history_customer_handoff, or zap_scan_history_get. No context, conditions, exclusions, or alternatives are mentioned, leaving selection 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses prerequisites, session changes, outbound requests to definition sources and API targets, authorization constraints, content-mode limitations, return contents, and error conditions. It also clarifies that import does not start an active scan, which prevents a meaningful misuse.

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 front-loaded with purpose and usage, then covers prerequisites, side effects, content mode, return values, and errors. Despite its length, every sentence adds actionable information for a complex, multi-mode tool with no 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?

Given no annotations and no output schema, the description is complete enough for correct invocation: it covers required environment setup, source modes, side effects, authorization constraints, return behavior, error cases, and the necessary follow-up step. Nothing critical for safe and correct use appears to be 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%, and the schema already documents all five parameters in detail, including mode-specific requirements. The description restates some cross-parameter constraints, such as content mode requiring hostOverride and shared filesystem staging, but adds little semantic detail beyond what the schema 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 states a specific verb and resource: importing OpenAPI/Swagger, GraphQL, or SOAP WSDL definitions to prepare API endpoints for testing. It also distinguishes this from ordinary web discovery by explicitly naming zap_crawl_start as the alternative for web pages.

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 clear selection guidance: use this when you have an API definition, but use zap_crawl_start to discover ordinary web pages. It also states the post-import workflow, directing the agent to review messages and only call zap_attack_start when active testing is permitted and approved.

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