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

With no annotations, the description carries the full behavioral burden and does well: it discloses that NPM stores rules and credentials, that item passwords are write-only and cannot be read back, that the created object is returned, and what dry_run does. It does not state permission/auth requirements or whether the operation can fail partway, which is the only notable gap.

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

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

Four tight sentences, front-loaded with purpose, then routing, then behavioral caveat, then the dry_run escape hatch. Every sentence contributes and nothing is padded.

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

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

An output schema exists, so the return-value sentence is mild redundancy rather than a necessity, but the write-only password and dry_run notes are genuinely useful for a mutation tool. Auth/permission prerequisites are the one omission for a create operation with no annotations.

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 every parameter already carries its own description; the baseline is 3. The description reinforces two of them (write-only passwords, dry_run preview) but adds no syntax, format, or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Create an access list') and immediately specifies its contents (IP allow/deny rules and basic-auth users). It explicitly names the sibling update_access_list as the tool for an existing list, so an agent can distinguish it without opening either 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?

Names the alternative explicitly ('use update_access_list to change an existing list') and gives the selecting condition, plus a preview path (dry_run=True) for verifying before committing. Nothing about when to pick this over its sibling is left to inference.

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

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

No annotations, so the description carries the full burden: it discloses that the request is sent to NPM, may contact Let's Encrypt, what is returned (cert object with ID, domains, status), and that dry_run previews without mutating. It omits auth/permission requirements, idempotency on re-request, and Let's Encrypt rate-limit implications, which matter for a certificate-issuance 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?

Four tight sentences, front-loaded with purpose followed by routing guidance, behavior, and return shape. Slightly crowded by the return-value sentence, which is redundant with the output schema.

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

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

