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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description goes further by documenting the ordered diagnostic hops, conditional checks for optional modules, and the behavior of returning the first failure plus a fix. It does repeat the read-only nature, but still adds substantial process context beyond 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?

The description is front-loaded with the core action and then compactly lists the hop sequence. The length is justified by the diagnostic complexity, and every clause contributes useful scope or behavior 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?

The tool has an output schema and explicit read-only/open-world annotations, and the description explains the diagnostic chain well enough to call it correctly. The main remaining gaps are the exact domain input format and explicit routing against similar sibling tools.

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

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

Schema description coverage is 0%, so the schema provides only a bare string parameter named domain. The description partially compensates by specifying that it is a public domain in the context of a domain-to-container diagnostic chain, but it does not clarify format details such as whether to include a scheme, subdomain, or port.

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 diagnostic verb and resource: it checks every hop between a public domain and its upstream container and names the first failing hop with a fix. It also enumerates the exact check sequence, making the tool's scope and distinction from generic status/list tools clear.

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

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

Usage is implied through the troubleshooting workflow: the tool is for diagnosing where a public service path fails. However, it does not explicitly compare against siblings such as service_status, homelab_health, or infrastructure_overview, nor does it state when not to use it.

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?

Goes well beyond the annotations by disclosing the approval gate, the environment-variable escape hatch, and that delete is permanent — real operational context an agent cannot get from destructiveHint alone. It stops short of explaining `dry_run`, which is the obvious safeguard for those destructive actions.

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

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

Four short sentences, front-loaded with the read-only vs. mutating split, then per-action requirements. No filler or restatement of the title.

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

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

Output schema exists, so return values need not be described, and the safety/approval story is fully covered. Gaps remain around pagination (page/limit), whether zone_id is required for scoped actions, and what dry_run does.

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 0% across 11 parameters, so the description must carry the burden; it partially does, mapping name/record_type/content to create and record_id to update. It says nothing about zone_id, ttl, proxied, page/limit pagination, or dry_run, leaving over half the parameters unexplained.

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?

Names the resource (DNS records) and enumerates every action the single `action` enum supports, so an agent knows this is a multi-op CRUD tool for individual records. It does not explicitly contrast with the sibling `dns_zones` (which handles the parent zones), leaving that distinction to inference from the name.

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

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

Gives per-action guidance: list/get are read-only, create/update/delete mutate the zone and require approval or HOMELAB_DNS_ALLOW_WRITES=true. That is concrete when-to-use context, but there is no routing guidance toward alternatives such as `dns_zones` or `expose_service`.

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 establish that this is a safe read-only, non-open-world operation. The description adds useful modality context by noting BIND export formatting, but it omits details such as pagination behavior or what data the export contains, even though an output schema exists.

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

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

The description is a single compact sentence with no wasted wording. The action-oriented structure is front-loaded and immediately useful.

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

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

The tool is simple and has an output schema plus annotations, so the description does not need to explain return values. Still, with 0% schema description coverage, it should at least clarify pagination parameters and the zone_id requirement for export.

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 0%, so the description must carry parameter meaning. It explains the action values and implies zone_id for export, but page, limit, and the explicit role of zone_id remain undocumented.

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 resource (Cloudflare DNS zones) and the two modes (list zones or export one zone in BIND format). It does not explicitly distinguish this tool from sibling tools such as dns_records, which prevents a top score.

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 action values imply when to use list versus export, giving some practical guidance. However, it does not state that export requires a zone_id, nor does it compare this tool with relevant alternatives such as dns_records.

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 readOnlyHint=false and destructiveHint=true, and the description reinforces this consistently rather than contradicting it. It adds genuinely useful context beyond the annotations: the approval gate, that remove is permanent, and that prune wipes ALL stopped containers. It omits any mention of the dry_run escape hatch, which would have closed the loop.

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?

Compact and front-loaded: the read-only vs mutating split comes before the destructive specifics. The telegraphic sentence fragments are efficient but slightly hurt readability, and one or two sentences on the undocumented parameters could have been added without bloat.

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

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

