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

With no annotations provided, the description carries the behavioral burden and does disclose the most important trait: the new app exists in a deny-all state until a policy is attached, which prevents an agent from assuming the hostname is immediately protected. It omits other behavioral facts such as required permissions, idempotency on repeated calls, or whether an existing app on the same domain 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?

Two short sentences, no filler, and the primary effect is front-loaded before the follow-up caveat. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need not be explained, and the description covers the critical post-creation state an agent must know. The remaining gap is minor — no mention of zone scoping or what happens if the domain is already protected — which keeps it just short of fully complete.

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 each parameter (name, domain, zone_id, session_duration) is documented in the schema itself, including the 'No scheme' constraint and the default. The description adds only an indirect reference to the domain parameter and no syntax, formatting, or defaulting detail beyond the schema, 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?

The description states a concrete effect — putting a hostname behind a Cloudflare Access login — which is clearly a creation operation on an Access application and is distinguishable from delete_access_app_tool and list_access_apps_tool. It is slightly indirect in that it never uses the word 'create' or 'application', so an agent must map 'hostname behind Access login' to the create_access_app_tool name itself.

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

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

It supplies the key context that a freshly created app has no policy and denies everyone, implicitly naming create_access_policy_tool as the required follow-up. It does not state when to choose this over other creation siblings (e.g., create_dns_record_tool) or any preconditions on the zone, so it stops short of full when/when-not 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?

No annotations are provided, so the description carries the full behavioral burden. It never states permission requirements, whether policy evaluation order matters, whether changes apply immediately, or any side effects of a mutation. The rule-shape explanation is valuable but reads as parameter semantics rather than behavioral disclosure.

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

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

Two short sentences, both front-loaded with the essential facts: the operation, then the non-obvious rule object format. No filler.

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

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

With an output schema present, return values needn't be explained, and the critical parameter unknown (rule structure) is covered. However, for a 7-parameter mutation with zero annotations, the description omits prerequisites and behavioral context an agent would want before invoking it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the description adds genuinely new information: the include/exclude/require arrays hold objects with exactly one key of a fixed set, with concrete examples (email, email_domain, ip, everyone). The schema types these as generic objects with additionalProperties:true and no key documentation, so this is real added meaning.

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

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

States a specific verb+resource: 'Add a policy to an Access application.' This clearly distinguishes it from create_access_app_tool and delete_access_policy_tool by naming the resource and operation. It does not explicitly reference siblings, so it stops short of a 5.

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 when-to-use guidance, no prerequisites (e.g. that the target Access app must already exist via create_access_app_tool), and no mention of how this relates to list_access_policies_tool or delete_access_policy_tool. The agent must infer everything about context.

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 and does almost none of it. It does not state required permissions, whether the record is created immediately, idempotency, or error conditions for invalid zone/type combinations.

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 with no waste, so structure is fine. Its brevity, however, reflects under-specification rather than disciplined concision, keeping it at minimum-viable.

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 mutation tool with 8 parameters and no annotations, the description is inadequate. An output schema exists so return values need not be explained, but the absence of any usage, permission, or behavioral context leaves the definition incomplete.

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%, documenting all 8 parameters (ttl, name, type, content, proxied, priority, zone_id, comment), so the schema already does the heavy lifting. The description adds zero parameter meaning, which sets it at the baseline of 3 under the coverage rule.

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 (Create) and resource (DNS record), so an agent immediately knows the operation. However, it offers no differentiation from siblings like update_dns_record_tool, delete_dns_record_tool, or create_page_rule_tool, which is the key remaining gap at this level.

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 update_dns_record_tool or list_dns_records_tool, no prerequisites, and no stated context. The agent must infer usage entirely from the name.

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, yet it discloses nothing about permissions required, whether creation is idempotent, how the mandatory targets/actions arrays are interpreted, or whether the rule takes effect immediately. Only the bare fact that it is a write operation is conveyed by the verb.

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 short sentence with zero waste, but this is under-specification rather than conciseness — brevity here costs the agent all routing and behavioral information. A single sentence is not appropriate for a five-parameter mutation 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 mutation tool with five parameters, no annotations, and two free-form object-array parameters whose semantics are entirely unstated, the description leaves the agent unable to construct a correct call. The existing output schema excuses explaining return values, but nothing else is covered.

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 zone_id, targets, actions, priority and status are already documented in the schema. The description adds no format details, no examples of target/action object shapes, and no interaction between priority and ordering. Baseline 3 applies when the schema does the heavy lifting.

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

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

"Create a new page rule" only restates the tool name and title — a bare verb+resource with no scope, no mention of zone binding, and no distinction from update_page_rule_tool or list_page_rules_tool. An agent learns nothing it couldn't infer from the identifier itself.

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

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