For a mutation tool with no annotations and an existing output schema, the description covers purpose, alternative, external side effects, and preview mode. Remaining gaps are low-severity (permissions, rate limits, failure behavior) but not blocking for correct selection.

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 all four parameters are already documented, and the description only restates dry_run semantics already present in the schema. It adds no syntax, constraints, or interaction details (e.g. dns_challenge vs email) beyond structured data.

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+resource ('Request a new Let's Encrypt certificate for the supplied domains') with an explicit statement of what it does not do, and it names the closest sibling create_proxy_host_with_letsencrypt so the agent can distinguish the two without reading schemas.

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

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

Gives an explicit when-to-use condition ('when a certificate is needed without creating a proxy host') and names the alternative plus its differentiating behavior (create_proxy_host_with_letsencrypt also creates an HTTPS-forced host). No inference required.

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

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

No annotations are provided, so the description carries the full burden; it discloses that NPM persists the host config and applies it through normal config handling, that dry_run returns a preview without changing NPM, and what the response contains. It stops short of permission/auth requirements or reversibility, but the mutation behavior and non-destructive escape hatch are clearly conveyed.

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 sentences, each earning its place: purpose, tool selection, persistence/return behavior, and preview mode. The most decision-relevant routing rule is front-loaded right after the purpose.

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 an output schema present, the agent needs purpose, selection rule, and mutation semantics, and all are supplied. Return values are described even though the output schema already covers them, so nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in the schema and the baseline is 3. The description only reinforces dry_run behavior and the no-certificate framing, adding little beyond what the schema already says.

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 proxy host') plus the routing scope ('routes the supplied domains to an HTTP or HTTPS upstream'). It explicitly names the sibling create_proxy_host_with_letsencrypt as the contrasting option, so an agent can distinguish the two without opening schemas.

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

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

Gives a direct selection rule: use this when configuring proxying without a certificate, otherwise use create_proxy_host_with_letsencrypt to request one and force HTTPS. It also explains the dry_run preview path, so both the choice-of-tool and the safe-invocation path are covered.

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

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

With no annotations, the description carries the burden and does well: it discloses the certificate request side effect, failure reporting via failed_step and created certificate, the success return shape, and dry_run preview behavior. It omits auth/rate-limit context, which would matter for a Let's Encrypt operation, but the core behavioral traits are covered.

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 composite purpose, then usage, then behavioral details in a tight set of sentences. Every sentence earns its place and nothing is 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 10-parameter mutation with a certificate side effect, no annotations, and an existing output schema, the description covers purpose, alternative selection, failure behavior, return summary, and dry_run. Missing auth and Let's Encrypt rate-limit notes are minor gaps given the output schema handles return values.

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 all 10 parameters thoroughly. The description mentions dry_run semantics but adds no parameter meaning beyond what the schema provides, consistent with the baseline of 3 when structured data does 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 and composite resource: request a Let's Encrypt certificate then create a proxy host with HTTPS forced. It explicitly distinguishes itself from create_proxy_host, so an agent can select it without opening either schema.

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

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

Gives explicit when-to-use guidance and names the alternative create_proxy_host with the exact conditions that favor it: a certificate already exists or HTTPS forcing is not wanted. No inference is required.

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

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

With no annotations, the description carries the full burden and does add value — it discloses that no certificate is requested when a certificate_id is referenced, and that dry_run previews without changing NPM. However, it omits permissions/auth requirements, whether the operation is reversible, and side effects of creation, which are material for an un-annotated 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?

Five sentences with the purpose front-loaded ahead of the sibling routing and behavioral notes. Slightly redundant with schema on dry_run, but generally tight and well-ordered.

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 the return-value sentence is supplementary rather than required; the description nonetheless acknowledges the returned host object. For a 9-param mutation tool with no annotations, it is nearly complete, missing only permission/prerequisite context.

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 baseline is 3; the schema documents all nine parameters including defaults and valid HTTP codes. The description reinforces the cert-reference and dry_run semantics but adds little beyond what the schema already provides.

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

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

States a specific verb+resource ('Create a host that redirects requests for domains to a destination') and immediately contrasts with the sibling create_proxy_host. An agent can distinguish it from create_proxy_host and create_stream 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?

Explicitly routes usage: 'Use this for URL redirection; use create_proxy_host to forward requests to an upstream server.' The condition selecting the alternative is stated clearly. It does not cover the other redirection-host lifecycle siblings, but the core when-to-use vs alternative is fully specified.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that NPM stores the configuration and applies it through normal config handling, that it returns the created object with ID/ports/protocol flags, and that dry_run previews without mutating. It omits auth/permission requirements and any restart or propagation behavior, but that is a modest gap for a straightforward create.

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 tight sentences, front-loaded with the core action before the routing alternative and the return/dry-run notes. Slightly redundant in restating the return payload and dry_run behavior that the schema and output schema already convey.

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 explaining the return object is optional, and the create is a single flat mutation with fully documented parameters. What remains thin is permission/prerequisite context, which matters for a create tool with no annotations.

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 is already documented in the input schema, establishing a baseline of 3. The description only echoes dry_run semantics (already in the schema) and refers generically to 'protocol flags' rather than adding new meaning to tcp_forwarding/udp_forwarding defaults.

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) plus resource (TCP/UDP port forward) and the exact scope (incoming port to destination host and port). It explicitly distinguishes itself from the sibling proxy-host tools by naming the alternative category for HTTP/HTTPS domain 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?

Gives an explicit selection rule: use this for raw TCP or UDP forwarding, use proxy-host tools for HTTP/HTTPS domain routing. It also names the dry_run preview mode as a safe alternative to committing the create, so the agent knows both the routing decision and the pre-flight option.

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

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

With no annotations, the description carries the full burden and does so: it declares the operation is permanent and irreversible, warns that referencing hosts may be affected, states the return value (True on success), and documents the dry_run preview behavior. This is exactly the destructive-operation context an agent needs.

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 tight sentences, each earning its place: action, alternative, prerequisite, consequences, return value, and preview flag. The destructive action is front-loaded, followed by the safe alternative.

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 description still notes the True-on-success return, and all the operational risk of an irreversible delete is disclosed. Nothing needed to invoke this tool safely 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% and both parameters are already documented in the schema, including dry_run's preview semantics and the ID's origin. The description reinforces this but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource combination ('Permanently delete an access list by ID from NPM') and explicitly distinguishes itself from update_access_list and list_access_lists. An agent can select this tool without opening any sibling schema.

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

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

Gives explicit routing: use update_access_list to keep the list and change rules, and confirm the ID with list_access_lists first. Both the 'when to use this' and the 'when to use something else' conditions are stated, plus a prerequisite step.

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

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

