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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds a crucial behavioral caveat: on Caddy <= 2.11.4, the 'order' global option mutates the process's directive order despite the preview-only claim. This goes beyond annotations and is essential for correct usage. It also explains the return format (adapted JSON and warnings).

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 long, but every part earns its place: the core purpose, the usage context, and the version-specific caveat. It is front-loaded with the primary action, and the detailed exception is justified because it materially affects behavior. Slightly dense but not verbose.

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

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

For a tool with a subtle mutation risk, the description covers the version-specific behavior, the return value (adapted JSON plus warnings), and adapter requirements. There is no output schema, so the description correctly explains what the agent will receive. Nothing essential is missing for safe invocation.

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

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

Schema coverage is 100% with descriptions for both config and adapter, so the baseline is 3. The description adds context about adapter module availability (built-in vs. compiled external modules), which complements the schema and helps the agent choose the right adapter. Not a large addition but useful.

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 clear verb+resource: 'Convert a config in any registered adapter format to Caddy JSON without loading it.' It distinguishes itself from siblings like caddy_load by explicitly stating 'without loading it', so an agent can tell it apart immediately.

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 when to use the tool ('previewing what a Caddyfile produces, or for porting from nginx/yaml configs') and specifies the adapter module prerequisite. It also warns about the 'order' mutation on older versions, effectively covering a when-not-to-trust-preview-only scenario.

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

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

Annotations are all false, providing minimal safety context (not read-only, not idempotent, not destructive). The description adds capability details (supports any handler) but does not disclose behavioral traits such as whether the route is appended or overwrites existing routes, validation behavior, or reversibility. This is a moderate 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?

The description is two sentences, front-loaded with the action, and contains no fluff. Every word adds relevant context about what the tool does and its flexibility.

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 100% schema coverage and absence of an output schema, the description covers the tool's purpose and scope effectively. It misses some behavioral context (e.g., route ordering, interaction with terminal flag) but is reasonably complete for a config-modifying tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by enumerating common handler types (reverse_proxy, file_server, etc.) and emphasizing 'full control', which helps the agent understand the flexible, free-form nature of the match and handle parameters beyond the schema's minimal examples.

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 action ('Add a route') and its scope ('full control over match conditions and handlers'). It also lists specific handler types, which distinguishes it from sibling tools like caddy_remove_route and caddy_list_routes.

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

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

The phrase 'full control' implies this is the general-purpose tool for adding routes, and mentioning 'any Caddy handler' suggests flexibility. However, it does not explicitly state when to use this versus alternatives like caddy_reverse_proxy, nor does it provide any exclusions or 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?

The description discloses extensive behavioral details beyond annotations: delete requires confirm=true, set/delete validate the id resolves, root-id handling replaces/unloads the entire config, snapshots for revert, and admin endpoint reporting. This exceeds the destructiveHint annotation and provides critical safety context.

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

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

The description is dense but every sentence adds value, covering core purpose, edge cases, and safety constraints. It is front-loaded with the primary function and systematically explains special behaviors. No wasted 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?

Despite no output schema, the description explains key success/failure behaviors (refusal of unknown ids, root handling, admin endpoint relocation). All 6 parameters are documented in the schema, and the description covers the main edge cases, making it fully sufficient for correct invocation.

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

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

Schema coverage is 100% and parameter descriptions are already detailed, especially for 'mode' and 'confirm'. The description adds behavioral context (e.g., id resolution) but does not substantially extend parameter meaning beyond the schema, 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 verb ('read, updated, or deleted') and resource ('config object by @id tag'), and explicitly distinguishes it from path-based access. It also identifies it as the recommended way to manage individual routes, differentiating it from sibling tools like caddy_config_set/get.

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 indicates when to use this tool (for individual config objects with @id) and explains the root-id special case where it behaves like caddy_config_set/delete. It does not explicitly name alternatives for non-root operations, but the context implies it's the go-to for individual objects, which is sufficient 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?