An output schema exists, so return values need no explanation, and the mutation/destruction story is well covered. However, for a 9-parameter multi-action tool with no schema descriptions, the missing parameter applicability (which params belong to which action, and what dry_run does) leaves the definition incomplete 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 0% across 9 parameters, so the description carries the full burden and covers only 'container' plus the action enum. Nothing explains all, tail, limit, since, offset, timeout, or dry_run — an agent cannot infer that tail/since apply to logs and limit/offset to list.

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?

Opens with a bare fragment ('Containers.') but immediately enumerates all nine actions, so the resource and operation set become unambiguous. It is distinguishable from docker_images and docker_inventory by the container-specific action list, though it never names those siblings explicitly.

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

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

Clearly separates the read-only actions (list, get, logs, stats) from state-changing ones (start, stop, restart, remove, prune) and states the precondition (human approval or HOMELAB_DOCKER_ALLOW_WRITES=true). It also notes 'container' is not needed for list or prune, but gives no guidance on when to reach for docker_images/inventory 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond them by stating the approval gate and the HOMELAB_DOCKER_ALLOW_WRITES=true escape hatch, plus what each destructive action actually destroys. It does not mention the dry_run flag or whether force changes deletion semantics, so some behavioral surface is uncovered.

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

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

Two sentences, no filler, with the read-only versus write distinction front-loaded before the per-action semantics. The only inefficiency is the one-word 'Images.' opener, which conveys little on its own.

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

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

An output schema exists, so return values need not be described. However, for a seven-parameter, multi-action destructive tool with no schema descriptions, the description leaves the pagination and force parameters and the dry_run safety valve undocumented, which is a meaningful gap.

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

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

Schema description coverage is 0%, so the description carries full burden for seven parameters. It only glosses the action values and implicitly image/tag; force, limit, offset, and especially dry_run (a safety-relevant flag) go entirely unexplained in both schema and 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 names the resource (Docker images) and enumerates the four actions in the enum (list, pull, remove, prune), which makes the tool's scope understandable. The opening fragment 'Images.' is terse and the verb is only implied by the action list, but an agent can still tell this is image management rather than container management.

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 clearly separates the safe read path (list) from the mutating paths (pull, remove, prune) and explains the difference between remove and prune, which is exactly the selection decision an agent needs. It does not say when to prefer docker_inventory or docker_containers over this tool, so sibling routing 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 already declare readOnlyHint=true and openWorldHint=false, so the 'Read-only' claim is consistent but adds little. The backend dependency for stacks is genuine added context, but pagination behavior (limit default 20, offset) and what happens when stack_id is omitted with kind=stacks are not disclosed.

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

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

Two sentences, zero filler, with the resource enumeration front-loaded and the conditional stack behavior immediately after. Every clause carries 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?

An output schema exists and annotations cover the safety profile, so the description only needs to carry invocation logic — which it largely does for kind and stack_id. The remaining gap is the undocumented pagination contract (limit/offset), which matters for a listing tool with a default page size of 20.

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 0%, so the description carries the burden: it clarifies kind's three modes and explains that stack_id is meaningful only with kind=stacks. However, limit and offset are never mentioned, and stack_id's default of 0 is left ambiguous (no stack vs. ignored).

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 concrete verb ('lists') and enumerates the exact resources returned: volumes, networks, or Portainer stacks. This distinguishes it from siblings like docker_containers and docker_images by resource type, though it never names those siblings explicitly.

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

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