With no annotations, the description carries the full burden and does well: it discloses irreversibility ("cannot be undone"), the external side effect ("NPM applies the configuration change"), the return value, and a safe-preview mode via dry_run. It stops short of stating required permissions or auth, but the destructive/reversibility profile is fully covered.

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

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

Three tight sentences with the destructive action front-loaded, then the alternative, then the safety valve. Every sentence carries information an agent needs; 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?

For a two-parameter destructive tool with an output schema present, the description covers the destructive semantics, the alternative path, the ID source, and the dry-run escape hatch. Nothing required 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%, so the baseline is 3. The description's notes on id (confirm via the list tool) and dry_run (preview the exact request) largely restate what the schema already documents, adding no new syntax, format, or constraint detail.

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 names a specific verb and resource ("Permanently delete a proxy host by ID") and clarifies scope by stating it removes "its configured domain routing from NPM." An agent can distinguish it from update_proxy_host or disable_proxy_host without opening any schema.

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

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

It explicitly routes to the alternative ("Use disable_proxy_host to stop routing while keeping the host") and names a helper for obtaining the required ID ("list_proxy_hosts helps confirm the ID"). When-to-use, when-not-to-use, and an alternative are all present.

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

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

No annotations are provided, so the description carries the full burden and does so richly: irreversible ('cannot be undone'), applies an NPM config change, returns True on success, and a dry_run preview mode. This is exactly the behavioral context an agent needs for a destructive mutation.

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 tightly packed sentences: action/effect front-loaded, then alternatives, then reversibility/return/preview. No filler; every clause earns its place.

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

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

For a destructive single-resource delete with an output schema present, the description covers irreversibility, alternatives, ID sourcing, return value, and dry-run preview. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description still adds value by explaining the dry_run semantics ('preview the exact request without changing NPM') and the id source, slightly above the baseline 3.

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

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

States a specific verb (delete) and resource (redirection host) with the scope clarified as 'by ID' and the effect stated precisely ('removing its redirect configuration from NPM'). Clearly distinguishable from siblings like disable_redirection_host.

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 names the non-destructive alternative (disable_redirection_host to retain while stopping redirects) and points to list_redirection_hosts to resolve the ID. This gives clear when-to-use-this-vs-that 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?

With no annotations, the description carries the full behavioral burden and does so well: permanent deletion, immediate cessation of port forwarding, irreversibility, and a dry_run preview path. It omits auth/permission requirements and any side effects on related configuration, which keeps it below 5.

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

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

Front-loaded with verb and resource, then risk, then prerequisite, then return and preview behavior — each clause 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?

For a destructive tool with no annotations, the description covers irreversibility, immediate effect, safe-preview option, and a confirmation step; an output schema already documents the return value. Nothing essential 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 coverage is 100%, so both id and dry_run are already documented in the schema; the description largely restates the dry_run preview behavior. It adds only the minor hint that the ID comes from the matching list tool. 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?

States a specific verb, resource (delete a TCP/UDP stream by ID), and the concrete effect on NPM. An agent can immediately distinguish this from delete_proxy_host, delete_access_list, and delete_redirection_host by the resource named.

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

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

'List streams first to confirm the ID' gives an explicit prerequisite step pointing at the list_streams sibling, which routes the agent correctly. There is no explicit when-not or alternative-selection guidance, but the context for use is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutation ('changes NPM host state'), the operational consequence ('stops that host from serving traffic'), the reversibility profile ('retaining its configuration'), and a safe preview mode. It does not mention permission/auth requirements or idempotency, which is the only remaining 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?

Five short, front-loaded sentences with no filler; the core action leads. The final dry_run sentence largely duplicates the schema's own description, which is the only wasted motion.

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

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

For a two-parameter mutation with full schema coverage and an output schema, nothing needed for correct invocation is missing. Return-value explanation is unnecessary given the output schema, and the description's one-line note about the updated host object is a harmless bonus.

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 (id, dry_run) are already fully documented in the schema; the description's restatement of dry_run adds no new syntax or format detail. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Disable a proxy host by ID') plus the key semantic distinction from the obvious sibling: configuration is retained rather than removed. An agent can immediately tell it apart from delete_proxy_host and from enable_proxy_host.

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

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