Beyond the destructiveHint annotation, the description discloses important behaviors: deleting a parent deletes descendants, root deletes unload the entire config, only root deletes are snapshotted for caddy_revert, and the admin endpoint may rebind or become unreachable. This is substantial context that prevents catastrophic misuse.

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 long but every sentence earns its place by clarifying dangerous edge cases, alternatives, and recovery behavior. The core action is front-loaded, with the risky root-path details following naturally. No 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?

For a destructive, high-stakes tool, the description covers outcomes, side effects, snapshot behavior, admin endpoint implications, and the alternative replacement tool. The absence of an output schema is acceptable because the behavioral consequences are fully disclosed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the path parameter, especially the root-path variants and their full-unload behavior, and reinforces the confirm=true requirement. This goes beyond simply restating 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's action: deleting config at a JSON path and removing the config node. It distinguishes itself from caddy_load by explicitly noting that replacing the config is a different operation. The verb+resource combination is specific and 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 gives explicit guidance around the root-path danger and names caddy_load as the alternative when replacement is intended. It also states that confirm=true is required. It does not enumerate every sibling alternative, but the critical routing decision is 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by explaining the return behavior for empty vs. specific paths, which goes beyond the structured annotations and helps the agent predict the tool's output.

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 action, and every word adds value. It avoids needless detail while including a practical example. No redundancy or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the essential behaviors: full config vs. subtree, path example, and empty path default. It doesn't mention error handling or exact output format, but these are relatively minor gaps given the tool's simplicity and strong 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% for the only parameter 'path', but the description enriches its meaning by explicitly stating that an empty path returns the full config and providing a concrete example ('apps/http/servers/srv0/routes'). This goes beyond the schema's generic 'Config path' description.

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

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

The description clearly states the tool reads Caddy config at a JSON path, with a specific verb ('Read') and resource. It distinguishes itself from siblings by being the generic config getter, while other tools handle writes, deletes, or specific lookups. The clarification of empty path returning the full config adds scope 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?

The intended usage is implied: use this to read config by path. However, there is no explicit guidance on when to prefer this tool over alternatives like caddy_config_by_id or caddy_status, nor any exclusions. The description provides clear context but no comparative direction.

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 destructiveHint annotation, the description discloses major non-obvious consequences: root writes discard all apps, servers and routes not in `value`, may re-bind the admin endpoint and can make Caddy unreachable from both this server and caddy_revert; append is non-idempotent; insert at root only works after a root caddy_config_delete; and root writes are snapshotted while other paths are not. This is exactly the kind of behavioral 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?

The description is long, but every sentence carries unique operational or safety information, covering mode behavior, root-path edge cases, error codes, admin endpoint reachability, and interaction with caddy_load/caddy_revert. The core purpose is front-loaded in the first sentence, and the rest is logically grouped, making it a dense but efficient reference.

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 output schema and only a destructive annotation, the description covers error conditions (404, 409), preconditions (root delete before insert), side effects on admin endpoint connectivity, rollback capability, and interactions with sibling tools. An agent can correctly invoke this tool and anticipate all major consequences across every required mode.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds critical meaning beyond the schema's one-line mode definitions: it explains that writing [] to routes drops every route, that append replaces non-array keys and cannot create parents, that insert fails with 409 if the key exists, and the precise root path variants and confirm=true requirement. It enriches the semantics of path, mode, and confirm substantially.

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 opening sentence states a specific action and resource ('Write config at a JSON path'), and the description immediately distinguishes the three modes (overwrite/append/insert) with their HTTP semantics. It also differentiates from caddy_load by noting that tool replaces the whole config while this one targets a path (except at root), and contrasts with caddy_revert and caddy_config_delete in the behavioral descriptions.

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

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