Gives a real prerequisite ('stacks need the Portainer backend') and a conditional mode switch ('Pass stack_id with kind=stacks to get that stack's compose file'), which tells the agent when the stack branch applies. It stops short of explicit exclusions or naming where to go for containers/images 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 destructiveHint/openWorldHint annotations, the description discloses the pre-flight container check, the conditional CNAME only when tunnel_hostname is supplied, and that a plan is presented before any change is applied. It still omits whether an existing proxy host is overwritten or how DNS records are reconciled, which matters for a destructive, open-world mutation.

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

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

Two sentences, zero waste, with the effect chain and the plan-preview guarantee front-loaded. Every clause adds information an agent cannot get from the schema.

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

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

An output schema exists and the annotations carry the safety profile, so the description does not need to describe return values. It is nearly complete for a multi-step, multi-system mutation, with only idempotency/existing-resource behavior and dry_run semantics left open.

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 0%, so the description must carry parameter meaning. It usefully explains that tunnel_hostname is optional/conditional and that forward_host:forward_port form the forwarding target, but dry_run, dns_zone_id, and container_name's role are left unexplained.

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?

Starts with a specific verb+resource ('Expose a container') and enumerates the three concrete side effects: container check, Cloudflare CNAME, Nginx Proxy Manager host. It is clearly distinguishable from the opposite-number sibling teardown_service, though it does not explicitly contrast with proxy_hosts or dns_records.

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

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

Usage is implied by the effects described (use when you want a container reachable at a domain), but there is no explicit when-to-use vs. alternatives guidance. The dry_run parameter exists in the schema yet the description never says when to prefer a dry run over a live apply.

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 and outbound-network nature are covered. The description adds real behavioral value beyond that: results are scoped to *enabled* modules only, and a module with incomplete configuration surfaces the specific missing variable name rather than failing silently.

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

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

Two short sentences with no filler, and the module-scoping constraint is front-loaded. The opening fragment lacks a verb, which costs a little clarity, but nothing is wasted or repeated.

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

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

An output schema exists, so return shape needn't be explained, and annotations cover the safety profile. What remains missing for a diagnostic tool of this kind is when to reach for it (first-line troubleshooting?), whether it performs live network probes with associated latency, and how it relates to infrastructure_overview.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema is empty and fully described, leaving no gap for the description to fill.

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 the resource (every enabled module) and the two facts returned (connectivity, version), which is specific enough to distinguish it from plain module-listing siblings like homelab_modules. It is a noun phrase with no explicit verb ('reports'/'returns' is implied), which slightly blunts the statement of action.

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

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

There is no guidance on when to call this versus related tools such as infrastructure_overview, service_status, or homelab_modules, and no prerequisites or expected cost (a per-module connectivity sweep is likely slower than a metadata listing). The agent must infer the use case from the name alone.

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 readOnlyHint=true and openWorldHint=false, the description adds valuable behavioral context: settings values are never shown, only whether they are set, and it discloses whether writes are pre-approved. It does not cover auth or rate-limit behavior, so it falls short of a 5.

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

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

The description is two sentences and front-loads the main capabilities before giving the parameter instruction. It is efficient, though the phrase 'what each tool does' is slightly ambiguous.

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 read-only tool with one optional parameter and an existing output schema, the description covers the key behavioral facts an agent needs: no values are exposed, write pre-approval status is reported, and a module name yields detail. It could be clearer about what happens when no module is passed, but it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that passing a module name returns that module's full settings list, which adds meaning beyond the bare string parameter. However, it does not specify valid module names, accepted format, or default behavior when omitted beyond implication.

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 the tool's purpose in terms of the questions it answers: module on/off state, missing settings, write pre-approval, and tool descriptions. It is clear enough to distinguish this as an introspection tool, but it does not explicitly differentiate itself from siblings like infrastructure_overview or homelab_health.

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 one usage instruction: pass a module name for its full settings list. However, it does not say when to use this tool versus alternatives, nor when not to use it. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are aggregated across three external systems in a single request, but says nothing about freshness, latency, or what happens when one system is unreachable.

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

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

A single short sentence with the scope front-loaded and no filler. It is a fragment rather than a full clause, but nothing wasted.

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

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

An output schema exists, so return values need not be described, and a zero-parameter read-only tool carries little behavioral burden. What remains slightly thin is the framing of what the counts mean (e.g., whether this is a health/summary view).

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain. Baseline 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?

Names a specific verb ('Counts') and the three resources covered (Docker, Nginx Proxy Manager, Cloudflare DNS), which clearly distinguishes it from the sibling tools that each list one resource type. It stops short of saying what exactly is counted (containers? zones? records?).

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?

'in one call' implies this is the aggregate/summary entry point rather than a per-resource listing tool, so usage is implied. There is no explicit guidance on when to prefer this over homelab_health or homelab_modules, nor any prerequisite or exclusion.

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 the approval gate for writes and the blast radius of deletion ('affects every proxy host that uses it'), which is exactly the kind of context annotations can't express. It stops short of describing pagination or 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?

Three short sentences, front-loaded with the resource, then safety constraints, then the input format and destructive consequence. No filler.

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

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

An output schema exists, so return values needn't be explained, and the approval/destructive behavior is covered. However, with 8 parameters and zero schema descriptions, the missing coverage for limit/offset/dry_run/list_id leaves the definition meaningfully incomplete 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 0% across 8 parameters, so the description must carry the load. It only clarifies the allow/deny comma-separated IP/CIDR format and implicitly ties name/list_id to create/delete; limit, offset, dry_run, and action semantics are unaddressed. That leaves most parameters undocumented in both structured and prose fields.

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

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

The description names the resource ('IP access lists') and enumerates the operations (list, create, delete), so an agent can tell this manages proxy ACLs rather than proxy hosts or certificates. It is clear but lacks an explicit 'manage' verb and doesn't contrast itself with the proxy_* siblings beyond resource name.

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

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

Explicitly states list is read-only and that create/delete require approval or ALLOW_WRITES, which is actionable when-to-use context. It also warns that deleting a list affects every proxy host using it. It doesn't name alternatives, but for a resource-scoped CRUD tool that's a minor gap.

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 the tool as destructive and non-read-only, but the description adds genuinely non-derivable behavior: the list action is safe while request performs an external Let's Encrypt issuance, issuance is gated behind approval or an ALLOW_WRITES flag, and it will fail if the domains are not publicly reachable. That is real operational context beyond the hints. It does not mention the dry_run escape hatch, which is the one notable omission for a destructive action.

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

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

Three short sentences, front-loaded with the resource, then the safe action, then the risky action with its prerequisites. Nothing is padded, though the telegraphic fragments ('SSL certificates.', 'list is read-only.') cost a little readability.

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

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

An output schema exists, so return values need not be described, and the destructive/approval model is covered. What remains missing is how to scope a request (domain_names) and how to preview it (dry_run), which leaves an agent with a destructive tool under-documented at the call site.

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 0% across 5 parameters, so the description must carry the burden and it largely does not. It explains the meaning of only one parameter value pair (action=list vs action=request); domain_names, limit, offset, and especially dry_run — the only way to preview a destructive issuance — get no mention at all.

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 fragment 'SSL certificates' names the resource, and the two following sentences name the two modes of operation (list vs request), so the agent can tell this tool apart from proxy_hosts or dns_zones. It stops short of a single clean verb+resource statement, but the scope is unambiguous.

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

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

It gives clear selection conditions: use list for a read-only view, use request to obtain a new Let's Encrypt certificate. It also states prerequisites (approval or ALLOW_WRITES, and DNS must resolve to reachable domains), which is exactly the context an agent needs before choosing request. It does not name a sibling alternative, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context beyond annotations: which actions are read-only, that mutations require human approval or a configured override, and that dry_run avoids the approval prompt. It does not detail exactly what data is destroyed or how updates merge with existing settings.

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 compact sentences with no wasted language. Read-only behavior, mutation approval, and dry_run preview are front-loaded in a logical order.

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

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

For an 11-parameter tool with 0% schema description coverage, the description is not complete enough about what the individual fields mean or how they affect each action. It covers mutation safety and dry_run well, and an output schema exists, but the substantial parameter documentation gap leaves an agent under-equipped to invoke create or update 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 0% for 11 parameters, so the description must carry the burden. It explains action modes and dry_run meaningfully, but leaves domain_names, forward_host, forward_port, host_id, ssl, force_ssl, block_exploits, limit, and offset undocumented.

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 the resource ('Proxy hosts') and explicitly maps its action modes to read-only versus mutating behavior. It does not differentiate from siblings such as proxy_redirections or proxy_certificates, but an agent can still infer the tool's purpose from the action enum and description.

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

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

It clearly states that list/get are read-only while create/update/delete change NPM and require approval or HOMELAB_PROXY_ALLOW_WRITES=true, and that dry_run=true previews without asking. It does not explain when to choose this tool over sibling proxy tools, but it gives strong operational guidance for the supported actions.

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 readOnlyHint=false and destructiveHint=true, so the destructive nature is known structurally. The description adds genuinely new context beyond that: the approval / ALLOW_WRITES gating requirement for create and delete. It does not disclose what a delete removes (the rule only, vs. associated certs/hosts) or whether writes are reversible.

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

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

Two short sentences with no filler, and the most decision-relevant fact (approval gating for writes) is stated up front. It is arguably too terse rather than padded, but on the conciseness axis it is efficient.

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 9-parameter, 3-action tool with zero schema documentation, the description should map parameters to actions (e.g., create needs domain_names + forward_domain; delete needs redirection_id). An output schema exists so return values need not be explained, but the per-action parameter requirements and the meaning of dry_run are left entirely to guesswork.

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 0% across 9 parameters, so the description carries the full burden and does not meet it. It clarifies only the `action` enum values; `domain_names`, `forward_domain`, `forward_scheme`, `preserve_path`, `redirection_id`, `dry_run`, `limit`, and `offset` are entirely undocumented, including which are required for which action.

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?

"HTTP redirections" names the resource and the second sentence enumerates the three actions (list/create/delete), which is the key fact that this is a multiplexed action tool. But there is no verb describing what managing a redirection actually entails (e.g., domain forwarding rules), and no differentiation from siblings like proxy_hosts or dns_records beyond the noun.

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

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

It distinguishes the read path from the write paths ("list is read-only; create and delete need approval"), which implies when each action is appropriate. It gives no guidance on when to prefer this tool over proxy_hosts, dns_records, or expose_service, and no prerequisite context for first-time users.

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 that the payload spans three related entity types (container, proxy hosts, DNS records), which is useful framing beyond the annotations, but it says nothing about scoping behavior, empty results, or what open-world lookups it performs.

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

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

A single tight sentence that front-loads the core idea and enumerates the three data sources. It wastes no words, though brevity comes partly from omitting information that matters.

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 structure needn't be restated. However, a composite lookup tool with three fully undocumented parameters and no sibling differentiation leaves key decisions (which id to pass, what happens when domain is blank) unaddressed.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions the three parameters. The phrases 'the container', 'the domain', and 'its DNS records' loosely hint at container_name, domain, and dns_zone_id, but nothing explains optionality, defaults, or how domain/dns_zone_id narrow the aggregate.

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 says it is an aggregated view of a service comprising the container, proxy hosts, and DNS records, which conveys the resource. But 'One view of a service' is noun-only, with no verb identifying this as a read/lookup, and nothing distinguishes it from infrastructure_overview or homelab_health.

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

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

There is no statement of when to use this composite view versus querying docker_containers, proxy_hosts, and dns_records separately, and no guidance on when to prefer infrastructure_overview. The agent must infer the selection criteria entirely.

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 destructive=true and openWorld=true, so the description's added value is the explicit blast radius (proxy host plus optional DNS record) and the order in which they are removed, plus the note that a plan is presented to the person first. It leaves dry_run unexplained, which matters for a destructive tool with 0% schema coverage.

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

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

Two sentences, no filler, and the destructive action is front-loaded ahead of the conditional clauses. Every clause carries information the agent needs.

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

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

Output schema exists so return values need no explanation, but for a destructive 5-parameter tool the description should still explain what dry_run does and what dns_zone_id is for. The core destructive semantics are covered; the preview/scope controls are not.

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

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

With 0% schema description coverage the description must compensate, and it does cover three of five parameters: domain lookup by name, proxy_host_id as an override, and dns_record_id as the opt-in for DNS deletion. dry_run and dns_zone_id are never mentioned, so the compensating work is only partial.

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 resources (delete the proxy host and, optionally, the DNS record) and anchors itself to a named sibling by declaring it the reverse of expose_service. An agent can distinguish it from every other sibling 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?

"Reverse expose_service" gives a clear selection rule against that specific sibling, and the conditional phrasing tells the agent when the DNS record is also removed. It does not say when NOT to use it (e.g., when only the DNS record should be removed, or when the host was created outside expose_service).

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