Explicitly routes to alternatives with conditions: delete_proxy_host for removal, list_proxy_hosts to check status, dry_run=True to preview. This is exactly the when/when-not/alternatives structure that removes inference.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that the configuration is preserved, that the redirect stops being served, that the change is applied to NPM, and that dry_run previews without mutating. It does not mention required permissions, reversibility via enable_redirection_host, or side effects on dependent hosts, leaving modest gaps.

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

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

Front-loaded with the action and its key distinction, then the alternative tools, then the side effect and return value. Slightly redundant: 'stops the redirect from being served' and 'applies the configuration change' cover overlapping ground, and the return-value sentence is unnecessary given the output schema.

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

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

For a two-parameter mutation with full schema coverage and an output schema, the description supplies everything the agent needs: the effect, the config-retention semantics, sibling routing, and the dry_run safety valve.

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 id and dry_run are already documented in the schema, and the description's dry_run explanation largely restates the schema text. The phrase 'by ID' confirms the identifier's role but adds no format or sourcing detail beyond what the schema provides, 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 ('Disable a redirection host by ID') and immediately clarifies the semantic distinction from deletion: configuration is retained in NPM while the redirect stops being served. This separates it cleanly from delete_redirection_host without needing siblings opened.

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?

Explicit routing is provided: use delete_redirection_host to remove the host, list_redirection_hosts to check status, and this tool to disable it. The dry_run option is also framed as a preview path, so an agent has clear when-to-use and when-not-to-use 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?

With no annotations, the description carries the full burden and does a good job: it discloses that NPM stops forwarding while disabled, that configuration is retained, that the updated stream object is returned, and that dry_run gives a no-op preview. Auth/permission requirements and rate limits are not mentioned, keeping it out of the top tier.

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

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

Front-loaded with the primary action and scope, then alternatives, then the dry_run escape hatch. Every sentence carries distinct information 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 no explanation, and the description still names the returned object. The main residual gap is the absence of any note on required permissions or the effect on in-flight connections, but for a simple toggle this is largely 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%, so the schema already documents both id and dry_run. The description restates dry_run's preview behavior but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Disable a TCP/UDP stream by ID') plus the key scope detail that forwarding configuration is retained. It explicitly contrasts with delete_stream (removal) and list_streams (status), so an agent can place it precisely among its siblings.

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

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

Names delete_stream as the alternative for permanent removal and list_streams for checking status, which gives clear routing guidance. It omits the symmetrical when-to-re-enable guidance and any prerequisites, so it falls just short of the full when/when-not treatment.

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

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

With no annotations, the description carries the full burden and does well: it discloses that this mutates NPM host state, that the configuration is applied, that the updated host object is returned, and that dry_run=True previews the request without changing NPM. It omits permission/auth requirements and idempotency behavior, leaving some behavioral gaps.

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 tight sentences, front-loaded with the primary action and effect before the alternative-tool routing. The 'Returns the updated host object' sentence is slightly redundant given the output schema exists, but overall there is little 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 explained, and the description still covers mutation effect, dry_run preview, and tool routing. For a two-parameter mutation tool with no annotations, this is nearly sufficient, with only auth/permission context missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; the description restates the ID and dry_run preview without adding format or edge-case detail. 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?

States a specific verb (enable) and resource (proxy host), scoped by ID, with the effect spelled out: NPM resumes serving the configured domain routing. It clearly contrasts with update_proxy_host and list_proxy_hosts, so an agent can pick it apart from siblings 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?

Names two alternatives and their conditions ('use update_proxy_host to change host settings; use list_proxy_hosts to confirm status and ID'), giving clear routing context. It stops short of an explicit exclusion against the obvious complement, disable_proxy_host, so it's strong but not fully exhaustive.

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

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

With no annotations, the description carries the burden and does well: it discloses that this mutates NPM state and applies configuration, that it returns the updated host object, and that dry_run previews the exact request. It omits permission/authorization requirements and reversibility specifics (e.g., whether disable_redirection_host undoes it), keeping it short of a 5.

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

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