It provides explicit guidance for when to use each mode: 'insert' is called the safe way to create a server or app, 'append' is for arrays, and 'overwrite' for replacement. It explicitly directs whole-config replacements to caddy_load as the deliberate alternative and mentions caddy_revert for rollback after root writes, giving agents clear decision 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 declare readOnly/idempotent/non-destructive, and the description adds significant behavioral detail: output caps (500 routes/20000 chars), whole-route truncation, omission note, and exact fallback path. This fully discloses edge-case behavior without contradicting 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?

Three dense sentences that each add distinct value: purpose/output, caps/truncation, and fallback. No redundant filler; structure is well-organized.

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 list operation with one optional parameter and no output schema, the description covers output format, limits, edge-case behavior, and how to get the complete data. It is fully self-contained for an agent to invoke and interpret results.

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 only parameter 'server' is already documented in the schema with default 'srv0' and 100% coverage. The description does not add additional parameter-level detail but doesn't need to given 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?

Clearly states it lists all routes on a Caddy HTTP server and describes the dual output (summary + raw JSON). The use of 'all routes' and explicit reference to caddy_config_get for reading the rest distinguishes it from sibling config-read tools.

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

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

Implies use when you want a quick route overview on a specific server, and explicitly directs to caddy_config_get at a specific JSON path for the full untruncated data. The cap behavior and omission note also tell the agent when the result is incomplete.

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 this as a safe, read-only, idempotent operation. The description adds transparency about the output content (specific server attributes), which is helpful given there is no output schema. This goes beyond what annotations alone provide.

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, front-loaded with the action and output details, followed by a practical usage hint. Every sentence contributes value 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 zero-parameter, read-only list operation with strong annotations, this description is complete. It tells the agent exactly what the tool does, what it returns, and when to invoke it, making tool selection and usage straightforward.

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 schema is fully covered by default. Per the baseline for 0-parameter tools, the description appropriately focuses on behavior and output rather than parameter explanations.

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 identifies the operation as listing all configured HTTP servers and specifies the exact data returned (names, listen addresses, route counts, TLS status). This distinguishes it from sibling tools like caddy_list_routes, which focus on routes rather than servers.

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 this to discover server names before calling route tools.' This provides a clear workflow context, though it does not explicitly name alternatives or exclusion cases.

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?

Despite strong annotations (destructiveHint=true, idempotentHint=true), the description adds substantial extra context: atomic replacement, disposal of the entire running config, snapshot and revert via caddy_revert, and the non-retry/may-still-apply behavior on timeout. It explicitly states confirm=true is required and clarifies the destructive impact. This goes far beyond the annotations and is directly actionable.

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 three sentences, progressively delivering the core action, safety/timeout details, and the confirm requirement. It is front-loaded with the primary purpose and contains no filler. Every clause contributes critical information, making it highly concise and well-structured.

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

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

For a destructive, full-config replacement tool, the description covers the essential elements: action, accepted formats, timeout behavior, confirm requirement, and revert path. It omits explicit output/return information, but there is no output schema, and the caution to re-read config implies the operation's effects may not be immediately visible. This is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description mostly mirrors the schema for config and format, and for confirm it reiterates the safety requirement without adding new parameter-level meaning. The added value lies in behavioral context (timeout, discard) rather than parameter semantics, so 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 begins with a specific action: 'Replace the entire Caddy configuration atomically.' It clearly identifies the resource (entire Caddy configuration) and the verb (replace). The mention of atomicity and acceptance of JSON or Caddyfile distinguishes it from sibling tools like caddy_config_set (incremental changes) and caddy_add_route (route-specific).

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 it is 'the safest way to make large config changes,' giving clear context for when to use it. However, it does not explicitly mention alternatives or exclusion criteria (e.g., 'for incremental changes, use caddy_config_set'). It does provide related caution about timeout and re-reading config, which supports proper usage.

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, idempotentHint, and destructiveHint. The description adds substantial behavioral context: output can be megabytes, filter-mode drops blank/free-form comments but preserves HELP/TYPE lines, '# EOF' is always kept, max_lines defaults to 500, and a trailing comment reports dropped lines. This goes well beyond the structured hints.

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 appropriately sized—four sentences that lead with the core purpose, then dive into parameter behavior with examples. Every sentence carries unique, essential information; there is no repetition or filler. The structure flows logically from purpose to usage to edge cases.

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

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