There is no when-to-use guidance and no reference to the obvious alternatives (update_page_rule_tool, list_page_rules_tool, delete_page_rule_tool). The agent must infer that this is the creation path purely from the name.

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 adds genuine context by disclosing the free-plan quota (5 custom rules) and the zone selector mutual exclusivity. However, it says nothing about required permissions, idempotency, or mutation/reversibility behavior for a write 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 short sentences, front-loaded with the core purpose, then quota, then the selector constraint. Every sentence 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?

An output schema exists, so return values need not be explained, and the purpose, quota, and selector exclusivity are covered. Still, for a mutation tool with zero annotation coverage, the description omits permissions, validation expectations for the expression field, and failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by declaring that zone_id and zone_name are mutually exclusive ('not both'), a constraint not expressed anywhere in the schema properties. This is genuine value-add over the structured fields.

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: 'Create a new WAF custom rule.' An agent can immediately understand the operation. It does not explicitly differentiate from siblings like update_waf_rule_tool or delete_waf_rule_tool, but the create semantics are self-evident among the WAF rule family.

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?

Provides a real constraint ('Provide either zone_id or zone_name, not both') and a plan limitation, but gives no explicit when-to-use guidance relative to alternatives such as update_waf_rule_tool, nor any prerequisites. Usage is implied rather than directed.

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. It usefully discloses one key side-effect: the hostname persists but loses its Access login, distinguishing this from a broader teardown. However, it omits irreversibility, required permissions, and any confirmation the deletion succeeded.

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 with no filler, and the outcome is front-loaded after the verb. It is appropriately sized for a simple delete 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?

An output schema exists so return values need not be explained, and the schema covers both parameters. What is missing for a destructive operation with no annotations is the irreversibility/permission context, which the description does not address.

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 app_id (UUID) and zone_id (32-char hex). The description adds no parameter-level 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?

The description states a specific verb (Delete) and resource (Access application) and adds the outcome 'leaving its hostname with no Access login,' which clarifies exactly what state results. It does not explicitly distinguish itself from siblings like delete_access_policy_tool, but the resource scope 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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or warnings about the operation. Usage is only implied by the verb. Nothing tells the agent when deletion is appropriate or what to check first.

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 implies a destructive operation but says nothing about irreversibility, required permissions, or side effects on the parent Access application. For a delete tool with zero annotation coverage 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?

A single short sentence with the verb and resource front-loaded and zero filler. It is arguably under-specified rather than bloated, so it scores well on efficiency while leaving room for more content.

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?

An output schema exists, so return values need not be explained, and the schema fully covers the three ID parameters. However, for a destructive tool with no annotations, the absence of any warning about irreversibility or permission requirements leaves an important behavioral gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with all three IDs (zone_id, app_id, policy_id) documented including their formats (UUID, 32-char hex), so the schema does the heavy lifting. The description adds no meaning beyond that, which is the expected 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?

States a specific verb (Delete) and resource (a policy from an Access application), which an agent can distinguish from sibling delete tools like delete_access_app_tool. It stops short of explicitly naming the sibling or scoping the parent resources (zone/app) in prose, but the 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?

No guidance on when to use this versus list_access_policies_tool or create_access_policy_tool, and no prerequisites such as needing the app to exist or the policy to be currently attached. The agent must infer usage entirely from the name.

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, and 'Delete' is the only signal that this is a destructive, likely irreversible mutation. It says nothing about required permissions, whether deletion is permanent or recoverable, confirmation requirements, or the effect on associated records.

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 single three-word sentence is short but does not earn its place — it is under-specification rather than conciseness, duplicating the tool name instead of front-loading useful 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?

An output schema exists, so return values need not be explained, but for a destructive operation with zero annotation coverage the description is far too thin: no safety, permission, or reversibility context is supplied anywhere.

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 both parameters (zone_id, record_id) carry format guidance (32-character hex string) in the schema itself. The description adds nothing further, 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?

It gives a verb+resource ('Delete a DNS record'), which does implicitly separate it from create/update/get/list siblings, but it restates the tool name and title almost verbatim and adds no scope, target, or effect detail. It is accurate but minimal — the reader learns nothing they could not infer from the name alone.

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 when-to-use guidance, no mention of prerequisites (e.g. resolving zone_id/record_id first via list_dns_records_tool or get_dns_record_tool), and no exclusions. The agent must infer the context entirely from the tool name.

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 for a destructive operation, and it discloses nothing: no irreversibility warning, no permission/scope requirements, no indication of what happens to dependent resources. The only implicit signal is that 'Delete' mutates 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?