Front-loads the core action, then alternatives, then behavioral notes and the dry_run escape hatch. Each sentence earns its place, though the return-value and dry_run statements slightly overlap with structured fields, preventing a full 5.

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-value detail is not strictly required, and the change semantics plus dry_run preview give an agent enough to call it correctly. Minor gap is the absence of permission/reversibility notes for a mutation tool with no annotations.

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 id and dry_run are already fully documented in the schema, giving a baseline of 3. The description echoes the dry_run preview behavior and the id's likely source (matching list tool), adding marginal value but no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (enable a disabled redirection host by ID) and explicitly explains the effect: NPM serves its redirect again. It also names what it is not, routing editing to update_redirection_host and status checks to list_redirection_hosts, so an agent can distinguish it from siblings without opening schemas.

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 names alternatives and their conditions: update_redirection_host for destination/redirect-code edits and list_redirection_hosts for status, with the implicit condition that it applies to a currently disabled host. It also flags dry_run as the preview path, covering when-not-to-mutate.

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

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

With no annotations, the description carries the full burden and does disclose the mutation ('changes the stream state in NPM'), the return value, and a dry_run preview that avoids changing NPM. It omits permission/auth requirements and whether the operation is idempotent on an already-enabled stream.

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

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

Front-loaded with the action and effect, followed by routing and the dry_run tip. Efficient overall, though 'This changes the stream state in NPM' partly restates the opening sentence.

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 details are covered, and the description still notes the updated stream object is returned. For a two-parameter mutation with no annotations, it supplies the safety and routing context an agent needs, lacking only auth/idempotency details.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the schema does the heavy lifting. The description adds the practical meaning of dry_run (preview the exact request) but nothing about the id format beyond what the schema says.

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 (Enable), resource (TCP/UDP stream), and the effect (NPM forwards its incoming port again). It also names the sibling tools it is not (update_stream, list_streams), so an agent can distinguish it without opening schemas.

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?

Routes the agent explicitly: use update_stream for ports/protocol flags and list_streams to check status. It implies the trigger condition (a disabled stream) but does not spell out when to prefer disable_stream over enable_stream beyond 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 burden and adds a key behavioral constraint: 'NPM does not return stored item passwords, so password values cannot be read back.' It also implies a read-only fetch and describes the return structure. It does not cover authentication or error behavior, but for a read-only getter this is a strong 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?

The description is front-loaded with the core action and efficiently packs purpose, usage guidance, a limitation, and return details into four sentences. The final sentence listing return fields is somewhat redundant given the output schema, but otherwise every sentence earns its place.

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

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

Given a simple one-parameter getter with an output schema, the description covers purpose, when to use it, a runtime limitation, and expected content. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the sole 'id' parameter. The description reinforces that an ID is required but adds no syntax, format, or sourcing details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb ('Fetch'), resource ('access list'), and scope ('by ID'), and explicitly differentiates from the sibling list_access_lists by directing discovery use there. It also specifies the contents returned (client rules, basic-auth user metadata), leaving no ambiguity about what the tool does.

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

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

It states exactly when to use this tool ('for detailed rules') and names the alternative ('use list_access_lists to discover IDs'), providing the condition that selects between them. No inference is required to choose the right tool.

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

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

With no annotations provided, the description carries the burden and does good work: it declares read-only behavior and the important side-effect guarantee that it 'does not reload Nginx' (a meaningful trait for a reverse-proxy config tool). It omits error behavior for an unknown ID and any auth/permission context, keeping it short of a 5.

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

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

Three sentences, each earning its place: purpose, sibling routing, and behavioral/return disclosure. Front-loaded with the primary action and no redundant 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?

For a single-parameter read tool with full schema coverage and an output schema, the definition covers purpose, alternative routing, safety profile, and return contents. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the single id parameter is documented in the schema as coming 'from the matching list tool.' The description adds no syntax or format beyond that, so the baseline 3 for schema-driven parameter documentation 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 ('Fetch one proxy host by ID') plus the scope of returned data (configured fields and current status). It explicitly distinguishes itself from the sibling list_proxy_hosts, so an agent can route correctly without opening either schema.

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

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

Gives an explicit when-to-use ('details about one host') and names the alternative with its own condition ('use list_proxy_hosts to find IDs or inspect all hosts'). The selection logic between the two tools is fully spelled out.

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 safety burden and does so by declaring 'This is read-only and does not change NPM.' It also enumerates the returned fields (domains, destination, redirect code, status), which adds context. It stops short of stating auth requirements or what happens when the ID is invalid/missing.

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

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