For a tool with no output schema, the description covers the return format implicitly (Prometheus text) and explicitly covers filtering semantics, line handling, size limits, and the trailing summary. It gives the agent enough context to anticipate output characteristics and pitfalls, making it complete for invocation and result handling.

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?

Although schema coverage is 100%, the description significantly enriches parameter meaning. It explains that filter is a substring match on metric names, that HELP/TYPE lines for matching metrics are retained, and that label values are NOT matched. For max_lines, it details the default (500) and the appended summary line, which the schema does not fully convey.

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+resource: 'Get Prometheus metrics from Caddy.' It lists concrete metric categories (request counts, durations, TLS handshake stats, active connections) and clearly distinguishes this tool from sibling tools like caddy_config_get or caddy_status, which serve different purposes.

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 provides clear guidance on when to use the filter and max_lines parameters, including examples and edge-case behavior (label values not matched). It does not explicitly contrast with alternatives, but among the siblings none offer metrics, so the context is clear enough for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little beyond repeating the certificates parameter's effect, and does not disclose additional behavioral traits such as output format or error behavior. No contradiction with annotations exists.

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

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

The description is a single, focused sentence that begins with the verb and directly states the tool's purpose. No filler or redundant information, making it highly concise and well-structured.

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

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

The tool is a simple read-only getter with no output schema, yet the description is vague about what 'info' includes or what the response format looks like. While annotations and schema cover parameters and safety, the description lacks contextual detail about the return value or edge cases, making it minimally adequate.

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

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

Input schema coverage is 100% (both 'ca' and 'certificates' have descriptions). The description does not add any additional meaning beyond the schema, so the baseline score 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 starts with the verb 'Get' and clearly identifies the resource as 'PKI certificate authority info or the CA certificate chain.' This is specific and distinguishes it from siblings like caddy_config_get or caddy_status, which have different purposes.

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 its usage as a read-only query for PKI CA information, but does not explicitly state when to use it over alternatives like caddy_tls or caddy_config_get. No exclusions or alternative tool references are provided, so 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?

The description goes well beyond the annotations by clarifying that idempotency is mode-dependent: @id mode is idempotent, while index mode is not and can remove different routes on repeated calls. It also discloses the two-step read-then-delete race, the config-global scope of @ids, and the refusal behavior when the id resolves to a non-route object. This is excellent behavioral disclosure for a destructive 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?

Every sentence carries essential operational or safety information. The description is front-loaded with the core action, then systematically covers target selection, idempotency differences, concurrency hazards, and scope semantics. There is no filler or repetition that does not 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?

For a destructive, non-idempotent tool with no output schema, the description is remarkably complete. It addresses the main failure modes (race conditions, repeated index removal, non-route @id targets), explains the confirm-based safety mechanism indirectly through the schema, and gives the agent enough context to call the tool correctly and avoid destructive mistakes.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains why id is preferred, warns that index removal re-packs the routes array, and clarifies that @ids are config-global rather than route-scoped. This enriches the agent's understanding of how id and index actually behave.

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 direct, specific statement—'Remove a route'—and immediately identifies the two targeting modes (@id or index on a specific server). This clearly distinguishes it from generic config deletion tools and from route-modification siblings like caddy_add_route or caddy_list_routes.

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

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

The description gives explicit usage guidance: prefer @id because it is stable across reorderings, avoid index mode when possible because it can race against concurrent edits. It does not explicitly compare this tool to alternatives like caddy_config_delete, but the contextual guidance for choosing between the tool's own modes is strong and concrete.

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 supply safety hints (destructiveHint=true, idempotentHint=false), and the description adds substantial context beyond them: conditional idempotency based on `id`, duplicate-route creation on repeat calls, refusal on non-route @id collision, server argument being ignored after @id registration, and TLS transport behavior. This is rich behavioral disclosure.

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

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