A single four-word sentence with zero waste and the verb front-loaded, so it is structurally clean. But the extreme brevity reflects under-specification rather than efficient communication, so it cannot score higher.

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 mechanical aspects are covered externally: both required parameters are fully described in the schema and an output schema exists, so return values and inputs need no explanation here. What remains missing is any when-to-use or destructive-operation context, which is a real but modest gap given how simple the call is.

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% – both zone_id and rule_id are documented as 32-character hex strings in the schema – and the description adds no further format or constraint detail. Baseline 3 applies when the schema does all the work.

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

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

States a specific verb (Delete) and resource (page rule), which cleanly separates it from the create/update/list page-rule siblings. It does not, however, add any scope detail beyond what the tool name already conveys (e.g. whether the whole rule or a subset is removed).

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 versus update_page_rule_tool or list_page_rules_tool, no prerequisites, and no note that the operation is irreversible. The only usage signal is the verb 'Delete' implied by the name.

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 supplied, so the description carries the full behavioral burden for a destructive mutation. It says nothing about irreversibility, whether confirmation is required, what happens on a missing rule_id, or required auth — only the verb "Delete" is disclosed.

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

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

Two short, front-loaded sentences with no filler; the operation is stated first and the constraint second. It is arguably too terse for a destructive tool, but nothing 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 delete operation with zero annotation coverage and no output-schema explanation needed, the description should at minimum flag irreversibility or failure behavior. Instead it covers only the operation name and a parameter-exclusivity rule, leaving the agent without the safety context Deletion requires.

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, and the description adds a real constraint the schema does not encode: the schema allows both zone_id and zone_name to be null, while the description requires exactly one. It still does not explain why a zone is needed alongside rule_id.

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 ("Delete a WAF custom rule"), which is clearly distinguishable from the create/update/list WAF siblings. However, it never explicitly contrasts itself with those siblings or states what scope of rule is removed.

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 mutual-exclusivity rule for zone_id/zone_name is genuine usage guidance for invocation, but there is no statement of when to reach for this tool versus update_waf_rule_tool or delete_page_rule_tool, nor any prerequisite context (permissions, existing rule).

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 readOnlyHint=true annotation already establishes that this is a safe read operation. The description adds that the returned application includes its audience tag (aud), which is useful output context, but it provides no additional behavioral details such as authorization requirements, error behavior, or rate limits. With annotations carrying the safety profile, this is a moderate contribution.

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 wasted words. It immediately states the operation and the notable return detail. Nothing is repeated unnecessarily.

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 a simple read operation with complete parameter documentation, a readOnlyHint annotation, and an output schema. The description supplies the remaining essential context: what is fetched and one notable returned field. An agent has everything needed to select and invoke the tool 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 both parameters (app_id and zone_id) are already fully documented in the input schema. The description does not add syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Get one Access application, including its audience tag (aud).' It clearly scopes the operation to a single application, implicitly distinguishing it from list_access_apps_tool. However, it does not explicitly name or differentiate itself from sibling tools.

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

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

The description gives no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as list_access_apps_tool or get_access_organization_tool. While 'Get one' implies retrieval of a single app by ID, this is not framed as usage guidance.

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

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