Three tight sentences with zero waste: purpose first, then routing guidance, then behavior and return shape. Everything is front-loaded.

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 the description needn't detail return values, and the one required parameter is fully documented. For a simple read-only single-fetch tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single id parameter is already documented with its source ('from the matching list tool'), so the schema does the heavy lifting. The description adds no extra format or constraint details beyond that, so baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (one redirection host) plus the key data it carries (destination and status). It explicitly distinguishes itself from list_redirection_hosts, so an agent can route between single-fetch and discovery without opening schemas.

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

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

Gives a direct when-to-use rule ('Use this for a single redirect') and names the alternative tool plus the reason to prefer it ('to discover IDs or inspect all redirects'). No ambiguity about which sibling to call.

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

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

No annotations are provided, so the description carries the behavioral burden, and it does declare the safety profile ('read-only and does not change NPM'). It still omits error behavior for a nonexistent/invalid ID, which matters for a fetch-by-ID tool with no annotation coverage.

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

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

Three tight sentences, purpose front-loaded before the sibling routing. The final return-field sentence partially duplicates the existing output schema, so it does not fully earn 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?

An output schema exists, so return values are covered structurally; combined with purpose, sibling routing, and the read-only declaration, an agent has everything needed to call this correctly.

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

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

The single parameter is fully documented in the schema (100% coverage) including its origin ('from the matching list tool'), so the schema does the heavy lifting. The description adds only 'by ID', which is baseline-level 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?

Specific verb (Fetch) plus resource (one TCP/UDP stream by ID) with the returned content named (forwarding ports, protocol settings). It is immediately distinguishable from list_streams and from the update/delete stream siblings.

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 scopes itself to a single stream and names the alternative: 'use list_streams to find IDs or inspect all streams.' The condition selecting the sibling is stated, not 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?

No annotations are provided, so the description carries the full burden and does disclose two meaningful traits: it is read-only and does not expose stored passwords. It stops short of covering pagination, result limits, or ordering for a potentially large collection.

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

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

Three tight sentences with no filler; the core action is front-loaded, followed by ID-lookup guidance and the read-only disclosure. Every sentence earns its place.

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

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

An output schema exists, so return-value documentation is unnecessary and the brief mention of returned access-list objects suffices. The read-only/password note compensates for the absent annotations, leaving only minor gaps around result volume or paging.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description adds no parameter details, but none are needed.

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 access lists configured in NPM') and immediately distinguishes itself from the sibling get_access_list, which returns one list with its rules. An agent can tell the two apart without opening either schema.

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

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

Explicitly states when to use it ('to find IDs before fetching, updating, or deleting a list') and names the alternative with its selecting condition ('use get_access_list for one list with its rules'). This routes the agent correctly with no inference required.

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

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

With no annotations provided, the description carries the full burden, and it does disclose that the operation is read-only and makes no certificate request — an important disambiguation from its write siblings. It also previews the return shape, though it omits any pagination or volume limits.

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 followed by usage routing and then the behavioral/safety note. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes the returned fields. For a zero-parameter read tool this is 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?

The tool takes zero parameters, so per the baseline this is a 4. There is nothing parameter-related the description needs to compensate for.

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 SSL certificates known to NPM') plus scope detail on expiry information. It clearly distinguishes itself from the sibling write tools create_letsencrypt_cert and renew_certificate by name.

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

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

Explicitly tells the agent to use this to inspect available certificates and names the two alternatives with their roles ('requests a new certificate', 'renews an existing one'). This fully routes the agent between the read and write paths.

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, this description carries the full burden and does so reasonably: it declares the operation is non-mutating ('does not change NPM or request a certificate'), effectively a read-only hint. It also sketches the return payload, though it omits pagination/rate-limit behavior for what could be a large list.

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

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

Three sentences, each earning its place: purpose, usage/routing, and non-goals/returns. Front-loaded with the core verb+resource so an agent grasps it immediately.

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

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

For a zero-parameter list tool with an output schema, the description covers purpose, routing, and safety. Return-value detail is partly redundant given the output schema, and pagination/volume behavior is unaddressed, but nothing critical is missing for correct invocation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. No misleading parameter claims are made.

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 proxy hosts configured in NPM') plus the scope of returned data ('including their current status'). This clearly separates it from get_proxy_host (single), create_proxy_host, and the other list_* siblings for certificates/access lists/streams.

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

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

