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 behavioral burden and does well: it discloses that the server chooses direct versus queued execution, lists add-on and headless Firefox prerequisites for Client Spider, and constrains which auth sessions work with which strategies. It omits failure modes, permissions, and how to monitor or stop the crawl, 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?

The description is front-loaded with the core action and then layers in server behavior, strategy mapping, prerequisites, and auth constraints. Every sentence earns its place and there is no redundant or filler 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?

For a multi-strategy crawl-start tool with rich schema coverage and no output schema, the description covers the key decision points an agent needs: when to choose each strategy and which auth sessions are compatible. It could go further by noting that execution may be asynchronous or by pointing to zap_crawl_status/zap_crawl_stop.

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 practical meaning beyond the schema: it explains which strategy suits which site type, notes Client Spider add-on requirements, and maps auth-session kinds to strategies. It does not elaborate on targetUrl or idempotencyKey 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?

The description states a specific verb and resource: 'Start a guided crawl for a target host or root URL.' It is clearly distinct from attack or scan tools, but it never names a sibling to differentiate from, such as zap_attack_start, so it stops short of the top score.

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 explicit strategy-selection guidance for traditional sites, JavaScript apps, AJAX Spider, and the default engine, and adds auth-session compatibility rules. It does not state when to prefer this tool over sibling tools like zap_attack_start, but the strategy guidance is detailed and actionable.

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. It usefully discloses the precondition that scan evidence must be visible to the caller, but says nothing about read-only semantics, rate limits, pagination, or whether results change over time.

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 core purpose, then the return value, then the precondition. No filler or 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 single-parameter read tool with no output schema, the description covers purpose, return shape, timing, and the key visibility precondition. It leaves the exact return structure unspecified, but the 'grouped risk summary' characterization is sufficient for an agent to invoke 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 description coverage is 100%, so the baseUrl semantics (nonblank, covered by visible scan evidence, with an example) are already fully documented in the schema. The description restates this requirement rather than adding new parameter detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get the first-pass findings view') and specifies the output form ('concise grouped risk summary'). This implicitly but clearly distinguishes it from the sibling zap_findings_details, which would imply the detailed drill-down.

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 temporal context ('after a scan or passive-scan wait') and a use case ('fast triage'), routing the agent appropriately. It does not explicitly name zap_findings_details as the alternative for deeper inspection or state when not to use this tool.

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

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

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 must carry the behavioral disclosure burden. It communicates that the tool blocks until the backlog drainsley, but does not mention what happens on timeout, whether any side effects occur, or what the tool returns. This is adequate for a simple wait operation but leaves some behavioral details implicit.

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 tight sentence with no filler. The main action and its purpose are front-loaded, and the description earns its place without 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 wait tool, the description plus fully documented parameters gives enough to call it, but there is no output schema and no statement about return values or timeout behavior. This is a clear gap, though not severe given the tool's simplicity.

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 two parameters are already documented in the input schema. The description adds no extra parameter details, which fits the baseline score of 3.

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 ('wait'), a concrete resource ('passive scan backlog'), and a clear purpose ('before reading findings or generating reports'). This differentiates it from siblings like zap_passive_scan_status meaningless name. The sentence fully explains what the tool does.

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

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

The description gives a clear workflow context: use it before reading findings or generating reports. It does not explicitly name alternative tools or state when not to use it, but the sequencing guidance is strong enough to guide an agent's choice.

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 bears the full burden of behavioral disclosure. It says 'Generate' but does not state whether the operation is read-only, has side effects, requires authentication, or is long-running. It also omits any mention of rate limits or potential impact on scan state. For a generation tool, this is a significant 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 two sentences with zero filler. The primary purpose is front-loaded, and the usage guidance is concise and directly actionable. Every word 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 tool with only optional parameters and no output schema, the description covers purpose and usage adequately. However, it lacks behavioral details and does not explain what 'guided defaults' means or how the report artifact is delivered (e.g., returned vs. stored). Given the simplicity, it is moderately complete but leaves some operational specifics unclear.

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?

All three parameters (theme, format, baseUrl) have descriptions in the input schema, and schema description coverage is 100%. The tool description adds no additional information about parameters, so it does not exceed the baseline of 3 that the schema already provides.

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

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

The description clearly states the action ('generate') and the resource ('human-shareable report artifact'), and specifies 'using guided defaults' which, while vague, does not obscure the core purpose. It also differentiates from sibling tools by contrasting with findings summary/details for interactive triage, making its role 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?

The description gives explicit usage timing ('after passive scan backlog drains') and directly names the alternative use case ('findings summary/details for interactive triage'). This provides clear guidance on when to select this tool over siblings, leaving nothing 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?

No annotations are provided, so the description carries the burden. It clearly implies a read operation ('Read') and mentions the alternative of manual filesystem access, which is useful. However, it doesn't disclose any additional behavior, such as error handling or the format of the returned content, which is a minor gap for a simple read 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, compact sentence that front-loads the verb and resource, includes the key context (after zap_report_generate) and the benefit (no manual filesystem access). Zero waste; every word 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?

The tool is simple with two parameters (one required), no output schema, and low complexity. The description explains the purpose and when to use it. While it doesn't explicitly state the return value, it's implied by 'read back through MCP.' This is adequate for a straightforward read operation.

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 both parameters well. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't clarify maxChars behavior or report path format beyond the schema's own description). Baseline 3 is appropriate.

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

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

The description clearly states the tool reads a report artifact, specifies its use after zap_report_generate, and distinguishes it from manual filesystem access. It doesn't explicitly differentiate from sibling read tools like zap_scan_history_get, but the resource type (report artifact) is distinct enough.

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

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

The description gives clear context on when to use it (after zap_report_generate) and why (avoid manual filesystem access). It doesn't explicitly list alternatives or exclusions, but the context is sufficient for an agent to understand its placement in the workflow.

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 burden and does so: it discloses that import mutates the current ZAP session, may send requests to the definition source and API targets, requires authorization, and does NOT start an active scan. It also states the return format (plain text with definition type, source kind, source, and import messages/job IDs) and that invalid inputs, blocked URLs, and ZAP API failures raise errors.

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, then usage, then behavior, then return/error semantics. Despite its length, every sentence adds distinct information for a complex, unannotated tool, so 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?

For a tool with no annotations and no output schema, the description covers the safety profile (session mutation, egress, authorization), prerequisites (configured ZAP instance and add-on), the return shape in lieu of an output schema, and error behavior. Nothing an agent needs 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 description coverage is 100%, so the schema already documents source, sourceKind, endpointUrl, hostOverride, and definitionType in detail. The description notes the add-on matching requirement but adds no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb (import) plus the resource (OpenAPI/Swagger definition, GraphQL schema, SOAP WSDL) and the goal (prepare API endpoints for testing). It explicitly distinguishes itself from zap_crawl_start for ordinary web pages, so an agent can pick the right tool 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?

Gives when-to-use ('when you have an API definition'), names the alternative and its condition ('use zap_crawl_start to discover ordinary web pages'), and sequences the downstream action ('call zap_attack_start ... when active testing is needed'). It also states the prerequisite of a reachable, configured ZAP instance with the matching add-on.

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