Annotations declare readOnlyHint=true, so the safe-read profile is already known. The description adds domain context by naming the Zero Trust organization and its relation to a zone's Access applications, but it does not mention auth needs, rate limits, or response behavior. With annotations covering safety, this modest addition merits a 3.

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 wasted words. It is appropriately sized for a one-parameter getter and 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 simple getter with complete schema coverage, an output schema, and readOnly annotations, the description states what is retrieved. It is nearly complete, though it could clarify the relationship to Access applications more precisely; a 4 is fair.

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 single zone_id parameter is documented in the schema as a 32-character hex string. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb ('Get') and resource ('Zero Trust organization behind a zone's Access applications'), making the action clear. However, it does not differentiate this tool from siblings like get_zone_tool or list_access_apps_tool, so it falls short of a 5.

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 when-to-use guidance, no alternatives, and no exclusions. An agent gets no help deciding between this and related Access or zone tools. The description provides only the bare purpose.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered without the description. Beyond that the description adds nothing behavioral: no error behavior for a missing/invalid ID, no note on what the record payload contains, no rate-limit context.

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 short sentence with the key scoping qualifier ('single', 'by ID') front-loaded. Nothing is padded or redundant.

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

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

For a simple two-parameter read tool with a complete schema, an output schema, and annotations covering safety, the description covers enough to invoke correctly. Only the absence of error/edge-case guidance keeps it from being fully complete.

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 both zone_id and record_id (including their hex-string format) are fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single DNS record by ID'), and the word 'single' implicitly separates it from the sibling list_dns_records_tool. It stops short of naming that sibling or contrasting the two, so it is clear but not fully differentiated.

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

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

The phrase 'by ID' implies the caller must already hold a record_id and wants one record rather than a listing, which is a usable signal. But there is no explicit statement of when to prefer this over list_dns_records_tool or get_zone_tool, and no prerequisites given.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds the aggregation behavior ('grouped by action and source'), which is real value. It does not disclose pagination, default window behavior, or result volume concerns beyond what the schema's defaults imply.

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

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

Two short sentences with the core action front-loaded and the constraint immediately following. Nothing is wasted, though it is terse enough that some helpful context is omitted.

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?

Return values are covered by the output schema and all five parameters are documented at 100% coverage, so the description doesn't need to explain them. It is complete enough to call correctly, with only marginal gaps around which sibling to choose.

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 already 100%, setting a baseline of 3. The description goes beyond the schema by stating that zone_id and zone_name are mutually exclusive, an XOR constraint the schema cannot express, which meaningfully guides invocation.

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 ('Get') and resource ('security/firewall events') and adds that results are 'grouped by action and source', which tells the agent the shape of the output. It does not, however, differentiate itself from nearby analytics tools like get_zone_analytics_tool or get_top_pages_tool, so the boundary between siblings is left implicit.

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 supplies one clear usage rule ('Provide either zone_id or zone_name, not both'), which is genuinely helpful mutual-exclusion guidance. It offers no when-to-use context relative to the other analytics/security siblings, so an agent must infer when this tool is preferred over them.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden, but it adds nothing behavioral: no note on rate limits, pagination, result ordering, or how ties are broken. Nothing here goes beyond the annotation and the schema.

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

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

Two short sentences, front-loaded with the resource and metric, followed immediately by the one constraint that matters. No filler or restatement of the title.

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

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

An output schema exists, so return values need no explanation, and defaults for limit/since/until are in the schema. However, with zero required parameters the description never says what happens if neither zone_id nor zone_name is supplied, leaving a real ambiguity about the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule between zone_id and zone_name, which the schema does not encode (both are independently nullable). That is genuine added meaning for two of the five parameters.

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

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

States a specific verb (Get), resource (top pages), and ranking metric (request count), which clearly separates it from generic analytics siblings like get_zone_analytics_tool. It does not explicitly name or contrast with those siblings, so it falls just short of 5.

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 only guidance is the exclusivity constraint 'Provide either zone_id or zone_name, not both,' which is about parameter usage rather than when to pick this tool over get_zone_analytics_tool or get_traffic_by_country_tool. Usage is implied by the name and metric, not stated.

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 readOnlyHint annotation already establishes this is a safe read, so the description's burden is reduced. It adds the useful constraint that zone_id and zone_name are mutually exclusive, but says nothing about what happens if both are supplied, whether results are paginated, or how the breakdown is ordered.

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

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

Two short sentences, purpose stated first, constraint second. No filler, no restatement of the title, nothing that could be trimmed.

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?

An output schema exists, so return values need no explanation, and the schema fully covers the five optional parameters. Only the missing sibling routing and failure behavior for conflicting zone identifiers keep it below a 5 for a five-parameter analytics 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 coverage is 100%, so limit/since/until/zone_id/zone_name are all documented in the schema (baseline 3). The description adds one genuinely non-derivable rule — "provide either zone_id or zone_name, not both" — since the schema marks both as nullable and would permit supplying both.

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

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

The description gives a specific verb+resource ("Get traffic breakdown by country"), which is clearly distinct from analytics siblings like get_top_pages_tool, get_security_events_tool, and get_zone_analytics_tool. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

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

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

Usage is only implied by the resource name plus the mutual-exclusion constraint on zone identifiers. There is no statement of when to prefer this over get_zone_analytics_tool or get_top_pages_tool, and no prerequisite guidance (e.g., that a zone must exist or that the caller needs analytics permission).

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?

readOnlyHint=true already declares this as a safe read, so the description only needs to add context. It reinforces the read-only summary nature and adds the zone exclusivity rule, but says nothing about auth requirements, rate limits, or the timezone/aggregation behavior of the date range.

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 lines, front-loaded with the purpose, then return contents, then the one invocation caveat. 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?

With an output schema present, the field list is arguably redundant but harmless, and the exclusivity rule covers the main ambiguity. The only remaining gap is guidance on default behavior when no zone is supplied, which is minor given all four parameters are optional and documented.

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, but the description adds a genuine constraint the schema does not express: zone_id and zone_name are mutually exclusive. That is real added meaning beyond the structured fields.

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 zone traffic analytics summary' — and enumerates what the summary contains (requests, visitors, bandwidth, cache ratio, status codes). It is clear what the tool returns, though it never names the sibling analytics tools (get_top_pages_tool, get_traffic_by_country_tool) that an agent might confuse it with.

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 'Provide either zone_id or zone_name, not both' line gives an invocation constraint, which is useful. However, it says nothing about when to pick this tool over the other analytics siblings, or what happens if no zone is supplied (all params are optional and defaulted).

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds the behavioral constraint that the two keys are mutually exclusive, but says nothing about error behavior when neither is given or what the returned detail includes (though an output schema exists).

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

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

Two short sentences, the primary purpose front-loaded and the input constraint immediately following. No filler and nothing redundant with 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The mutual-exclusion rule is stated, but the definition is silent on the no-argument error case, which leaves a small gap for a lookup tool with two optional inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: both params are nullable/optional with no required field, so the 'either/or, not both' XOR constraint is not captured in the schema itself and must come from the description.

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

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

States a specific verb (Get) plus resource (Cloudflare zone details) and the two lookup keys (ID or name). This distinguishes it from list_zones_tool, which returns multiple zones, though the sibling is not named explicitly.

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 sentence 'Provide either zone_id or zone_name, not both' gives a real mutual-exclusion rule for selecting inputs, which is genuine usage guidance. However, it never states when to prefer this over list_zones_tool or what happens if neither argument is supplied.

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 readOnlyHint annotation already establishes this is a safe read, and the description adds nothing beyond it. It says nothing about pagination, result ordering, or how many apps might be returned, which is the sort of context that would earn credit over the annotation.

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 with no filler. It is efficient, though its brevity is partly under-specification rather than tight editing.

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 an output schema present, return values need not be explained, and the sole parameter is documented. What is missing is operational context: no filtering, pagination, or relationship to the create/get/delete Access app siblings.

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% (the zone_id format is documented as a 32-character hex string), so the schema fully carries parameter meaning. The description only restates the scoping role of the zone without adding format or constraint detail, which is the baseline for full coverage.

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

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

Clear verb+resource ('List the Access applications') and scope ('on a zone'), so the agent knows exactly what it returns. It does not distinguish itself from siblings like get_access_app_tool or list_access_policies_tool, but the resource 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?

No when-to-use, prerequisites, or routing guidance is given. The description never mentions the sibling get_access_app_tool (for a single app) or note that a zone_id is required context, leaving the agent to infer selection on its own.

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 readOnlyHint annotation already declares this is a safe read, and the description adds nothing further - no pagination behavior, no result limits, no note about whether policies are returned in any order. With annotations present the bar is lower, but the description contributes no additional behavioral context.

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 short, front-loaded sentence with zero filler; the verb and resource lead the sentence. Nothing is wasted or buried.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a list operation there is no mention of pagination, ordering, or result-size expectations, leaving those gaps unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both zone_id and app_id are already documented (hex string, UUID) in the schema. The description adds no syntax or filtering meaning beyond that, so the baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('policies on an Access application'), so an agent can tell it retrieves policies rather than creating or deleting them. It does not name the sibling it relates to (e.g. list_access_apps_tool) or clarify scope, so it stops 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?

There is no when-to-use guidance, no mention of prerequisites, and no indication of when to pick this over create_access_policy_tool or delete_access_policy_tool. The agent must infer usage entirely from the name and verb.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context—and it adds none. It says nothing about pagination behavior (despite page/per_page), how filters combine, or result ordering, leaving the annotation as the only behavioral signal.

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 with zero waste. It is efficient, though its brevity reflects under-specification as much as discipline.

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?

An output schema exists, so return values need not be explained, and the read-only annotation covers safety. However, for a six-parameter filtered-list tool sitting among many DNS siblings, the absence of routing and filtering guidance leaves real gaps.

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 every parameter (name, page, type, content, zone_id, per_page) is already documented in the schema. The description adds no filter syntax, combination logic, or defaulting detail beyond that, making 3 the correct 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?

States a specific verb ('List') and resource ('DNS records') scoped to a Cloudflare zone, so the operation is unambiguous. It does not, however, distinguish itself from the sibling get_dns_record_tool (single record) or explain the collection-vs-singleton distinction, so it falls short of a 5.

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 no when-to-use guidance, no exclusions, and never names an alternative. With get_dns_record_tool and the create/update/delete siblings present, an agent gets no help deciding when listing is the right call versus fetching one record.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. Beyond that, the description adds nothing behavioral — no pagination, no result-volume or ordering caveats, no note that filters are optional. It simply restates the 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?

A single short sentence with zero padding and the resource front-loaded. It is efficient, though the brevity edges toward under-specification rather than true conciseness.

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 an output schema present and annotations covering the read-only nature, the description does not need to explain return values or safety. But for a list tool with filtering and sort parameters, it omits any hint about result shape, pagination, or how filters interact, leaving it minimally adequate.

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%: zone_id, order (with accepted values), and status are all documented in the schema itself. The description adds no parameter meaning beyond that, 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: 'List all page rules for a zone.' An agent can immediately tell this is a read/list operation over page rules. However, it does nothing to distinguish itself from the many other list_* rules tools in the sibling set (header rules, URL rewrite rules), relying on the name alone.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as create_page_rule_tool or update_page_rule_tool. The agent must infer from the name that this is the retrieval counterpart to those mutation tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds no behavioral details beyond that, such as pagination, auth requirements, or rate limits. It simply restates the operation with no additional transparency.

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 wasted words. It is appropriately terse for a simple list tool, though it could be slightly more informative 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?

Given the tool's low complexity, full schema parameter coverage, output schema presence, and read-only annotation, the description is sufficient to understand the tool's function. It lacks optional usage context but is not misleading or incomplete for 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%, with zone_id documented as a 32-character hex string. The description adds no meaning beyond the schema, 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?

The description states a specific verb ('List') and resource ('request header modification rules'), clearly distinguishing it from siblings such as set_request_header_rules_tool (write vs read) and list_response_header_rules_tool (request vs response).

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 no guidance on when to use this tool versus alternatives, such as set_request_header_rules_tool for modifications or list_response_header_rules_tool for response rules. It only states what the tool does.

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?

readOnlyHint=true already declares the safety profile, so the bar for added context is lower, but the description adds nothing beyond it: no pagination behavior, no note about whether rules are zone-scoped or account-scoped, no indication of ordering or result limits. It simply restates the 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?

A single short sentence with no waste, and the resource is front-loaded. It is appropriately sized for a simple list operation, though it is arguably too terse to be maximally useful.

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?

Because an output schema exists and parameter coverage is 100%, the missing return-value and parameter detail is forgivable. However, for a read tool in a dense sibling set of list/set/get variants, the absence of any routing or scoping guidance leaves a clear gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter (zone_id) with 100% schema description coverage, including its 32-character hex format. The description adds no semantics beyond the schema, 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?

The description states a clear verb+resource: listing response header modification rules. The scope word 'response' implicitly distinguishes it from the sibling list_request_header_rules_tool, though the description never names that sibling explicitly. An agent can identify the resource but must consult the name/siblings to confirm the read-vs-write distinction.

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 when-to-use, prerequisites, or alternative guidance is provided. The description does not mention that set_response_header_rules_tool is the mutating counterpart or when listing is appropriate versus fetching a single rule. Usage must be inferred entirely from the tool name.

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 readOnlyHint annotation already tells the agent this is a safe read, so the description contributes essentially nothing behavioral on its own. It does not disclose whether results are paginated, whether they are zone-scoped, or whether an empty result is possible. No added context beyond the annotation.

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 short sentence with zero filler and no preamble — nothing to trim. It is front-loaded by nature, though the brevity comes from under-specification rather than disciplined editing.

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?

An output schema exists, so return values need no explanation, and the lone parameter is fully documented in the schema. What is still missing is scope and volume context — whether all rules in the zone are returned or a subset, and how the listing relates to the set_ sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single zone_id parameter carries its own format note ('32-character hex string'), so the schema does the full job. The description adds no parameter meaning, which is the expected baseline of 3 when coverage is complete.

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

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

The description 'List URL rewrite rules.' is a near-verbatim restatement of the tool name and title, which is the textbook tautology case. It identifies a verb and resource, but adds no scope, no filtering behavior, and no differentiation from siblings such as set_url_rewrite_rules_tool.

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 when-to-use guidance, no mention of prerequisites like a required zone, and no pointer to the paired write tool. The agent must infer usage purely from the name. Nothing is misleading, but nothing is stated either.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description doesn't need to re-establish that. It adds the mutually-exclusive zone identifier constraint, but says nothing about pagination, result caps, or scope limits that would matter for a listing endpoint.

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

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

Two short sentences, the purpose front-loaded and the constraint second. No filler, nothing redundant with the title.

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

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

An output schema exists, so return values need not be described, and the tool is a simple two-optional-param read. The description covers the key invocation ambiguity (which identifier to supply); only minor gaps remain around pagination and whether zero arguments is valid.

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 a genuine constraint the schema does not encode: both parameters are nullable/optional in the schema with no mutual-exclusion or at-least-one rule, so "either zone_id or zone_name, not both" is real added meaning.

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

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

States a specific verb ("List") and resource ("WAF custom rules for a zone"), which separates it cleanly from the create/update/delete_waf_rule siblings and from other list_* rule families. It does not explicitly name an alternative, but the resource is unambiguous enough to select without opening a 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 only guidance is "Provide either zone_id or zone_name, not both," which is a calling constraint rather than a when-to-use statement. There is no mention of when to prefer this over, say, get_security_events_tool or the specific rule-type listers, though the resource name makes the intent inferable.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds the authorization scope ('accessible by the API token'), which is genuinely useful context not present in annotations or schema. It does not mention pagination behavior or rate limits, though the schema documents page/per_page.

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 sentence, front-loaded with the action and resource. It contains no redundant restatement of the title or schema details.

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?

An output schema exists and the input schema fully documents filters and pagination. Annotations cover read-only safety. The description adds the token-scope constraint, so nothing critical for correct invocation 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%, with all four parameters (name, page, status, per_page) documented in the schema. The description adds no parameter-level information, 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 ('List') and resource ('Cloudflare zones'), plus the authorization scope ('accessible by the API token'). This distinguishes it from the sibling get_zone_tool, which retrieves a single zone, and from resource-specific list tools like list_dns_records_tool. Clear and specific enough to select 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?

No explicit when-to-use, prerequisites, or alternative tool routing. It does not say when to use this versus get_zone_tool for a specific zone, nor when to filter by name or status. Usage is only implied by the verb 'List'.

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 usefully discloses that every method works on all plans including Free and implicitly frames purge_everything as the blunt instrument, but it never states that purging is irreversible, that it degrades origin load, or any rate-limit/permission behavior an agent should expect.

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

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

Four short sentences, front-loaded with the core action before the method list and the preference rule. The 'Every method works on every plan' sentence is slightly tangential but does carry real information, so no sentence is pure waste.

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?

An output schema exists, so return values need not be described. With 100% schema coverage and a complete method-choice rule, the only gap is the destructive/irreversibility caveat, which is a notch below complete yet still leaves the agent able to call the tool 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 each parameter (tags, files, hosts, prefixes, purge_everything, zone_id) is already documented in the schema. The description reinforces the mutual-exclusivity ('use one of') relationship between the method parameters, which is mild added value, but adds no format or limit detail beyond the schema.

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

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

States a specific verb (purge) and resource (cached content) with scope (Cloudflare's edge). No sibling tool touches cache, so the purpose is unambiguous against the surrounding zone/DNS/WAF/analytics tools.

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

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

Explicitly enumerates the five selectable methods and gives a selection rule: prefer hosts, prefixes, tags or files over purge_everything when only part of a zone is stale. This is real when-to-use guidance, not a restatement of the name.

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 it discloses the single most important trait: this operation replaces ALL existing rules (destructive overwrite). It does not, however, mention auth/permission requirements or whether the call is idempotent.

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

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

Front-loads the operation and its destructive caveat in one sentence, then uses a tight bullet list for the rule structure. Every element earns its place with no filler.

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

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

An output schema exists so return values need no explanation, and the description covers the destructive replace behavior and rule sub-structure. It stops short of describing permissions or how to inspect existing rules before overwriting them.

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 rules items are untyped objects (additionalProperties: true) with no defined properties, so the description adds real meaning by spelling out each rule's fields (expression, description, action, action_parameters) and giving an example. zone_id is covered by the schema. This goes beyond the nominal 100% coverage.

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

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

Specific verb ('Set') plus resource ('request header modification rules'), and it explicitly notes the scope ('replaces all existing rules'). This cleanly distinguishes it from list_request_header_rules_tool (a read) and set_response_header_rules_tool (a different resource).

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 replace semantics imply a full-overwrite use case, but there is no explicit when-to-use guidance, no routing to siblings (e.g., list existing rules first, or use set_response_header_rules_tool for response headers). Usage 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 full behavioral burden. It usefully discloses that the tool replaces ALL existing rules (a destructive trait), which is meaningful. However, it omits permission/auth requirements and whether changes are reversible, leaving notable gaps for a mutation 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?

Front-loads the core action and replace semantics, then lists rule fields compactly with bullets. No wasted sentences, though the header nesting example is slightly cryptic.

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?

An output schema exists, so return values need not be explained, and both parameters and rule structure are covered. The remaining gap is auth/permission context and the exact action_parameters shape, but the definition is otherwise complete for calling the 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 coverage is 100% (baseline 3), but the description goes further by documenting the internal shape of each rule object (expression, description, action, action_parameters with headers). Since the schema only says 'List of rule definitions' with additionalProperties:true, this field-level detail adds real semantic value.

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 ('Set') and resource ('response header modification rules'), and explicitly notes the replace semantics. An agent can distinguish it from set_request_header_rules_tool and list_response_header_rules_tool purely from the description.

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 '(replaces all existing rules)' note implies destructive use and gives a warning, but there is no explicit when-to-use guidance or routing to siblings such as list_response_header_rules_tool for reading before writing. Usage must be inferred.

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 disclosure burden. It surfaces one genuinely important trait ('replaces all existing rules'), which tells the agent this is a destructive full-overwrite rather than an append. However, it omits auth/permission requirements, idempotency, and rate-limit behavior expected of an unannotated mutation 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 destructive replacement warning is front-loaded in the opening line, then a tight bulleted list defines the rule shape. Every sentence earns its place with no filler, and the format is easy for an agent to parse.

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?

An output schema exists, so return values need no explanation, and the description covers the rule payload shape and the overwrite semantics an agent needs before calling. It is nearly complete, with only environment/prerequisite context left unstated.

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, and the description earns above that by documenting the structure of the otherwise opaque 'rules' array items (expression, description, action, action_parameters with a concrete JSON example). This compensates for the schema leaving rule items as bare 'additionalProperties: true' objects.

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 ('Set URL rewrite rules') and adds a critical scope note that it 'replaces all existing rules', which cleanly separates it from the list_url_rewrite_rules_tool sibling. It does not explicitly name an alternative tool, but the 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?

The parenthetical 'replaces all existing rules' implies full-replacement usage and is the key operational context, but there is no explicit when-to-use vs. when-not, no mention of a sibling alternative, and no stated prerequisites. Usage is implied rather than guided.

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, and it discloses almost nothing. It implies mutation of an existing record but never states whether this is a partial or full update, whether omitted fields are preserved, whether values are reversible, what permissions are required, or whether the change propagates immediately.

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 with zero padding, which is structurally clean. But for a 9-parameter mutation tool this brevity reads as under-specification rather than discipline, since no sentence earns extra value by being absent.

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?

An output schema exists so return values need not be explained, but for a mutation tool with no annotations and 9 parameters (2 required) the description leaves critical gaps: it never mentions that zone_id and record_id are required, nor that the remaining fields are optional partial-update inputs.

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% across all 9 parameters, so the schema already documents every field's meaning. The description adds no parameter-level information (e.g., that only supplied fields change), 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?

The description gives a specific verb and resource ('Update an existing DNS record'), so an agent knows this mutates a record rather than creating or deleting one. However, it adds essentially nothing beyond the tool name and title, which are near-identical restatements, and it offers no detail that distinguishes it from the sibling update_page_rule_tool / update_waf_rule_tool pattern beyond the resource noun.

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 on when to use this tool versus create_dns_record_tool, delete_dns_record_tool, or get_dns_record_tool. It does not state that the record must already exist, nor mention any prerequisite such as fetching the record first to obtain record_id.

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 and discloses nothing: not what happens to fields omitted from the update, not whether the operation requires specific permissions, not whether changes are reversible. For a mutation tool with zero annotation coverage this is a serious 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?

A single front-loaded sentence with zero padding, so it is not verbose. It is, however, thin rather than efficiently dense — the brevity reflects under-specification rather than crisp information packing.

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?

An output schema exists, so return values need not be explained, and the schema is fully documented. But this is a 6-parameter mutation tool with no annotations and no guidance on partial-update semantics or required versus optional behavior, leaving the agent without enough context 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%, and each parameter (zone_id, rule_id, status, actions, targets, priority) is documented in the schema itself. The description adds nothing beyond the schema, 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?

The description states a specific verb (Update) and resource (page rule), so the agent knows exactly what kind of operation this is. However, it does nothing to distinguish itself from its obvious siblings (create_page_rule_tool, delete_page_rule_tool, list_page_rules_tool) or the parallel update_waf_rule_tool, so it stops short of a 5.

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 on when to use this tool versus create/delete/list page rules, no prerequisites, and no conditions that select it over alternatives. The word 'existing' faintly implies the rule must already exist, but no actual usage guidance is given.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers almost nothing beyond implying mutation. It does not disclose whether omitted optional fields (all default to null) preserve or clear existing values, whether the operation requires elevated permissions, or how a missing/unknown rule_id is handled.

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

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

Two short sentences with the core operation front-loaded and the constraint immediately after. There is no filler, though the overall thinness reflects missing content rather than successful economy.

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 partial-update mutation tool with seven optional/defaulted parameters and no annotations, the description omits the most decision-relevant facts: null-vs-preserve semantics for unset fields, auth requirements, and failure behavior. The output schema covers return values, so that gap is excused, but the mutation semantics are not.

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 a genuinely new constraint the schema cannot express: zone_id and zone_name are mutually exclusive ('provide either... not both'), while both are merely nullable in the schema. That is real added meaning beyond the field descriptions.

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

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

States a specific verb (update) and resource (WAF custom rule) with the qualifier 'existing', which implicitly distinguishes it from create_waf_rule_tool and delete_waf_rule_tool. It does not name siblings explicitly, so the differentiation relies on the reader's inference rather than direct routing.

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 only guidance is the zone_id/zone_name mutual exclusion, which is a parameter constraint rather than usage context. It never says when to reach for this tool versus list_waf_rules_tool, create_waf_rule_tool, or delete_waf_rule_tool, nor what prerequisites (e.g., rule must already exist) apply.

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