Explicitly gives the primary use case: 'find host IDs before get, update, enable, disable, or delete operations', which names the downstream siblings that depend on this output. It also excludes non-goals ('does not change NPM or request a certificate'), though it never names an alternative list tool or when NOT to use this one.

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

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

With no annotations, the description carries the full behavioral burden and does so in part: it declares 'This is read-only and does not request certificates,' which tells the agent there are no side effects or certificate issuance. It also discloses the returned fields, though it omits pagination or result-size behavior for a potentially unbounded list.

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

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

Three sentences, front-loaded with the core action, then usage routing, then a return summary. Every sentence adds distinct information with no filler or repetition 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 the description is not obliged to detail return values, yet it briefly previews them ('domains, destination, redirect code, and status') as a convenience. Combined with the read-only guarantee and ID-discovery guidance, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, which per the rubric sets a baseline of 4. There is nothing for the description to clarify beyond confirming this is an unfiltered list, and it does not misrepresent any input.

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 ('List configured redirection hosts') plus the scope of what is returned ('their current status'). It also distinguishes itself from the sibling domain of proxy hosts by noting 'proxy hosts handle upstream reverse proxying,' so an agent can separate list_redirection_hosts from list_proxy_hosts without reading either 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?

It gives an explicit when-to-use workflow: 'Use this to find IDs before fetching, changing, enabling, disabling, or deleting a redirect,' which maps directly onto the sibling get/update/enable/disable/delete redirection tools. The proxy-host exclusion sentence further sharpens the boundary between alternatives.

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

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

With no annotations, the description carries the full burden and does well: "This is read-only and does not change NPM" declares the safety profile, and it names the return fields (IDs, ports, protocols, status). It omits auth requirements or pagination/result-size limits, which would matter for a list endpoint against a large config.

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

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

Three sentences, each earning its place: what it lists, when to use it, and what it returns / its safety profile. The most decision-relevant information (scope and the ID-lookup purpose) is front-loaded.

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 parameterless read-only list tool this is complete: purpose, usage trigger, safety profile, and return contents are all covered, and an output schema exists so return values need no further elaboration in the description.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-related the description could add or omit; the 100% schema coverage is trivially satisfied by an empty object.

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 configured TCP/UDP streams") plus the scope detail "and their current status," which separates it cleanly from the single-item sibling get_stream. An agent can tell what it retrieves without opening the schema.

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

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

Explicitly says to use it "to find stream IDs before fetching, changing, enabling, disabling, or deleting a port forward," which routes the agent from this lookup tool to the downstream mutation siblings. It doesn't name any sibling tool directly (e.g. get_stream for a single stream), so it stops short of the full 5.

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

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

With no annotations, the description carries the burden and does well: it discloses that renewal triggers NPM certificate renewal processing, may contact the certificate provider, returns the operation result, and that dry_run previews without changing NPM. It omits auth/permission requirements and idempotency or rate-limit behavior, so it falls short of full 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?

Four sentences, front-loaded with the core action and the sibling routing, and each sentence carries information. The dry_run behavior is stated once in the description and once in the schema, a mild redundancy that keeps it from a 5.

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

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

For a 2-parameter mutation with an output schema, the description covers side effects, provider contact, dry_run preview, and return shape, so an agent has what it needs. Auth/permission expectations are the only notable omission.

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 are already documented in the schema (id sourced from list_certificates, dry_run preview behavior). The description restates both without adding syntax or format detail, 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 ('Request renewal of an existing certificate by ID') and explicitly names the sibling tool create_letsencrypt_cert that handles the new-certificate case. An agent can distinguish it from siblings like create_letsencrypt_cert and list_certificates without opening any schema.

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

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

Gives explicit routing: use this for a certificate already managed by NPM, use create_letsencrypt_cert to request a new certificate. The condition that selects this tool over the alternative is unambiguous.

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

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

With no annotations, the description carries the full burden and does well: it discloses that NPM receives merged writable fields, that item passwords are write-only and unreadable, that dry_run previews the request, and that the updated object is returned. It omits auth/permission requirements needed to perform the update.

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 tightly scoped sentences, front-loaded with purpose then alternative then behavior. Minor redundancy between the items/clients mention in sentence one and the schema-level detail, but 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?

