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?

No annotations are provided, so the description must carry the behavioral disclosure burden. It mentions a constraint on the target URL but does not explain whether the operation mutates state, creates credentials, returns a session handle, or requires prior setup. This is a significant gap for a tool that 'prepares' a session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The main action is front-loaded, and the critical constraint follows immediately. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with complete schema coverage, the definition is minimally viable: the purpose and key constraint are clear. However, with no annotations and no output schema, the lack of behavioral and usage context leaves an agent uncertain about side effects, return value, and how this preparation step relates to the sibling validation tool.

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. The description's 'authorized origin' constraint restates what the targetUrl schema property already conveys, adding little new parameter-level meaning. This matches the baseline-3 case where 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 clearly states the action ('Prepare') and the resource ('a guided auth session'), with meaningful qualifiers: it comes from an operator-managed profile and the target must stay on the authorized origin. It does not explicitly differentiate itself from the sibling zap_auth_session_validate, but the prepare/validate distinction is reasonably inferable from the verb.

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 explicit guidance on when to use this tool versus alternatives like zap_auth_session_validate or zap_attack_start. The authorized-origin constraint is a precondition, but the description does not state when to prepare versus validate a session, nor when this tool is not appropriate.

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 it discloses important traits: the server decides direct versus queued execution from deployment topology, and auth support is limited to prepared form-login sessions on the HTTP spider path. It does not, however, describe what the call returns or how to track the resulting crawl, which would be useful 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?

Three focused sentences with the action front-loaded and each subsequent sentence earning its place: strategy selection, auto fallback, and auth limitation. No filler or redundant restatement of 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?

The definition is complete enough for invocation: it tells the agent what URL to provide, how to choose a strategy, and the auth limitation. The main gap is that with no output schema it does not specify the response shape or how to obtain the crawl ID needed for sibling status/stop 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 coverage is 100%, so the baseline is 3, but the description adds value by explaining the direct/queued execution model that gives idempotencyKey meaning and extends the authSessionId constraint to 'HTTP spider path only.' This is contextual information beyond the schema property 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?

The description opens with a specific verb and resource: 'Start a guided crawl for a target host or root URL.' It clearly identifies the tool's function and scope, and the guided-crawl framing distinguishes it from sibling operations like zap_attack_start or 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?

It provides explicit if-then guidance: 'Use strategy=http for traditional server-rendered sites, strategy=browser for SPAs, login-heavy flows...' and 'strategy=auto when you want the service to pick the default crawl engine.' It also gives a clear exclusion for auth: supported only on the HTTP spider path, so an agent knows when not to supply authSessionId with browser strategy.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the default grouped-detail behavior and the raw-instance mode, and notes that raw instances are 'bounded'. It does not mention failure modes or exact limits, but for a read-style details tool this is reasonably 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?

Two compact sentences, with the primary use case front-loaded and the mode switch explained in the second sentence. There is no filler or unnecessary repetition of 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?

The description captures the core decision—grouped details by default vs raw instances with includeInstances=true—and identifies the relationship to the summary tool. It does not specify filter combination behavior, sort order, or a concrete cap on the instance limit, but with all parameters optional and no output schema, it is broadly sufficient for safe invocation.

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 mostly paraphrases the schema's includeInstances semanticsmation and adds only minor examples like 'attack samples'. It does not meaningfully explain filters beyond what 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 states a specific action ('Drill into findings') on a clear resource and explicitly positions it after the summary, distinguishing it from the sibling zap_findings_summary. The two output modes (grouped vs raw instances) make the tool's purpose unambiguous.

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

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

It explicitly says to use this tool after reading the summary, and gives a concrete condition for choosing includeInstances=true when raw occurrences are needed. This clearly routes the agent to this tool instead of the summary sibling.

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

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

Annotations are absent, so the description carries the full burden. It discloses the return shape ('concise grouped risk summary') and implies a read-only operation via 'Get,' but it does not mention side effects, repeated-call safety, or other behavioral constraints. Acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, with no filler. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one optional parameter and no output schema, the description adequately primes the agent for a summarized, risk-grouped result. It could say more about grouping criteria or output structure, but it is sufficient for correct invocation.

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 covers the only parameter 100%, and the description's 'Use baseUrl to scope results to a specific host or path' mirrors the schema text. It therefore adds no meaning beyond the schema, earning the baseline 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?

The description states 'Get the first-pass findings view' with a clear verb and resource, and further specifies 'concise grouped risk summary for fast triage.' This distinctively separates it from the more detailed-looking zap_findings_details sibling, even without naming it. Purpose is unambiguous.

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

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

It explicitly sets the timing context 'after a scan or passive-scan wait,' telling an agent when this tool is relevant. It does not enumerate exclusions or alternative tools, so it falls just short of 5.

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 are provided, so the description must carry the behavioral disclosure burden. It conveys that the result is a bounded JSON snapshot, but it does not say whether the operation is read-only, whether limits or pagination apply beyond 'server configuration', what side effects may occur, or what the response shape looks like. This is insufficient for a no-annotations 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 front-loaded sentence that names the action, the resource, the output format, and the purpose. There is no fluff, repetition, or structural clutter.

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 no output schema, no annotations, and several close sibling tools, yet the description only gives a high-level snapshot intent. It does not describe the JSON shape, the default scope of the snapshot, how filters combine, or why it is distinct from the handoff/release-evidence siblings. Given that absence, an agent still has meaningful gaps to fill to call 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 each parameter already has a meaningful description including evidenceType's allowed values. The tool-level description, however, does not add param-specific semantics or clarify how 'bounded' interacts with the optional limit/status/target/evidenceType filters. 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 states a concrete action ('Export') and resource ('bounded scan history ledger snapshot') with an output format and purpose ('as JSON for release evidence or handoff'). It is clear, but it does not explicitly differentiate itself from the very close siblings zap_scan_history_release_evidence and zap_scan_history_customer_handoff, both of which coincide in purpose.

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 use this tool versus the close siblings, such as zap_scan_history_release_evidence, zap_scan_history_customer_handoff, or zap_scan_history_list. The phrase 'for release evidence or handoff' gestures at context but gives no selection criteria or exclusions, leaving the agent to infer when each alternative is appropriate.

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 provided, the description carries the full burden of behavioral disclosure. It only says 'Import,' implying a mutation, but does not explain side effects, required ZAP state, success/failure behavior, or whether existing targets are overwritten. This is a significant gap for a tool that modifies system state.

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 front-loads the core verb and resource. It is efficient with no fluff, though it lacks any secondary structure like elaboration or caveats.

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?

This is a mutation tool with no annotations, no output schema, and 5 parameters. The description gives minimal context about how this fits into the broader workflow, such as whether it is a prerequisite for scanning, what happens after import, or typical failure modes. An agent would need additional knowledge to use it effectively.

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 fully documents all parameters. The description adds the supported definition types, matching the definitionType parameter, but does not enrich understanding of sourceKind, endpointUrl, or hostOverride beyond the schema. 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 states a specific verb ('Import') and resource ('API definition'), and explicitly enumerates the supported types (OpenAPI, GraphQL, SOAP). It is distinct from sibling actions like scanning or crawling, so an agent can understand its purpose, though it does not explicitly contrast with any sibling.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions. It simply states what it does without context about its role in the ZAP workflow (e.g., before scanning or crawling).

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