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

Annotations already carry readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' merely reinforces that rather than contradicting it. Beyond the annotation, it adds meaningful behavior: execution via `certbot certificates` and the coverage scope of all certs certbot knows about, including domains without an active nginx site. No annotation contradiction.

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 with the core purpose front-loaded, followed by the mechanism and a scope qualifier. Every sentence earns its place, and the caveat about inactive nginx domains prevents a realistic mis-assumption.

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 read-only tool that has an output schema and a readOnlyHint annotation, the description is complete: it states what is listed, the mechanism, and the precise coverage boundary. 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?

The tool takes zero parameters, so the empty schema needs no elaboration and the 0-param baseline of 4 applies. The description adds no parameter details, and none are required.

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'), resource ('certbot-managed certificates'), and the exact data returned (expiry date, days remaining), plus the underlying command. The read-only listing framing clearly distinguishes it from the cert-management siblings (issue_cert, renew_cert, revoke_cert, delete_cert) without needing to open 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 'List every certbot-managed certificate' phrasing plus 'Read-only' implies this is the inspection tool within the cert family, and the scope note ('not just domains with an active nginx site') sets a useful expectation. However, it never names a specific alternative or states an explicit when-to-use/when-not-to-use rule — sibling differentiation 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?

Annotations provide readOnlyHint and openWorldHint, but the description adds behavioral nuance beyond that: it explains the resolution is against public resolvers to match Let's Encrypt's view, and mentions the query order. This is valuable context that isn't conveyed by annotations alone. No contradictions found.

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 concise (two sentences) and front-loaded with the core function and rationale. It avoids redundancy and each clause adds value—explaining the method, the use case, and the sibling alternative without fluff.

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 read-only tool with one parameter, an output schema (which we don't see but is indicated), and annotations covering safety, the description is complete. It covers why the public resolver is used, when to call it, and how it differs from a nearby sibling, leaving no gap an agent would need filled.

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 only one parameter, 'domain', and the input schema already provides a clear description with an example. The tool description doesn't add extra parameter-level details beyond what the schema covers, so it earns the baseline score for high schema 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?

The description clearly states the tool's function: resolving a domain against public resolvers (1.1.1.1, 8.8.8.8) with a specific query order (CNAME first, then A/AAAA). It explicitly names the sibling tool check_upstream_health as the alternative for a different task, making its purpose unambiguous.

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

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

The description explicitly states when to use the tool ('Use before issue_cert / create_site to confirm a domain actually points where you expect') and when not to ('For confirming something is listening behind nginx, use check_upstream_health instead'). This leaves no ambiguity about the tool's intended 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: it is a TCP-level probe, independent of nginx or DNS, confirming that something is actually listening rather than relying on resolution.

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 with no filler: the first states what the tool does, the second gives concrete usage contexts, and the third routes to the relevant alternative. Every sentence earns its place and the key 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?

With a fully documented input schema, an output schema, and annotations covering read-only and open-world behavior, the description adds exactly what is missing: purpose, usage timing, and differentiation from check_dns. Nothing an agent needs to invoke it correctly is 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 the parameters are already well-documented in the schema. The description does not need to elaborate on individual parameters; it correctly focuses on the tool's purpose and usage context.

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

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

The description uses a specific verb and resource: 'TCP-probe an upstream host:port to confirm something is actually listening there.' It also explicitly distinguishes itself from check_dns, making the tool's scope unmistakable even among many 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?

It gives concrete use cases: sanity-check an upstream before create_site or debug a 502 afterward. It also names the alternative tool (check_dns) and the condition that selects it, leaving no ambiguity about when to use this tool.

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

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

Although idempotentHint already signals repeatability, the description adds valuable behavioral context: DNS propagation may take minutes, issue_cert re-checks resolution itself, and retrying issue_cert is safe if the domain is not yet resolving. This goes beyond the annotations and helps the agent anticipate timing and failure behavior.

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 tight and front-loads the core purpose before providing workflow guidance. The sentence about repeatability overlaps with the idempotentHint annotation, which prevents a perfect score, but the remaining sentences all earn their 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 the rich schema, existing annotations, and presence of an output schema, the description fills the remaining practical gaps: where this tool fits in the provisioning flow, DNS propagation delays, retry safety, and which sibling tool to use instead. Nothing necessary 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?

The input schema documents all three parameters with descriptions and examples, so parameter semantics are fully covered by structured data. The description restates domain→target but adds no new constraints, syntax, or edge-case guidance 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?

Clearly identifies the operation as an upsert of a Route 53 CNAME record pointing `domain` at `target`, which is specific and unambiguous. It also distinguishes itself from create_txt_record and from create-only semantics, so an agent can immediately tell what this tool does and does not do.

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 explicit sequencing ('Run this before create_site / issue_cert'), timing guidance ('allow a few minutes for DNS propagation'), and a clear alternative for TXT records ('use create_txt_record instead'). This gives the agent concrete conditions for when to invoke this tool versus a sibling.

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

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

Beyond the minimal annotations (openWorldHint and destructiveHint only), the description discloses key behavior: validation via `nginx -t`, automatic rollback on failure, and what it deliberately does not do (reload/cert). This fully informs the agent of side effects and prerequisites.

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, no redundancy, and the most important facts (purpose, safety, follow-up) are front-loaded. Every sentence earns its place, making it efficient 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?

Given the tool's moderate complexity and the presence of an output schema, the description covers all essential aspects: what it does, safety mechanism, required follow-up, and alternatives. Nothing an agent needs to call it correctly or decide whether to use it 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 schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds context that the parameters define an nginx proxy upstream (host/port) and ties the domain to a server block, enriching meaning beyond the schema's mechanical definitions.

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

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

The description clearly states the tool creates a new nginx server block using a specific template, distinguishing it from related tools like update_site. The verb 'create' and resource 'server block' are specific, and the mention of 'websocket-capable default template' adds precision.

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 provides usage context: does NOT reload nginx or request a certificate, and instructs to follow with reload_nginx and issue_cert. It also names the alternative (update_site) for existing sites, giving clear when-to-use vs. when-not-to 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 (openWorldHint, idempotentHint, destructiveHint:false) already declare the safety profile; 'Upsert' is consistent with idempotentHint, so no contradiction. The description adds genuine behavioral value beyond annotations: automatic value quoting, the cleanup expectation, and the 'upsert' semantics. It doesn't mention auth needs or conflict behavior, but with annotations carrying the safety profile a 4 is fair.

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 with zero filler. The core purpose is front-loaded, followed by use case, cleanup instruction, and sibling differentiation. Every sentence earns its place and the most actionable constraint (auto-quoting) is embedded early.

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 elaboration. Given the moderate complexity (3 params, 2 required), the description covers purpose, use cases, cleanup, and alternative routing. In a rich sibling context of 23 tools, the description fully disambiguates create_txt_record from create_domain_record and delete_txt_record.

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 three params are already documented, setting the baseline at 3. The description adds meaningful value beyond the schema by explicitly stating the value auto-quoting behavior ('Quotes the value automatically if the caller didn't'), which maps directly to the value param, and reinforces the domain format with a concrete example.

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 ('Upsert a Route 53 TXT record') plus concrete use cases (ACME DNS-01 challenge, domain verification) with a real example name (_acme-challenge.<domain>). It also names the specific sibling it relates to (issue_wildcard_cert) and the sibling it is not (create_domain_record), so an agent can differentiate 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 explicit when-to-use context (DNS-01 challenge, domain verification), tells the agent to clean up afterward with delete_txt_record, and explicitly routes the CNAME case to create_domain_record instead. Alternatives and exclusions are both stated directly.

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 flag destructiveHint=true, so the safety baseline is covered. The description adds genuinely valuable context beyond that: the confirm:true gate, the critical ordering constraint (revoke must happen before delete), and the concrete consequence that nginx config referencing deleted files will fail to reload. This transforms a bare destructive flag into an actionable risk profile. No contradiction with annotations - destructiveHint matches 'Destructive', idempotentHint is consistent with deleting already-absent files being a harmless repeat, and openWorldHint=false matches a purely local 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 sentences, zero waste. The core purpose is front-loaded first, safety warnings follow in order of criticality: confirmation gate, revocation ordering, then downstream impact. Even the slight redundancy of 'Destructive' against destructiveHint is justified for a tool where a misfire is harmful. Every sentence earns its place.

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

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

For a destructive tool, this is complete. The description covers purpose, confirmation requirement, the revoke-before-delete decision, and post-delete consequences. The output schema exists so return values need no description, and the strong annotations carry idempotency and destructiveness. An agent has everything needed to decide whether and how to call this tool safely.

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 domain ('certbot cert name') and confirm ('Must be true to actually delete; false (default) is a dry run'). The description restates the confirm requirement but adds no new parameter-level meaning beyond the schema. Baseline 3 is correct when the schema carries the full parameter documentation burden.

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: 'Delete a certificate's files from certbot's local store.' It clearly differentiates from the sibling revoke_cert by explicitly stating deletion is not revocation, which is exactly the ambiguity this tool family needs resolved. An agent can distinguish delete_cert from revoke_cert 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?

The description gives explicit routing guidance: 'if it may be compromised, call revoke_cert before this' names the alternative and the condition that selects it. It also warns about the downstream failure mode (nginx reload failures) which implicitly tells the agent to confirm no config references the cert before deleting. Nothing 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?

Explicitly discloses the destructive nature and the confirm:true safety gate, including the dry-run behavior. Adds the lookup-first behavior, which goes beyond the annotations and helps predict side effects.

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

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

Two sentences, front-loaded with the main action, and each sentence adds a distinct piece of information without 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?

For a two-parameter destructive tool, the description plus annotations and output schema cover safety, dry-run, and lookup behavior. Nothing essential 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 description reinforces the confirm parameter's role and explains why no TTL/value parameters exist by noting the tool looks up the existing record. Schema coverage is 100%, so the baseline is 3, but this added context earns a slight upgrade.

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 the Route 53 CNAME record for a domain. Differentiates from sibling tools like delete_txt_record and delete_cert by specifying the record type and service.

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?

Clearly implies when to use it: to remove a CNAME record from Route 53. Does not explicitly name alternatives or exclusions, but the domain/CNAME scope provides sufficient 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?

Annotations declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them by disclosing the dry-run mode, the fact that certificates are left alone, that nginx is not reloaded, and that an archived copy can be restored. These are critical behavioral traits not inferable from the annotations alone.

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

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

Four sentences, each carrying distinct information: what happens, the confirmation guard, the certificate non-effect, and the nginx reload/restore caveats. It is slightly dense but well-organized and front-loaded with the core action.

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 an output schema, full parameter schema coverage, and rich annotations, the description covers all necessary operational context: how to actually trigger deletion, what is not affected, what to do after, and how to undo. No important gap remains.

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%, with both parameters fully described in the JSON schema itself. The description reinforces the confirm parameter's dry-run semantics but adds no new meaning beyond what the schema already documents, 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 names a specific verb ('delete'), a specific resource ('nginx server block for a domain'), and ties in the related actions 'disable' and 'archive'. It clearly differentiates this from sibling tools like delete_cert and revoke_cert by scoping to the nginx server block only.

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 the confirm:true requirement and the dry-run behavior without it, explains that certbot certificates are untouched, says nginx is NOT reloaded and directs the agent to call reload_nginx afterward, and mentions restore_site as the reversal path. This fully routes the agent to the correct workflow.

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

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

Although destructiveHint is already true, the description adds meaningful detail: it requires confirm:true to act, otherwise it is a dry run that changes nothing. It also discloses that the tool looks up the exact existing record first rather than guessing TTL/value, which is important behavioral context beyond the annotations. No contradiction with annotations is present.

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 four sentences with each one serving a distinct purpose: purpose/example, destructive behavior/confirm requirement, lookup behavior, and sibling alternative. It is front-loaded with the most important information and contains 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?

Given the tool's moderate complexity, the description covers purpose, usage triggers, destructive behavior, confirmation requirement, and alternative tool routing. The output schema exists, so return value details are not needed in the description. An agent has enough information to decide when to use this tool and how to invoke it safely.

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 domain and confirm. The description reinforces the confirm parameter's dry-run behavior and adds the 'looks up the exact existing record' detail, but this is more about tool behavior than new parameter-level meaning. It meets the baseline but does not add substantial semantic value 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?

The description opens with a specific verb and resource: 'Delete the Route 53 TXT record for a domain.' It also gives a concrete use case (cleaning up an ACME DNS-01 challenge record) and explicitly differentiates itself from delete_domain_record for CNAME records. An agent can immediately understand what this tool does and how it differs from 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?

The description explicitly states when to use this tool: to clean up TXT records left by create_txt_record or issue_wildcard_cert. It also provides an explicit alternative: 'For a CNAME record, use delete_domain_record instead.' This gives clear context and exclusion criteria, leaving little 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?

The read-only nature is disclosed both in the description and the readOnlyHint annotation, with no contradiction. The description adds value beyond the annotation by specifying the systemctl mechanism and the version-string output, which are not present in the annotation. No hidden side effects are omitted.

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

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

The description is two short sentences with no wasted words. The core behavior is front-loaded, and the 'Read-only' note reinforces safety without redundancy.

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

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

For a no-parameter, read-only status tool with a defined output schema and annotations, the description is sufficient. It states the check performed, the mechanism, and the extra version output. There is no missing context that an agent would need to invoke it correctly.

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

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

The tool has zero parameters, and the schema description coverage is 100% (empty schema). The description does not need to explain parameter meaning because there are none, so the zero-parameter baseline of 4 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 ('report'), a specific resource (nginx service), and the exact output (active status and version string). It clearly distinguishes itself from mutation siblings like reload_nginx by framing this as a status query.

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

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

The description implies usage when you need to know whether nginx is active or its version, but it does not explicitly mention alternatives or situations where this tool should not be used. No exclusion criteria or sibling routing is provided, so the guidance is only implicit.

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 nature is covered. The description adds valuable behavior beyond annotations: it discloses the throw condition when the config is missing, and clarifies the output format as 'raw, unparsed' (implying no processing or validation). This goes beyond the annotations and provides actionable context for the agent.

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

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

The description is two sentences with zero waste. The core action and resource are front-loaded in the first sentence, and the usage guidance (throw condition and alternative) appears in the second. Every word earns its place.

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

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

The tool is simple with a single parameter, and the description covers the error condition and provides a fallback path. An output schema exists (though not shown), and annotations handle the read-only safety. 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 input schema already provides a clear description for the single 'domain' parameter ('Domain as it appears in sites-available, e.g. mysite.julcap.net') with 100% coverage. The tool description adds only the phrase 'for one domain,' which adds no new meaning beyond the schema. Baseline of 3 is appropriate since 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 the raw, unparsed nginx config file for one domain from sites-available.' It clearly distinguishes this from sibling tools like list_sites (which lists domains) and check_cert_expiry (which checks certificates). The scope is explicit — one domain, from sites-available — leaving no ambiguity about the tool's function.

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 explicitly tells the agent when to use it and when not to: 'Throws if no config exists for that domain - call list_sites first if you're not sure it exists.' This names the alternative (list_sites) and the condition that selects it, leaving nothing to inference.

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

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

Annotations provide openWorldHint=true and destructiveHint=false, but the description goes far beyond that. It discloses that the tool edits existing config, reloads nginx, pre-checks domain resolution and fails fast, defaults to staging (which issues untrusted certs but avoids rate limits), and warns that production issuance has real rate limits and that revoke_cert is needed to invalidate a mis-issued cert. This is rich behavioral context not available in annotations or 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?

Although the description is a single long paragraph, it is tightly packed with actionable information. It front-loads the core action, then covers prerequisites, behavioral notes, staging nuance, and the wildcard alternative. There is no redundancy or filler; every sentence adds value and the flow is logical.

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 mutation with external dependencies (Let's Encrypt) and rate-limit considerations. The description covers prerequisites (existing server block), behavior (edits config, reloads nginx), staging vs production, rate limits, revocation fallback, and wildcard routing. An agent has everything it needs to decide whether and how to call this tool correctly. The output schema exists, so return-value details are not required.

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, but the description adds substantial meaning beyond the schema. For email, it explains the consequence of omission (no renewal warnings). For domain, it reiterates the prerequisite of an existing server block and points to check_dns. For staging, it elaborates on the trade-offs between staging and production, including rate limits and CT-logging. The description genuinely enhances parameter understanding.

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

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

The description opens with a specific verb and resource: 'Request a certificate via `certbot --nginx` (HTTP-01 validation).' It clearly states what the tool does and distinguishes it from the sibling issue_wildcard_cert, which is explicitly named for wildcard domains. The purpose is unambiguous and 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 description explicitly states when to use this tool: it requires an existing nginx server block from create_site, and it notes that certbot edits that config in place and reloads nginx itself, so no separate reload_nginx call is needed. It also names the alternative for wildcards (issue_wildcard_cert) and explains why HTTP-01 can't validate wildcards, providing clear exclusion criteria.

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

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

Annotations already mark openWorldHint=true and destructiveHint=false. The description adds useful behavior: it fails fast with guidance on missing credentials, defaults to staging, and explains why DNS-01 is required. It could be slightly stronger by stating whether temporary Route53 DNS records are created during validation.

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 dense sentences: first states the core operation and constraint, second covers prerequisites and failure behavior, third covers default and alternative. No filler or repetition of 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?

For a tool with one required parameter, full param descriptions, an output schema, and an open-world annotation, the description covers the critical operational facts: wildcard scope, DNS-01 requirement, plugin/credential prerequisites, default staging, and the sibling alternative. Nothing essential 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 applies; the description adds no new parameter-level meaning beyond what the schema's `domain`, `staging`, and `email` descriptions already say. It does reinforce the wildcard scope and staging default, but does not compensate for anything missing.

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

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

The description states a specific action ('Request a wildcard certificate'), includes exact scope (`domain` and `*.domain`), and names the sibling to avoid (`issue_cert` for single non-wildcard domains). This makes it distinguishable from the related certificate tools 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?

It explicitly says when to use this tool (wildcard certs needing DNS-01) and when not to ('For a single non-wildcard domain, use issue_cert instead'). It also states the prerequisites (certbot-dns-route53 plugin, AWS credentials), which is actionable usage 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?

Annotations already declare readOnlyHint=truecars, and the description adds useful behavioral context beyond that: these archives are created by delete_site, are sorted newest first, and their filenames are directly consumable by restore_site. It does not contradict the annotations.

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

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

Two efficient sentences front-load the core purpose and ordering, then immediately explain the downstream integration with restore_site. There is no filler or repetition of schema information.

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, a single well-documented optional parameter, and read-only annotations, the description covers everything an agent needs: what to list, the order, and how the result is used by restore_site. Nothing critical 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 schema description covers the single optional domain parameter at 100%, so the baseline applies. The description does not add details about the domain filter, but it doesn't need to because the schema already documents it clearly.

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

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

The description uses a specific verb ('List'), names the exact resource ('archived nginx configs'), and clarifies the origin ('created by delete_site'). It also gives ordering ('newest first'), which distinguishes it from the sibling list_sites and makes the tool's role obvious.

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 clearly connects this tool to restore_site: filenames from this output feed into restore_site's archive_filename to restore a specific archive. It strongly implies when to use this tool over list_sites, though it does not explicitly state a negative condition like 'use list_sites for active sites.'

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 useful behavioral detail beyond that: it parses config files directly and does not shell out to nginx. This clarifies how the read-only operation is performed and implies a lightweight, direct inspection.

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

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

The description is two sentences, front-loaded with the core function and scope, then the read-only behavior, then the sibling alternative. Every sentence adds distinct value with no redundancy.

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

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

For a parameterless read-only list tool with an output schema and strong annotations, the description fully covers purpose, scope, behavior, and the relevant sibling 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter syntax, but that is unnecessary here; the empty schema and zero-parameter context fully describe invocation requirements.

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 ('List'), a specific resource ('nginx server block'), and a precise scope ('sites-enabled'). It also lists the returned aspects (domain, upstream, SSL configuration), making the tool's function 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 description explicitly provides a usage alternative: 'Use get_site_config for one domain's full raw config.' This tells an agent when to prefer this tool versus a sibling, leaving no ambiguity.

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 mark destructiveHint=true and idempotentHint=true, but the description adds essential behavioral detail: the default is a dry run, deletion requires explicit confirmation, it continues past individual failures, and it reports the actual removal count. These are important safety and execution traits not visible from annotations alone.

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

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

Three sentences, each carrying critical information: the core action, the safety mechanism, and the failure/reporting behavior. It is front-loaded with the main purpose and wastes no words.

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 destructive nature, the description covers the necessary safety context (dry run, confirm requirement), behavior on partial failure, and output reporting. Combined with full parameter schema coverage and an output schema, nothing essential 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?

Schema description coverage is 100%, so both parameters are already documented. The description's 'older than a threshold' matches older_than_days and 'requires confirm:true' matches confirm, but it adds little beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Delete'), a specific resource ('archived site configs (from delete_site)'), and a precise scope ('older than a threshold'). It clearly distinguishes this tool from siblings like list_archived_sites and delete_site by tying it to archived configs and threshold-based pruning.

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 clearly explains how to use the tool: confirm:true triggers deletion, while default is a dry-run that lists and changes nothing. It implies when to use it (for bulk pruning of old archived configs) but does not explicitly name alternatives or state when not to use it, leaving slight room for 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?

Annotations already mark the tool as idempotent, non-destructive, and closed-world. The description adds useful behavioral context: it runs a config test first and only reloads if that passes this is not stated in the annotations. It does not describe response/exit behavior, but the output schema likely covers that, so this is a strong 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 two concise sentences. The first front-loads the core behavior and safety guard, and the second provides the exact invocation context. Every sentence earns its place with no filler or redundant restatement.

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 tool with an output schema and annotations covering idempotency and destructiveness, the description is complete. It tells the agent what the tool does, when to call it, why it is needed, and what safety mechanism it uses. Nothing essential 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 has zero parametersasi the schema confirms, and schema description coverage is 100%. Per the rubric, a zero-parameter tool gets a baseline of 4. The description does not need to explain parameters, and it does not attempt to invent any.

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 precise action: run `nginx -t` and reload the live service only if the config test passes. It clearly identifies the resource (nginx), the specific behavior (guarded reload), and the context that distinguishes it from sibling tools that modify site configs but do not reload.

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 explicitly says when to use the tool: after create_site, delete_site, or restore_site. It also clarifies that those tools do not reload automatically, which removes ambiguity about whether this step is needed. It also implies a key constraint: never reloads a broken config.

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?

It discloses non-obvious behaviors: the staging simulation for dry-run, no rate-limit impact, permanent disarming of certbot's pre-renewal sleep, and synchronous return. These details are valuable beyond the sparse annotations (only `openWorldHint: true`, `destructiveHint: false`) and do not contradict them.

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 concise and front-loaded: the first sentence states the core command and scoping, the second covers the default and its safety cue, and the third explains the synchronous return. Every sentence carries essential information 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 two-parameter tool with a full output schema and straightforward behavior, this description covers the default state, the risky escape hatch, scoping, and execution behavior. Nothing needed 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 complete (100%), and the description adds the critical meaning of `dry_run: false` as a deliberate real renewal rather than simulation. It also clarifies that the `domain` parameter is actually a cert-name scope, which is not explicitly stated in 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?

The description clearly states the tool runs `certbot renew`, scopes to a single cert name via `--cert-name`, and defaults to `--dry-run`. It is distinct from the sibling issue/revoke/delete certificate tools, so an agent can tell when to invoke it.

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

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

The description gives clear guidance on when to keep the default dry-run and when to pass `dry_run: false` ('only when you mean to actually renew'). It does not explicitly contrast with issue_cert/revoke_cert for choosing a renewal path, but the conditions for using the tool safely are well 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?

The description adds crucial behavior beyond the annotations: it is destructive to current config, requires confirmation, test-renders before enabling, rolls back automatically on failure, and does not reload nginx. These details complement the destructiveHint:true annotation and do not contradict it.

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, each with a distinct role: purpose, destructive guard, failure mitigation, and the reload follow-up. Information is front-loaded and there is 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?

Given the destructiveHint annotation and the presence of an output schema, the description covers everything an agent needs: what is restored, the safety mechanism, the confirmation gate, and the necessary next-step reload. There are no hidden 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 the parameters are already well-documented (including the confirm default/dry-run and archive_filename default). The description restates the confirm requirement but does not add new parameter-level information, so the baseline 3 is appropriate.

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

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

States a specific verb ('restore'), a precise resource ('domain's nginx config'), the source ('most recent archive created by delete_site'), and the outcome ('enable it'). This clearly positions the tool as the inverse of delete_site and distinguishes it from create_site and reload_nginx.

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 states the mandatory confirm:true requirement, notes that confirm:false is a dry run, and explicitly instructs the agent to call reload_nginx afterward because this tool does not reload nginx. This is actionable usage guidance with a clear 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?

Although destructiveHint=true already flags mutation, the description adds substantial behavioral specifics: immediate browser-wide distrust, effective irreversibility, the confirm:true requirement, and the fact that cert files are left on disk. This goes well beyond the annotation and prepares the agent for real consequences.

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: purpose and trigger, consequence and safety requirement, and post-condition with follow-up. Every sentence 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?

The tool has an output schema, 100% parameter coverage, and annotations. The description adds the missing real-world behavior, irreversibility, and next-step guidance, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and already explains both parameters: domain as a certbot cert name and confirm as a guard with false default. The description reinforces the confirm requirement but does not add meaning beyond the schema. A baseline of 3 is appropriate.

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

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

The description states a specific verb ('Revoke') and resource ('a certificate with Let's Encrypt'), then clarifies its immediate consequence. It clearly distinguishes itself from the sibling delete_cert by noting the files remain on disk, and from issue/renew by its destructive nature.

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 a concrete trigger ('after a key compromise'), warns that it is destructive and irreversible, and directs the user to follow with delete_cert for file removal. It does not explicitly enumerate when not to use it, but the destructive warning and follow-up relationship provide solid usage 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?

Annotations already mark the operation as read-only, and the description adds useful behavioral facts beyond that: the 1000-line cap and the best-effort substring filtering limitation with a pointer to the note in the result. It does not need to restate read safety.

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

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

Two compact sentences front-load the core purpose and cap, then deliver the key caveat about domain filtering. No filler or redundant clauses.

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 three-parameter, read-only log-tail tool with an output schema present, the description covers the essential behavioral constraints (line cap, domain caveat, result note). Additional details would be redundant with the schema and 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 the prose largely mirrors the schema (e.g., 'capped at 1000' appears in both). The description adds no new parameter-level detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states a specific action ('Tail') on a specific resource ('nginx's access or error log') with an important bound ('capped at 1000 lines'). This clearly distinguishes it from all siblings, none of which read logs.

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 are no sibling log-reading tools to contrast with, but the description gives clear context for invoking the tool and explicitly warns that the domain parameter is not a true per-vhost filter. It stops short of an explicit when-to-use/when-not-to-use 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?

Beyond the annotations (idempotent, non-destructive), the description reveals critical behavioral traits: it rewrites proxy_pass in place, preserves SSL config, test-renders before committing, and auto-rolls back on nginx -t failure. It also discloses the lack of reload. These details significantly exceed what annotations alone convey.

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 efficient and front-loaded with the core action and key constraints. Every sentence carries essential information (scope, failure conditions, safety mechanism, post-requisite), with zero fluff 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?

The description covers failure conditions, the test-render/rollback mechanism, the reload requirement, and what is left untouched. With an output schema present and annotations providing safety hints, an agent has everything needed to invoke this tool correctly and predict its outcomes.

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 each parameter is already documented. The description adds value by linking the parameters to the operation (domain identifies the existing site, upstream_host/port become the new proxy_pass target), reinforcing their roles. This extra context elevates it 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?

The description clearly states the verb 'Update', the resource 'existing site's upstream' via proxy_pass rewriting, and explicitly differentiates from create_site and reload_nginx. It specifies exactly what is modified and what remains untouched, leaving no ambiguity about the tool's purpose.

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

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

The description explicitly states when to use this tool (existing site with proxy_pass) and when not to (if no existing config, use create_site instead; does not reload, call reload_nginx afterward). It names the alternatives directly, providing unambiguous routing for an agent.

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