For a 7-param mutation tool with an output schema, the description covers the operation, merge semantics, write-only constraint, and dry_run. The only real gap is permission/auth prerequisites, which annotations would normally supply but here are absent.

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 all seven parameters are already documented — including write-only passwords, dry_run, and the 'omit to keep current value' semantics. The description largely restates items/clients and the dry_run behavior, adding little beyond the schema 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 ('Update'), resource ('an existing access list by ID'), and the writable surface ('client rules and basic-auth users'), so an agent can immediately distinguish it from list/get/create siblings.

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

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

Explicitly routes the agent: 'Use this to edit access controls; use delete_access_list to remove a list,' and adds a dry_run preview path. It stops short of contrasting with create_access_list, but 'existing access list by ID' implies the boundary.

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 disclosure burden well: it explains that NPM receives merged writable fields (partial-update semantics), that no certificate is requested, and that the updated host object is returned. It does not cover permission/auth requirements or whether the change is reversible, which is the only remaining 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?

Four tight sentences, front-loaded with the verb+resource, then the alternative routing, then behavioral facts. No filler and nothing repeated.

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?

All 12 parameters are documented in the schema, an output schema exists so return values need not be explained, and the description adds the key merged-update and no-cert behaviors. Only auth/permission prerequisites are absent, which is minor for this tool size.

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

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

Schema description coverage is 100% and each parameter already documents 'omit to keep the current value', so the baseline is 3. The description reinforces the merge semantics with 'merged writable host fields' and highlights dry_run, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb, resource, and scoping ('Update writable settings on an existing proxy host by ID'), and explicitly distinguishes itself from the enable/disable siblings. An agent can route to the correct tool without opening any schema.

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

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

Gives explicit when-to-use ('change routing or options') versus when-not ('status only' -> enable_proxy_host/disable_proxy_host), and names the alternatives directly. The dry_run preview hint adds a further condition for safe invocation.

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

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

With no annotations, the description carries the full burden and does well: it discloses merge semantics ('NPM receives the merged writable fields'), the dry_run preview capability, and the shape of the result. It does not mention permissions or reversibility, which would be the remaining gap 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?

Three tight sentences with no filler; the core operation, the sibling routing, and the dry_run escape hatch are each front-loaded in priority order.

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 10-parameter, single-required-id update tool with an output schema present, the description covers operation, alternatives, merge behavior, and the dry_run preview. Nothing an agent needs to invoke it correctly is missing, and return values are handled by the output schema.

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 field already documents its 'omit to keep the current value' behavior, so the description's merge note largely restates the schema. It adds only the high-level framing of which settings are relevant (domains, destination, redirect behavior) rather than new parameter detail.

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 with scope ('Update writable settings on an existing redirection host by ID') and immediately contrasts with the status-only siblings enable_redirection_host and disable_redirection_host. An agent can distinguish this from the enable/disable/delete redirection tool variants 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?

Explicitly says what to use it for ('change domains, destination, or redirect behavior') and names the alternatives for the adjacent case ('use enable_redirection_host or disable_redirection_host for status only'). This is a clear when-to-use and when-not-to-use routing statement.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses patch/merge semantics (omitted writable fields are preserved, NPM receives the merged set), the dry_run preview behavior, and the return shape. It stops short of stating permission requirements, reversibility, or error behavior on invalid IDs.

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 tight sentences, zero filler: scope and field list first, then routing to siblings, then merge behavior, then the dry_run affordance. Every sentence earns its place and the most decision-relevant information is front-loaded.

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 7-parameter mutation tool with no annotations but a full schema and an output schema, the description covers scope, merge semantics, preview mode, and sibling routing, so an agent can call it correctly. The only real gap is operational context such as permissions or 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 description coverage is 100%, so every parameter including dry_run is already documented in the schema, and the description's merge note largely restates the schema's 'omit to keep the current value'. It adds only the implicit constraint that some fields are non-writable. 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?

States a specific verb (update), resource (existing stream by ID) and the exact field families in scope (writable port, destination, protocol). It explicitly names enable_stream/disable_stream as the status-only siblings, so an agent can separate this from those 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?

Gives both the when ('edit forwarding') and the when-not with the alternative named ('use enable_stream or disable_stream to change status only'). It also adds a safe-preview route (dry_run=True) for agents that need to verify intent before mutating.

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