Dense and front-loaded with the primary purpose and example first, then edge cases. It is on the long side and repeats several schema-documented facts, but every sentence contributes operational detail rather than 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, non-idempotent mutation tool with no output schema, the description is thorough: it discloses idempotency semantics, collision refusal, cross-server @id behavior, and TLS handling. 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%, so the schema already documents all four parameters, including the @id collision behavior and the mixed-scheme restriction. The description largely restates those semantics, adding only a concrete example; baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb+resource ('Add a reverse proxy route') and immediately scopes it as the most common operation. It also names caddy_add_route as the alternative for the mixed-scheme case, distinguishing it 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?

Explicitly covers when to omit vs supply `id`, gives a hard recommendation for automation/production, explains the config-global @id scope, and routes the mixed-scheme case to caddy_add_route. When-to-use and when-not-to-use are both 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?

The annotations only declare destructiveHint=true, but the description adds crucial behavioral context: snapshots retain only the last 10, are memory-only by default and lost on restart, contain full Caddy configs, and apply requires confirm=true. This substantially exceeds what annotations alone communicate and helps the agent avoid destructive mistakes.

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 dense but every sentence earns its place, covering auto-capture rules, retention, persistence, safety, and the action enum. It front-loads the primary purpose before diving into edge-case behavior, making it scannable for an agent.

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

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

For a destructive tool with three parameters and no output schema, the description covers the full behavioral contract: what is snapshotted, retention limits, persistence options, safety confirmation, and how each action behaves. Nothing critical for correct invocation is missing.

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

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

Although the schema already describes all three parameters, the description enriches them: it defines what each action does, states that index 0 means most recent, and clarifies that confirm=true is a mandatory safety gate for apply. This adds real decision-making value beyond the raw 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 clear verb-resource pairing, 'Manage config snapshots for rollback,' and immediately distinguishes this tool from the config-mutation siblings by focusing on snapshot lifecycle. It then enumerates the exact actions (list, save, apply), removing any 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 explicitly states when snapshots are auto-captured, when they are not ('no other delete or set is snapshotted'), and how to manually invoke each action. It also gives an operational guideline for persistence via CADDY_MCP_SNAPSHOT_DIR, which is exactly the kind of conditional usage an agent needs.

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, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is clear. The description adds valuable context about what the summary contains (servers, routes, listen addresses, TLS status), going beyond the annotations. It does not discuss failure modes, but the annotation coverage lowers the bar and the added context is meaningful.

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

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

The description is a single, front-loaded sentence that packs significant information: the verb ('Check'), the resource ('Caddy connectivity'), and a detailed summary content list. Every word earns its place, with no redundancy or filler.

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

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

Given the tool's simplicity (no params, no output schema), the description is complete. It explains both the action (connectivity check) and the expected return content (config summary with servers, routes, listen addresses, TLS status). Rich annotations further cover the safety profile, so the description sufficiently covers all necessary contextual information.

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 schema is trivially complete (coverage 100%). Per guidelines, 0 params receives a baseline score of 4 because there are no parameter gaps to address. The description adds no parameter info, but none is 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?

The description clearly states a specific verb and resource: 'Check Caddy connectivity and get a config summary'. It also enumerates the summary content (servers, routes, listen addresses, TLS status), which distinguishes it from sibling tools like caddy_config_get (full config) and caddy_list_servers (specific server list).

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 by stating the tool provides connectivity checks and a config summary, but it does not explicitly recommend it over alternatives or mention when not to use it. It provides clear context for when this tool is appropriate, but lacks explicit exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful context by specifying 'gracefully' shutdown and the confirm=true safeguard, which helps the agent understand the manner and safety requirement of the operation.

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

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

Two short sentences, front-loaded with the core action, and every word contributes value. There is no filler or redundant elaboration beyond the necessary confirmation note.

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

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

For a simple one-parameter stop operation with clear annotations and full schema coverage, the description is sufficient. It does not explain return values or edge cases, but given the low complexity and existing structured data, that is acceptable.

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 fully describes the confirm parameter with 100% coverage ('Must be true to confirm shutdown'). The description only repeats this requirement without adding new semantic detail, so 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 uses a specific verb 'shut down' with a clear resource 'Caddy server', and it is distinct from sibling tools that handle config, status, or routes. The action and target are 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 implies its use (to stop the server) but does not explicitly state when to use it versus alternatives or when not to use it. The confirm requirement is a prerequisite, not a usage guideline. It lacks explicit context for selection among siblings.

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?

Even though annotations already mark the tool as idempotent and non-destructive, the description reveals important side effects: set_* actions create apps/tls and missing parents, and writes only target policies[0].issuers[0] when that issuer's module is 'acme'. It also discloses version constraints (Caddy 2.10+), read-only behavior for ech_status, and the failure semantics of set_acme_profile when a CA does not support the profile.

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 dense but every sentence contributes operational guidance: purpose, action list, version gates, creation behavior, and the alternative path. It is front-loaded with the main purpose and action enumeration, and the longer edge-case clauses earn their length.

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 version requirements, fresh-vs-existing behavior, exact mutation targets, exclusions, and the alternative tool. The only notable gap is the lack of explicit return-value shape for status/ech_status, but since there is no output schema and the read actions are described as showing/reading config, this is a minor 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 the baseline is 3. The description adds value by explaining how the action parameter changes config: set_* creates missing parents and targets only the first issuer under specific conditions. It also reinforces the meaning of each action, though ca and email formats remain mostly handled by 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 opening line states a specific verb and resource: 'Get or configure TLS/HTTPS settings.' The description then enumerates the five actions, making the tool's scope unmistakable. It also differentiates from generic config tools by pointing to caddy_config_set as the fallback for unsupported TLS shapes.

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 the tool is appropriate: 'Works on both fresh and existing Caddy instances, including one with no config at all.' It also gives a clear when-not-to-use rule by instructing that on multi-policy TLS configs or with an 'internal' first issuer, you should 'edit the intended issuer with caddy_config_set instead.'

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 (readOnlyHint, idempotentHint), the description discloses several non-obvious behaviors: the data is returned verbatim, it may not reflect the current config on certain versions, dynamic entries persist for a while, and duplicates can appear with specific characteristics. This is exactly the kind of behavioral context that prevents an agent from drawing wrong conclusions, and it does not contradict any annotation.

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

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

The description is front-loaded with the core purpose and then expands into necessary caveats. It is longer than average, but every sentence adds unique operational value (version-specific behavior, persistence, duplication, summation warning). It is not wordy, though it could be tightened with bullet points for the caveats.

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

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

With no output schema and no parameters, the description carries the full burden of explaining what to expect from the tool. It covers the array shape, the fields per entry, the version caveat, the persistence timing, the duplicate-entry scenario, and the summing pitfall. This is sufficient for an agent to invoke the tool and interpret the result without being misled.

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 and the schema has no properties, so there is nothing for the description to explain. Baseline for 0 params is 4. The description makes no parameter claims and correctly focuses on output behavior instead.

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 precise statement of what the tool returns: Caddy's /reverse_proxy/upstreams array with the exact fields (address, num_requests, fails), returned verbatim. It also distinguishes this tool from configuration retrieval by noting that on Caddy 2.11.2+ it is not the configured upstream list, and the reader can infer it is meant for inspecting runtime upstream state.

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 context—it tells you when the data is misleading (after config changes, with dynamic upstreams) and warns against summing num_requests. However, it never explicitly says 'use this when you need runtime upstream statistics' or contrasts it with sibling tools like caddy_config_get. The caveats are useful but the when/why 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.