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

With no annotations, the description carries the full behavioral burden and does so extensively: it explains the internal-CA trust requirement, ACME admin-token gating, disabled ACME errors, refusal codes, idempotency implications, row storage on `withheld`, and the orthogonal `cert_state` values. This is unusually complete for a mutation/deployment 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 main purpose and sibling distinction are front-loaded, and the structure is readable. It is long and enumerates several error codes and return states that could be trimmed, but most of that detail is useful because there are no annotations and no output schema.

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

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

The description is complete for a complex proxy/certificate operation: it covers prerequisites, auth requirements, refusal modes, return shape, URL visibility in sibling tools, and certificate state transitions. With no output schema and no annotations, this level of detail is appropriate.

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 `name`, `domain`, `acme`, and `idempotency_key` in detail. The prose reinforces domain grammar, ACME authorization, and service-only exposure, but adds little parameter syntax or meaning beyond what is already present in the schema.

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

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

The description states a specific verb and resource: serve a deployed app at a domain owned by the caller, through this node's own proxy. It explicitly distinguishes this from `share_service`, so the agent can tell which sibling to choose before opening either schema.

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

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

It clearly frames the alternative: `share_service` uses Nerdit's domain over the cloud tunnel, whereas this tool serves at the root via the node's embedded Caddy. It also states the key prerequisite the daemon cannot fulfill: DNS A/AAAA/CNAME must already point at this machine.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it explains that the machine verifies each delivery's signature before the app sees it, forwards the provider's headers and exact body to path, and that no secret travels through this tool. It also discloses prerequisites, null URL behavior, refusal codes, and idempotent replay semantics.

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 purpose, then explains the delivery behavior, secret handling, prerequisites, and refusals in a compact sequence. Despite its density, every sentence contributes operational information an agent needs.

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

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

For a mutation tool with no annotations and no output schema, the description is complete enough: it covers the creation workflow, signature verification, returned url and secret_key, sharing and linking prerequisites, refusal modes, and replay behavior. An agent has what it needs to call add_hook 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 explains all parameters, including sender values and header/prefix conditions. The description adds some workflow meaning around path and the returned secret_key, but does not add parameter-specific semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: give a deployed app an inbound webhook address that a provider can POST to. It clearly distinguishes this from siblings like list_hooks, remove_hook, and set_secret by describing the creation workflow and the follow-up secret-storage step.

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 strong usage context: only deployed service apps can be exposed, models and databases are refused, the app must be shared, and the machine must be linked before a URL appears. It also routes the follow-up signing-secret storage to set_secret, though it does not explicitly say when to use list_hooks or remove_hook for existing hooks.

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

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

With no annotations, the description carries the burden and does disclose two genuinely important traits: the apply is atomic ('all-or-nothing', one invalid key rejects the whole document per schema) and a dry run is side-effect-free and exempt from both If-Match and idempotency keys. It still leaves out permission/auth requirements and what the dry-run plan response looks like.

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, zero filler, with the atomicity guarantee front-loaded and the dry-run caveat immediately after. Nothing could be removed without losing 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?

For a 4-parameter mutation tool with no annotations and no output schema, the description plus the rich schema documentation covers what an agent needs: atomicity, the dry-run escape hatch, and the stale-ETag/validation failure modes. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds cross-parameter semantics that the individual fields only partially state: that a dry run needs neither an If-Match nor an idempotency key. That relational constraint is useful and slightly exceeds what the schema spells out for idempotency_key.

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

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

The description gives a specific verb and resource ('declaratively apply a multi-section daemon config document') plus the key semantic of the operation ('all-or-nothing'), which is more than a restatement of the name. It does not, however, contrast itself with the sibling set_config, whose merge semantics it only references indirectly via 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?

Usage is implied by 'declaratively apply' and 'all-or-nothing' — an agent can infer this is the whole-document path versus set_config's incremental path — but the description never names that alternative or states when to prefer one over the other. The dry-run sentence guides parameter choice rather than 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?

With no annotations, the description carries the full burden and does so: asynchronous semantics (``applied`` means accepted, not healthy), refusals before first build, dry run creating nothing and minting no idempotency key, 409 ``project.owned``, and no rollback across services via ``project.apply_incomplete``. It also documents sandbox defaults, the remediation code ``image_needs_privileges``, and the port/health-probe contract.

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

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

Front-loaded: purpose first, then the operating loop, then response shape, then failure semantics. It is long, and the SANDBOX/PORT CONTRACT block is verbose, but nearly every sentence encodes a concrete failure mode or default an agent would otherwise get wrong; trimming would risk losing actionable detail.

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

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

No output schema exists, so the description compensates by naming the response fields (``services``, ``label``, ``action``, ``plan``, ``public_urls``, ``missing``, ``failed``) and their semantics. For a complex, multi-stage deploy tool it covers prerequisites, ordering, identity conflicts, partial-failure recovery, and environment defaults.

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 baseline is 3, but the description adds meaning the schema does not: ``dry_run`` creates nothing and mints no idempotency key, and the PORT CONTRACT clarifies how the ``port`` argument interacts with ``nerdit.toml`` ``[deploy].port`` and the default 8000. It does not re-explain ``repo_url``/``token_ref``/``ref`` beyond the schema, which is appropriate.

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

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

States a specific verb and resource: deploy every ``[services.<name>]`` of a project's ``nerdit.toml``. It explicitly contrasts itself with ``deploy_app``/``deploy_git`` for ``[deploy]``-only manifests, so an agent can tell it apart from the sibling deploy tools without inspecting schemas.

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

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

Gives an explicit ordered loop (get_project → dry_run → vars set → apply → wait_for_service → diagnose_service) and the branch condition ``waiting_for_variables``. It names the alternatives for manifests that are not declarations, and explicitly forbids inventing secret values in chat.

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

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

With no annotations, the description carries the disclosure burden and does well: it declares 'pure in-memory read' and notes role-aware behavior where admin callers receive additional fields. It does not discuss failure modes, caching, or permission requirements in more detail, but the key safety profile is clear.

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 first sentence front-loads the core purpose, and the second paragraph adds useful context. There is mild repetition in 'learn what the daemon can do' following 'Describe this daemon,' and the parenthetical list is long, but overall 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?

There is no output schema, so the description must explain return contents, and it does: version, role/quotas, URL grammar, backends, buildpacks, proxy details, deploy limits, git allowlist, feature flags, plus admin-only fields. That is complete enough for a zero-parameter introspection call.

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 parameter semantics are not applicable; baseline 4 applies. The description appropriately adds no parameter information because there is none.

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

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

The description gives a specific verb and resource: 'Describe this daemon,' then enumerates what is returned (version, caller role/quotas, URL grammar, backends). It also positions the tool as a first-stop discovery call rather than endpoint probing, which distinguishes it from config/diagnostic siblings like get_config or doctor.

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?

'call it first to learn what the daemon can do ... instead of probing endpoints' provides an explicit trigger and an alternative behavior. It does not explicitly state when not to use it or name sibling alternatives, so it stops short of the top score.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose some return content (GPU usage and services up) and implies an aggregate read-only snapshot, but it omits important traits such as freshness, auth requirements, and exact return shape, leaving meaningful gaps for an unannotated 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 definition is a single front-loaded sentence with no wasted words. It quickly conveys the verb, resource, scope, and example metrics, which is appropriately sized for a parameterless stats tool.

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

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

Given a zero-parameter stats tool with no output schema, the description should explain the return value more completely. It names a few metrics but does not indicate whether the response includes other cluster health fields, formatting, or freshness, so an agent has only a partial picture of what to expect.

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 there are no parameter semantics to document; the baseline for a parameterless tool is 4. The description appropriately does not speculate about parameters that don't exist.

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

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

The description uses a specific verb and resource ("Get aggregate cluster metrics") and names example metrics ("GPUs in use/total, services up"), which is clearer than a tautology. It implies an aggregate/cluster-level view rather than per-resource listing, but does not explicitly distinguish itself from siblings like service_stats, list_gpus, or list_services.

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 what the tool returns but gives no guidance on when to use it versus alternatives such as service_stats or list_gpus. There are no exclusions, prerequisites, or situational cues to help an agent choose among the many sibling diagnostic/listing tools.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses asynchronous return with state 'building', daemon-side image pull and launch, polling requirements, server-side write-only password handling, and that passwords are never returned. It also explains how applications bind to the database and which environment variables are injected.

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 purpose is front-loaded, and the following paragraphs are organized around async behavior, lifecycle routing, credentials, and application binding. Despite its length, each section provides operationally relevant context without 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 zero annotations, no output schema, and fully documented optional parameters, the description covers the critical unknowns: asynchronous state, polling, lifecycle boundaries, credential non-return, and binding semantics. An agent has enough information to invoke the tool and interpret the immediate result 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 name, backend, and idempotency_key fully. The description does not add parameter-level 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 and resource: provisioning a managed database as a database workload. It clearly distinguishes creation from lifecycle operations by saying stop/restart/delete go through service tools, so an agent can tell it apart from siblings like restart_service or list_databases.

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 explains the asynchronous provisioning flow and explicitly routes polling to list_databases or get_service until db_ready is true. It also explicitly excludes lifecycle operations by directing stop/restart/delete to existing service tools.

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

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

No annotations are provided, so the description carries the full burden and does: it discloses ownership semantics, the admin bypass, persistence until delete_project, and the three distinct 409/422 failure modes with their error codes and meanings. This is exactly the failure-mode context an agent cannot infer from structured fields.

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?

Purpose and effect are front-loaded, then lifecycle, then error codes, in a logical order with no filler. It runs long and packs multiple escape-coded conditions into one paragraph, which costs a bit of scannability, but every clause conveys distinct behavioral 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?

For a two-parameter creation tool with no annotations and no output schema, the description covers ownership, lifecycle, and every documented failure path. The only gap is that it never indicates what is returned on success (e.g. a project record or just the reserved name), which the agent must discover empirically.

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

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

Schema coverage is 100%, so both parameters (name format rules, idempotency_key retry semantics) are already fully documented in the schema. The description adds contextual meaning about what the name reservation implies, but no syntax or defaulting detail beyond the schema, which is the baseline-3 case.

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 specific verb+resource ("Create an empty project") plus the non-obvious effect of reserving the name for the calling token. It is clearly distinguishable from siblings: deploy/serve_model/create_database implicitly produce projects, create_project pre-claims a name, and delete_project releases it.

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

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

Explicitly states when NOT to use it ("You rarely need this before a deploy — every deployed app already becomes a project of its own name") and when it is warranted ("it lets you hold a name ahead of the first deploy"). Competing paths (deploy, serve_model, create_database, set_secret) are named with the condition that selects each.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses destructive cascade order, that the row is deleted only if all services succeed, the 409 project.delete_incomplete response with deleted/failed lists, idempotent re-run behavior, and the owner-or-admin authorization requirement.

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

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

Front-loads the core action ('Delete a project:...') and every following sentence adds concrete behavior (cascade, refusal shape, idempotency, auth). It is dense and slightly long-winded with parentheticals, but no sentence is 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 mutation with no annotations and no output schema, the description covers order of operations, failure response, idempotency, and permissions well. The one meaningful gap is that it does not restate that purge destroys durable state (secrets/data/images/workspace), leaving that critical destructive detail entirely to the schema.

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

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

Schema coverage is 100%, so name, purge, and idempotency_key are already fully documented in the schema, establishing the baseline of 3. The description's mention of 'releasing the name' mildly reinforces the name parameter but adds no syntax, defaults, or purge semantics beyond what the schema provides.

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

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

States a specific verb and resource ('Delete a project') and enumerates exactly what is removed and in what order, including that the name is released. It is distinguishable from sibling remove_service by explicitly noting the project row and the cascade through all contained services.

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?

By saying services go through 'the same cascade as remove_service,' it implicitly tells the agent that single-service removal belongs to remove_service and full-project teardown belongs here. It does not fully spell out when-not/exclusions, so it stops short of a 5, but the routing signal is clear.

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

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

With no annotations, the description carries the full behavioral burden and does so extensively: async acceptance vs. app readiness, local-path transport restrictions, [deploy] key handling and ignored keys, release/cutover failure semantics, dry_run no-write behavior, sandbox capability defaults, and port publishing/health-check rules. These are substantive behavioral disclosures, not restatements of schema.

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

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

It is front-loaded with the usage condition and async contract, and structured into clear operational concerns. It is unusually long and packs deployment manual detail into the description, but nearly all of it is actionable for a complex deploy tool, so it avoids fluff even if it is not terse.

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 12-parameter deploy tool with no annotations and no output schema, the description is complete: it explains what is returned on success, what next_step is, what dry_run and rollback responses omit, and how to follow up. Nothing critical to correct invocation appears missing.

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

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

Schema coverage is 100%, so the schema already defines each parameter. The description still adds cross-parameter meaning: rollback reads only name and idempotency_key, path is local-process-only, build_settings nulls reset to repository/default, and public_env refuses secrets. This goes beyond the schema, though some of it duplicates schema text.

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 states a specific verb and resource: deploying a local folder (build + run + URL), with rollback as a secondary mode. It explicitly distinguishes this tool from deploy_git, deploy_template, deploy_app, and the write_app_files path, so an agent can route correctly without opening another schema.

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

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

The description gives an explicit selection rule ('Use when: the source is a local folder'), states the asynchronous follow-up (wait_for_service), and names alternatives for remote/HTTP connections (write_app_files + deploy_app, deploy_git, deploy_template). It also clarifies rollback usage and dry_run boundaries.

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

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

With no annotations, the description carries the full behavioral burden and does so extensively: async behavior, dry-run side effects, release failure semantics, env/secret handling, response fields, sandbox constraints, and port contract. No contradiction with annotations is possible because none are provided.

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 key usage rule and sibling distinctions, and it is organized into useful paragraphs. However, it is unusually long and dense for a tool description; nearly every detail is relevant, but the length reduces scannability.

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 complex mutation tool with 10 parameters, no annotations, and no output schema, the description is complete enough to invoke and interpret correctly. It covers usage, behavior, response shape, failure semantics, sandbox requirements, and build/deploy configuration.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantial parameter meaning beyond the schema. It explains dry-run plan behavior, port and sandbox implications, build_settings reset/precedence rules, env secret overrides, and idempotency-key minting behavior.

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

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

The description states a specific verb and resource: deploying the workspace app of the same name. It explicitly distinguishes this tool from sibling tools `deploy` and `deploy_git`, so an agent can select it correctly without opening other schemas.

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

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

It gives explicit triggers and conditions: use after `write_app_files`, call again after each edit, and follow asynchronously with `wait_for_service`. It also names alternatives and exclusions, including that `redeploy_service` refuses workspace apps by design.

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

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

With zero annotations the description carries the full burden and does so in depth: async lifecycle, release runs once before traffic with revert-the-image-never-the-data failure semantics, cutover null vs false, dry_run writing nothing, and the exact response fields (summary/hints/next_step vs dry_run warnings). It also discloses the sandbox default (cap_drop ALL, no-new-privileges), the operator-relaxable caveat, and the image_needs_privileges remediation code.

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

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

Front-loaded well with 'Use when' and the async warning, but the body sprawls: the PORT CONTRACT material restates the port priority chain already in the schema, and the sandbox/root-entrypoint section is long enough to bury operational facts. Dense and mostly load-bearing, yet clearly over-budget for a tool description.

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 14-parameter, no-annotation mutation tool with no output schema, everything an agent needs is present: prerequisites, async follow-up, failure modes, response shape, port/privilege contract, and secret-handling boundaries. Nothing material is left for the caller to guess.

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 real meaning on top: which nerdit.toml [deploy] keys are honored and that everything else is IGNORED and echoed back in hints, how build_settings interacts with a repo Dockerfile, and that public_env values are shown in clear in a dry run while secret references are refused.

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 chain and resource: clones repo_url server-side, then builds and runs it, i.e. deploy-from-Git. The opening 'Use when: the app lives in a Git repo' instantly separates it from the local-directory siblings like deploy / deploy_app / deploy_template.

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

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

Explicit entry condition ('Use when: the app lives in a Git repo') and an explicit follow-up routing ('Asynchronous — follow with wait_for_service'), plus a clear dry_run branch for plan-only use. It never names the alternative sibling (deploy) as an exclusion, so the agent must infer when-not, keeping it a notch below 5.

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

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

With no annotations, the description carries the full burden and does well: async semantics ('a 201 here means the build was accepted, not that the app is up'), the follow-up call, override precedence (existing Dockerfile wins over build_settings), null-resets-vs-omission semantics, unsupported secret mounts, and an explicit plaintext-transcript warning about passing secrets.

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

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

Front-loads the trigger, then the async contract, then behavior, then the safety warning. Dense but nearly every sentence carries operational information; the AI-binding paragraph is the longest block and borders on 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 12-parameter mutation with no annotations and no output schema, the description covers the response shape (summary, hints never empty, next_step), the async contract, and the destructive/secret-handling risks. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: env/overrides layer over template defaults, public_env is public build-time variables with secret references refused, and AI bindings get injected as NERDIT_AI_<NAME>_*. The gpus/vendor/port interactions are left to the schema.

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

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

States the specific action chain: resolves template_id, clones the catalog repo server-side, deploys under name. An agent can tell it is the template-based deploy path from list_app_templates. Sibling differentiation against deploy_app/deploy_git is only implied, not stated.

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?

'Use when: you want a starter app' plus the explicit instruction to follow with wait_for_service gives clear entry and exit conditions. dry_run=True is offered as the preview path. It never says when NOT to use this versus deploy_app or deploy_git.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses the owner/admin authorization requirement, that the daemon resolves membership, that output reuses diagnose_service's failure bundle, and that it 'grants no additional authority' (a useful privilege-escalation clarification). It omits return shape and read-only nature, but the key behavioral facts are present.

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

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

Very short and front-loaded: purpose first, then the ID preference, then behavior. The 'under the existing owner/admin policy' clause is slightly awkwardly placed but no sentence is wasted.

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

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

For a 3-parameter, fully-schema-documented tool with no output schema and no annotations, the description covers authorization, escalation posture, and result provenance. What is missing — contents of the failure bundle — is minor given the absence of an output schema.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema, including the immutability/retired-ID rationale and the log_tail clamp. The description only echoes the 'prefer the ID' guidance, adding negligible meaning beyond the schema.

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

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

States a specific verb and resource with scope: 'Diagnose one service of an explicit project.' Naming diagnose_service as the bundle source implies the relationship to the sibling, though it never explicitly contrasts when to pick this over diagnose_service.

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

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

The only usage steering is 'Prefer an immutable project ID,' plus the mention that it reuses diagnose_service's bundle. There is no explicit statement of when to call this instead of diagnose_service, or of any preconditions beyond the owner/admin policy note.

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

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

With no annotations, the description carries the burden and does well: it declares this is an 'Owner-or-admin read', discloses exactly what sensitive data the bundle can expose (env/secret key *names*, app log lines) and what it never exposes (secret values), and notes the log tail is bounded. It stops short of saying whether the fresh health probe makes the call slow or what happens when the service has no deploy history.

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

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

Front-loaded with an explicit 'Use when:' clause and only two further sentences, both of which add real routing or safety information. Slightly dense with reST-style double-backtick markup that reads as noise rather than signal.

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?

No output schema exists, and the description compensates by enumerating the bundle's return contents and flagging remediation_code as the branching field, plus the safety profile. An agent knows what it will get back and how to act on it.

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

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

Schema coverage is 100%, so the two parameters are already fully documented including the default and the [1, 200] clamp. The description adds only the phrase 'bounded log tail', which is marginal value over the schema; baseline 3 applies.

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

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

States a specific verb+resource (diagnose a failing service) and enumerates exactly what the bundle contains: deploy phase, crash forensics, health probe, AI-binding readiness, log tail, remediation_code. This clearly separates it from service_logs and get_service, which an agent could otherwise confuse it with.

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

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

Explicit trigger ('Use when: a service is failing and you need the reason, not the logs'), explicit sequencing ('call it after wait_for_service returns failed'), and an explicit anti-pattern to avoid ('instead of scraping logs'). That is a when/when-not/alternative triad.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that checks are timeout-bounded server-side, that details expose key names only (no paths or secret values), and that it is safe for every role. Missing only notes on latency/cost or whether checks can be selectively run — but there are no params anyway.

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, verb-and-scope front-loaded, followed by the return shape and the safety guarantee. Nothing is padded or restated from 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?

No output schema exists, and the description compensates by describing the return shape (per-check {status, detail} plus a worst-of top-level status) and the safety characteristics of those details. An agent has everything needed to call it and interpret the result.

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. The description correctly implies no input is needed, and the enumerated check domains clarify what the argument-less call will cover.

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 ('Run') and resource ('daemon's bounded environment health checks') with the checked domains enumerated (docker/gpu/proxy/db), which distinguishes it from per-service siblings like diagnose_service and diagnose_project. It stops short of naming those siblings explicitly, so the distinction is inferred from scope rather than stated.

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 scope ('daemon's environment health') implies a preflight/triage use case, but the description never says when to call this versus diagnose_service, diagnose_project, or capabilities/proxy_status. Usage must be inferred from the enumerated check categories.

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

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

With no annotations, the description carries the full burden and does so: artifact custody (server-side tar, metadata only returned, never served over HTTP), retention (last N per DB pruned hourly, not an archive), per-call idempotency key semantics making retries unsafe, authorization model (owner-or-admin plus token scope), and a branchable error-code catalogue including the distinction between dump.in_progress and backup.in_progress.

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?

Purpose is front-loaded in the first sentence and the remainder is organized under explicit CUSTODY / RETENTION / TIMEOUT / authorization headings, so it scans well. It is long and dense, and the enumerated 409 codes push toward the verbose end, but nearly every clause carries decision-relevant information for a tool with no annotations.

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-ish long-running operation with no annotations and no output schema, the description supplies everything an agent needs: the returned metadata fields (basename, size, sha256, engine, format, duration), how to use the basename with restore, retention lifetime, and the failure modes to branch on.

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 would be 3, but the description adds real meaning to timeout_s by explaining that the default matches the client read budget rather than the route's own 900s, and that a client-side timeout does not mean the server-side dump failed. Input `name` is only lightly reinforced beyond the schema, hence not a full 5.

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

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

States a specific verb and resource ("Capture a logical, application-consistent dump of a managed database") and immediately names the underlying engine tooling (pg_dump custom format, redis-cli --rdb). It also distinguishes itself from the sibling volume-backup path, so an agent can tell which backup mechanism it is choosing.

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

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

Explicit timing guidance: "the dump to take before a migration or a destructive change", contrasted against the filesystem-based volume backup. It also gives operative alternatives for the edge cases — on timeout call list_database_dumps rather than retrying, and restore is deliberately out of scope on the CLI/REST. When-to-use, when-not-to-retry, and the alternative path are all spelled out.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the aggregation dimensions, included metrics, and two important exclusions, but it does not mention permissions, pagination, ordering, rate limits, or the exact return format.

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 compact sentences with no waste. The core resource and metrics are front-loaded, and the limitations are stated briefly afterward.

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

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

For a two-parameter, read-only usage reporting tool with a fully described input schema, the definition is largely complete. It explains the included metrics and exclusions, though without an output schema it could say slightly more about the returned grouping structure.

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 has 100% description coverage, with both parameters documented directly. The description reinforces that usage is reported per UTC day and app, but it does not add parameter details beyond the schema's existing descriptions.

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

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

The description clearly states the resource and metrics returned: AI gateway usage grouped by UTC day, app, and alias, including requests, tokens, and upstream errors. It is specific enough for an agent to understand what the tool provides, though it does not explicitly distinguish itself from sibling stats tools such as cluster_stats or service_stats.

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 description: this tool is for AI gateway usage reporting. The note 'No cost estimate, no prompt trace' usefully excludes expected content, but there is no explicit guidance about when to choose this tool over sibling statistics or audit tools.

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

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

With zero annotations the description carries the full burden and does so richly: secret values are never returned (only ${secrets.X} refs and env key names), ai bindings are injected at launch as NERDIT_AI_<NAME>_* vars, deploy.release failures abort and revert the image, and cutover null vs false is spelled out. It also names which fields accept secret refs — high-value behavioral context an agent could not get elsewhere.

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?

Purpose is front-loaded in the first sentence and subsequent paragraphs map to real returned fields rather than restating the name. It is dense but mostly earns its space; the parenthetical '(write idempotent migrations)' is advisory padding that could be trimmed.

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

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

No output schema exists, so the description must convey the return shape — it covers deploy fields, ai bindings, env_keys, and secret refs, which is the bulk of what matters. It does not enumerate other config sections (db, domains, edge_auth) even though edge_auth.password is referenced, leaving the full response shape partially described.

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 the single 'name' parameter already has a detailed description with 404 semantics, so the schema does the heavy lifting. The tool description adds no parameter-level information (no naming conventions or format), which is acceptable at this coverage level but earns only the baseline.

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

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

Opens with a specific verb+resource+scope: 'Read a deployed app's daemon-persisted config (deploy fields + ai bindings)'. An agent knows exactly what it gets. It does not, however, distinguish itself from the nearby sibling 'get_config' or 'get_service', leaving the sibling boundary to inference.

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 'deployed app's' implicitly scopes usage to apps (kind=service) rather than models or databases, but the explicit exclusion only appears in the schema's name description, not the tool description. No alternative tool (get_config, get_service) is named, so when-not branches must be inferred.

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

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

With no annotations at all, the description carries the full burden and does well: it discloses the admin requirement, that non-admin tokens get a structured 403 "forbidden" error, that it returns an AuditLogPage dict, and that filtering happens in SQL. It does not state result ordering or default sort, which matters for a log-reading tool.

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

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

Three short paragraphs, front-loaded with the verb, resource and scope; the operational advice about filtering over paging comes last where it belongs. No sentence repeats the schema, and the RST-style backticks are the only minor friction.

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 ten-parameter read tool with no output schema, the description supplies the return type, the auth failure mode, and the filter-composition rule. The remaining gap is ordering/pagination behavior across pages, which the cursor parameter hints at but the description never explains.

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 per-param meaning is already covered and a 3 would be the floor. The description still adds value beyond the schema by explaining that all filters compose with AND and are applied server-side, which tells the agent how to combine the ten optional filters rather than just what each one does.

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

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

States a specific verb and resource ("Read the audit log") plus the key scoping constraint ("admin-scoped") and paging bound. It's clear what it does, but it never distinguishes itself from the closest sibling, get_events, which an agent could easily confuse with it.

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

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

Gives real usage direction: admin token required, filters compose with AND, and "narrowing is cheap, so prefer a filter over paging" is actionable advice about how to call it. It stops short of naming alternatives (e.g. get_events) or saying when not to use this tool.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that secret-bearing values are redacted server-side, which is meaningful. It does not explicitly describe read-only safety, permission requirements, or the exact response shape, leaving clear gaps.

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

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

The description is two short sentences and front-loads the core action immediately. Every phrase adds useful scope or behavioral information, with no wasted text.

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 single-parameter config read, the description covers the main action, section-vs-all behavior, and redaction. Because there is no output schema, it could say more about the return structure, but the core behavior is adequately conveyed.

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 the optional 'section' parameter thoroughly, including examples and the 404 behavior for unknown sections. The description reinforces the omit-to-return-all behavior but adds no new parameter semantics beyond the schema, matching the baseline for high coverage.

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

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

The description uses a specific verb and resource: 'Read daemon config.' It clarifies that the tool returns either one section or all sections when omitted, which is useful scope detail. It does not explicitly distinguish itself from sibling tools such as set_config or get_app_config, so it stops short of a 5.

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

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

The description implies usage by saying it reads daemon config and returns one section or all sections when omitted. However, it gives no explicit guidance on when to use this tool instead of related siblings like get_app_config or set_config, nor does it state exclusions or prerequisites.

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

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

With no annotations, the description carries the load and does disclose real behavioral facts: the feed is durable, it is autonomous-transition oriented, and it is readable by any authenticated token (auth requirement). It omits return shape and retention/pagination behavior, and the "two directions" warning is stated so elliptically that it doesn't say which parameter goes which way.

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

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

Front-loaded with a "Use when:" clause and kept to three short sentences with no filler. The phrase "picking the wrong one walks the wrong way through history" is atmospheric rather than precise, costing a bit of clarity for its 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?

For a five-optional-parameter read tool with no output schema and no annotations, the description covers purpose, auth scope, durability, and the directionality trap. What's missing is minor: the vocabulary of event types is only sampled, and nothing is said about what a returned page contains beyond the schema's next_cursor reference.

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 explains limit clamping, type filtering, and the cursor/since_id mutual exclusion with 400 errors. The description reinforces the bidirectional model but adds no syntax, format, or constraint detail beyond what the schema states, so the baseline 3 applies.

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

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

Describes the tool concretely as the durable feed of autonomous daemon transitions, with example event types (service.failed, model.ready) that make the resource tangible. It implicitly separates itself from service_logs and get_audit by emphasizing daemon-level events readable by any token, but never names those siblings, so the distinction must be inferred.

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?

"Use when: you need the daemon's own account of what it just did" gives a clear triggering condition, and the note about two directions warns that argument choice changes traversal. No explicit when-not or named alternative among the many log/audit siblings, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses 403 for out-of-scope names, 404 for unknown names, that secret values never appear, that readiness may be null when a secret is needed, and that home is always this node today. Missing only a clear statement that this is a read-only, non-mutating call and any freshness/caching caveat.

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?

Opens with the one-line value proposition, then front-loads the return inventory and closes with error and secrecy caveats. No sentence is filler; the markup-heavy phrasing is dense but each clause carries distinct 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?

There is no output schema, so the description must describe the return shape and it does so comprehensively, down to the nested readiness flag and the addresses/home fields. Combined with error semantics and the secret-exclusion guarantee, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the schema itself already explains the immutable prj_ ID vs name tradeoff and the retired-ID trap, leaving little for the description to add. The 403/404 mentions give peripheral meaning to name resolution but no additional format or syntax detail, so baseline 3 is right.

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 and resource and enumerates exactly what comes back: services with state/last deploy/endpoint, referenced models and databases with readiness, public addresses, and home node. This is clearly distinguishable from narrower siblings like get_service, list_services, or diagnose_project.

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?

"Read this before you deploy or diagnose" gives clear situational context that ties it to deploy/diagnose_project siblings. It stops short of naming those alternatives or stating when-not to use it (e.g. when you only need one service's logs), so it is strong but not fully explicit routing.

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

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

With no annotations, the description carries the full burden, yet it discloses nothing: not whether the call is read-only (only implied by 'get'), not what happens when the name is unknown, and not whether it errors or returns empty. Only the thinnest behavioral implication is present.

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

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

The single sentence has zero filler and is front-loaded, but it is underspecified rather than genuinely concise for a tool with no annotations and no output schema. Brevity here costs information rather than saving it.

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?

There are no annotations and no output schema, so the description should say what a 'service' record contains and how missing names are handled. Neither is covered, leaving an agent unable to predict the response shape or failure 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% and the parameter description already explains that name accepts a service name or job id and that both resolve to the same row. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

"Get one service" states a specific verb and resource, so the basic meaning is inferable. But it does nothing to distinguish itself from siblings like list_services, service_stats, or diagnose_service, and 'service' is ambiguous until the schema clarifies app/model/database.

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

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

There is no guidance on when to use this versus list_services or service_stats, and no mention of prerequisites or the name-vs-job-id resolution behavior that the schema documents. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full burden and does so: it discloses the upstream call (GET {base_url}/models using the referenced shared key), that the key never leaves the machine, the return shape {base_url_host, models}, that it is read-only despite an underlying POST, and the exact refusal codes (422/503/502) without leaking provider text.

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?

Purpose is front-loaded in the first line, followed by mechanism, return shape, safety note, and error codes in a tight order. Dense but every chunk carries information; the error-code block is the only part that could be trimmed.

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

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

No output schema exists, and the description supplies the exact return shape and field semantics, plus the failure modes an agent must handle. Nothing material needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both base_url and api_key_ref are already documented as an /v1 URL and a ${secrets.shared.KEY} reference. The description reinforces the secret-stays-local guarantee but adds little syntax or format detail beyond the schema, matching the baseline 3.

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

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

States a specific verb+resource with scope: 'List the model ids an OpenAI-compatible provider offers (submitter or admin).' That is clearly distinct from the local-model sibling list_models, and it names the downstream consumer (set_ai_route), though it never explicitly contrasts itself with list_models.

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

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

Provides clear usage context — call it to pick a model id before configuring set_ai_route — plus the caller role requirement (submitter or admin). It stops short of naming an explicit alternative or when-not condition.

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

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

With no annotations, the description carries the full load and does well: it discloses the return fields (provider, provider model, base_url, key reference) and an important security behavior — keys appear only as ${secrets.shared.KEY} references, never values. It does not mention whether the gateway must be configured or any permission requirements, which keeps it below 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?

Two short sentences, front-loaded with the core action and then the return-shape detail. The stray indentation and RST-style double backticks are cosmetic clutter but do not obscure meaning.

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 listing tool with no output schema, the description supplies what the agent needs: what is listed and what each entry contains. It is only slightly short on prerequisites (does the gateway need to be enabled/configured for this to return data?).

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

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

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

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

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

States a specific verb and resource: lists the AI gateway's aliases plus the gateway enabled flag. This is clearly distinct from set_ai_route/remove_ai_route (mutations) and from list_ai_provider_models (provider catalog), though it never names those siblings to reinforce the distinction.

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

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

Usage is only implied: an agent can infer this is the read-only inspection call for AI routes. There is no explicit 'use this when...' or reference to the alternative siblings (list_ai_provider_models, get_ai_usage, set_ai_route) that an agent would weigh before calling.

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

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

With no annotations, the description carries the full burden and discloses output fields, the 500-file bound, no paging, and write-time exclusion semantics. It does not state auth/permission requirements or explicitly confirm read-only/no side effects.

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

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

Three short sentences, front-loaded with what the tool returns and followed by the key constraints. No sentence repeats the name/title or wastes space.

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 one-parameter list tool with no output schema and no annotations, the description explains returned contents, the file bound, no paging, and the deploy relationship. It still omits an explicit read-only/auth note, though the schema covers the parameter and 404 case.

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 the schema already documents the name parameter, existing workspace, deploy-name relationship, and 404 behavior. The description adds only "app's workspace" context, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ("List an app's workspace") and enumerates returned fields (paths, sizes, sha256, totals). It references deploy_app to explain the relationship, but does not explicitly distinguish itself from read_app_file or write_app_files.

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 clear context that the listing mirrors deploy_app's build and that excludes are enforced at write time, so an agent can infer it is useful for inventory/preview. It does not explicitly name when to use it instead of read_app_file or list_app_templates, nor does it state 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?

No annotations are provided, so the description carries the behavioral burden. It discloses that this is a listing operation returning id/name/coordinates and what kind of templates are included, but it does not explicitly state read-only safety, pagination, ordering, or any filtering limits. For a simple zero-parameter list this is adequate but not rich.

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 short and front-loaded: it first states what is listed, then gives the deployment alternative, then clarifies the template scope. Every sentence adds useful selection or invocation context without waste.

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

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

Given a zero-parameter, no-annotation, no-output-schema list tool, the description supplies enough context to select and call it correctly. It identifies the resource, the returned fields, the intended follow-up tool, and the scope distinction; only minor operational details like ordering or pagination are absent.

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

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

The tool has zero parameters, so there is no parameter semantics to clarify. The description does not need to compensate for schema gaps, and the empty schema is unambiguous.

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

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

The description uses a specific verb and resource ('List the app template store') and clarifies exactly what the listed items are ('deployable starter apps (id/name/coordinates)'). It also explicitly distinguishes these from per-service presets and points to the sibling action tool, so an agent can identify this as the read-only catalog lister without opening another schema.

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

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

It clearly directs the agent to use `deploy_template` when it wants to deploy one of the templates, which is the key alternative action. It also gives scope guidance by clarifying that these are full app templates rather than per-service presets, though it does not enumerate other list tools for comparison.

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

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

With no annotations, the description carries the full burden and covers it: ordering (newest first), that archives are never opened (mtime only), that tars stay under the daemon's backups directory and are never served over HTTP, retention defaults (dump_keep_last=5, hourly pruning), the 500-row cap, the truncated flag, and the owner-or-admin plus token scope gate.

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

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

Front-loaded with the core action and return shape, then organized by use case and retention rules; the prose is dense with information rather than padded. Slightly long with markdown styling and some redundancy, but nearly every sentence adds a behavioral fact.

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?

There is no output schema, so the description supplying the row shape ({dump, size_bytes, created_at}), the meaning of created_at, and the truncated flag is essential and provided. Authorization requirements and retention behavior round it out; nothing an agent needs to call or interpret the result is missing.

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

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

Schema coverage is 100%, so the single parameter and its kind=database constraint are already documented. The description adds only marginal meaning ('each one holds every row of ``name``'), which is consistent with the schema but does not extend it substantially, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the dump tars this daemon holds for one managed database'), scoping it to a single database. It is clearly distinguishable from siblings like list_databases and dump_database by naming dump_database directly and contrasting the listing with the dump operation.

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

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

Explicitly names two situations: the recovery path after a dump_database call outran the client read budget ('list before you retry'), and retention checking. It also states what the listing contains under pruning and truncation, so when-not conditions are covered.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: cursor pagination, page bounding, the transient 'building' state with its 'db_ready' flag, and that the endpoint is password-free. It does not state read-only semantics outright or note whether the listing includes all projects, but what is present is substantive.

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?

Short and front-loaded: purpose and pagination scope come first, then return-shape details. The quoted/backticked formatting and multi-line splitting are slightly noisy but every sentence contributes 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?

There is no output schema, so the description correctly steps in to explain the notable return values ('building', 'db_ready', password-free 'endpoint') and the paging model. It stops short of enumerating other fields, but the essentials for correct invocation and interpretation are present.

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

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

Schema description coverage is 100%, and the schema already documents the 50 default and the 200 clamp in more detail than the description's 'bounded to limit per page'. The description adds the pagination framing but no parameter meaning beyond the schema, so the baseline applies.

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

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

States a specific verb and resource ('List managed databases') and narrows scope with 'kind=database workloads'. It also distinguishes itself from the mutation siblings by noting that 'lifecycle actions go through the service tools', so an agent can tell it apart from create_database and the service-management tools.

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

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

The closing sentence routes lifecycle operations elsewhere, which establishes this as the read path and implicitly excludes it from create/start/stop flows. It never names the specific sibling tool or states an explicit precondition, so routing is clear but not fully prescriptive.

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

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

With no annotations, the description carries the full burden. 'List' plus 'live utilization metrics' signals a read-only, real-time snapshot scoped to the local daemon, which is genuinely useful context, but it doesn't say whether results are cached, how metrics are sampled, or what an empty result means.

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

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

A single front-loaded sentence with no wasted words; the resource comes first and the payload detail follows.

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-argument read tool with no output schema, the description gives enough to call it confidently and hints at the return content. The only gap is that the specific utilization fields returned are not enumerated.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies.

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

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

States a specific verb ('List') and resource ('GPUs known to the daemon') plus the scope of the payload ('live utilization metrics'). It is distinguishable from siblings like cluster_stats or system_disk, though it never names those alternatives 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?

Usage is implied: an agent would call this when it needs a GPU inventory or current GPU load. There is no explicit when-to-use, no exclusion relative to cluster_stats/system_disk, and no note on what to do when no GPUs exist.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the owner/admin access restriction, the shared-app prerequisite, the exact return shape, and the condition under which url is null. It stops short of describing pagination, ordering, or error behavior, so a 3 would be too harsh but 4 captures the remaining gaps.

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

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

The description is front-loaded with the core purpose and access constraint, then provides return shape and important null semantics. Every sentence adds useful information with no filler.

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

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

Although there is no output schema, the description supplies the return structure in detail, including the fields of each hook and the null-url condition. Combined with the fully documented single parameter, this is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and the single parameter is fully documented in the schema with details about app kind restrictions and error behavior. The description only reinforces that the name refers to a deployed app, so the baseline of 3 is appropriate when the schema already handles parameter semantics.

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 verb and resource: "List a deployed app's inbound webhooks." It distinguishes itself from add_hook/remove_hook through the verb "List" and scopes the resource to inbound webhooks on a deployed app, so an agent can identify the correct operation without opening sibling schemas.

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

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

It gives clear usage context by stating "owner or admin only" and that answers come only once the app is shared. These are meaningful preconditions. It does not explicitly name add_hook or remove_hook as alternatives for creation or deletion, so it stops 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?

No annotations are present, so the description carries the full burden and does reasonably well: it discloses cursor pagination, the fact that newly served models appear as 'building' until the off-tick pull completes, and that lifecycle operations live elsewhere. It still says nothing about permissions, rate limits, or result ordering.

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

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

Front-loaded with the resource and scope, then pagination, then the lifecycle caveat. Slight redundancy with the schema on limit/cursor, but no filler sentences.

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 annotations, the description is the only source of truth, and it never says what a model record contains (name, id, status fields) or what ordering to expect. Pagination and the 'building' state are covered, but the return shape is left undefined.

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

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

Schema coverage is 100%, so both parameters are already fully documented, including clamping behavior and the default of 50. The description only restates 'bounded to limit per page' and 'pass cursor from the previous page', adding no format or edge-case detail beyond the schema. Baseline 3 applies.

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

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

Uses a specific verb+resource ('List served AI models') and narrows scope with '(kind=model workloads)', which separates it from cluster/host listings. It never names the closest-looking sibling, list_ai_provider_models or list_services, so the boundary is inferred rather than stated.

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?

'lifecycle actions go through the service tools' steers the agent away from using this tool for mutation and points at the service family. It gives no explicit condition for choosing between this and list_ai_provider_models or list_services, so a small inference remains.

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

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

No annotations exist, so the description carries the burden and does a good job: it discloses token-scope filtering, per-page bounding, cursor pagination, and the shape of each entry (services with state/endpoint, plus advertised addresses). It doesn't cover ordering or behavior at the page cap, but for a read-only list the disclosure is solid.

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

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

Front-loaded with the core action and scope in the first clause, then return shape and the alternative in two short follow-ons. No filler; the slight repetition of the per-page bound is negligible.

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, the description responsibly explains what each entry carries and how paging works, and the token-scope caveat prevents misinterpretation of sparse results. Only minor gaps remain, such as result ordering and what an exhausted cursor looks like.

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

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

Schema coverage is 100% and both parameters are already well documented there (default 50, clamped to 200; opaque cursor). The description only restates 'bounded to `limit` per page' and 'cursor-paginated,' adding no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List the projects this token can see') and adds a real scope constraint — a scoped token sees only the projects its scope names. It also distinguishes itself from the sibling detail tool by naming `get_project` for 'the full picture of one.'

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

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

Explicitly routes the agent to `get_project` when it needs a single project's full detail, and states the listing is cursor-paginated. It gives clear context but no exclusions (e.g., when to prefer `list_services` or how to filter), so it stops just short of full when/when-not guidance.

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

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

With no annotations, the description carries the behavioral burden and does provide useful non-obvious context: the inventory is DB-authoritative and annotated with live Caddy state, and models intentionally show route: null because they are loopback-only. It does not discuss permissions, freshness or pagination behavior, but for a list operation this is a strong disclosure.

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

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

The purpose is front-loaded in the first sentence, and the second sentence adds only non-obvious detail about route: null and live-table annotations. There is no filler or repetition.

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

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

The tool is simple, with two optional paging parameters fully documented in the schema, and the description explains the key output nuance around route: null. However, with no output schema, the description should do more to explain the returned row shape beyond saying each row carries a live-table annotation.

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 limit and cursor are already fully documented in the schema. The description adds no parameter-level information beyond what the schema provides, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: it lists the DB-authoritative route inventory annotated with live Caddy state. That is materially more informative than the tool name alone, and the note about models appearing with route: null adds concrete scope. It does not explicitly distinguish this tool from the sibling list_ai_routes, so it stops short of a 5.

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

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

Use is implied by the phrase 'DB-authoritative route inventory' and the live Caddy annotation, so an agent can infer this is the tool for inspecting route state. However, there is no explicit when-to-use guidance, no exclusion, and no naming of alternatives such as list_ai_routes.

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

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

With no annotations, the description carries full burden; it usefully discloses that values are never returned, which sets expectations for the response. It omits read-only confirmation, authentication requirements, and the fact that the 'shared' scope is readable by any authenticated principal (only stated in the schema).

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

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

A single front-loaded sentence with no waste; the security-relevant caveat is folded into the same sentence rather than padding it.

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 one-parameter read tool with a fully documented schema, the description supplies the essential behavioral note about returned values. Only auth/permission context is left implicit, which is a minor 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 coverage is 100% and the single 'service' parameter is documented in detail, including the special 'shared' value. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List a service's secret key names') and adds the crucial scope qualifier that only names, not values, come back. It implicitly contrasts with set_secret/remove_secret, though it never names them or the 'shared' scope.

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

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

The parenthetical implies this is the read-only inspection path for secrets, which is enough to infer when to call it. There is no explicit guidance on alternatives (e.g. use this before remove_secret, or that it covers the same 'shared' scope as the other secret tools).

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

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

No annotations are provided, so the description carries the full behavioral burden. It only discloses newest-first ordering; it does not clarify read-only/non-destructive behavior, pagination, permissions, or return shape, even though the schema covers paging parameters.

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

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

A single front-loaded sentence states the action, resource scope, and ordering with no filler. It is terse but structurally 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 simple 3-parameter list tool with full schema coverage, the description is adequate to know it lists all service types newest first. However, with no annotations and no output schema, it leaves gaps around return shape and when to choose it over list_models, list_databases, or get_service.

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 limit, cursor, and status are fully documented in the schema. The description adds no parameter detail, which is acceptable under the baseline-3 rule when the schema does the heavy lifting.

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

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

States the specific verb 'List' and resource 'services', parenthetically scopes services to apps, models, and databases, and specifies newest-first ordering. It does not explicitly differentiate from siblings such as list_models, list_databases, or get_service, so it falls short of full sibling routing.

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

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

The description gives no when-to-use, when-not-to-use, prerequisites, or named alternatives. With many sibling tools for listing models/databases and getting service detail, the agent must infer that this is the broad discovery tool.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that membership is resolved by the daemon, retired IDs never address same-name replacements, and existing grants/token roles apply. It does not cover return format, pagination behavior, or other operational details, leaving clear gaps.

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

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

The description is front-loaded with the core action and is only three sentences long. It avoids repetition and keeps the important project-ID guidance visible, though the final sentence about grants and token roles could be integrated more tightly.

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 seven-parameter log-reading tool with complete schema coverage but no annotations or output schema, the description covers purpose, project resolution, and auth context. It is largely sufficient for correct invocation, though it could say more about the returned log data or filtering behavior.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description reinforces the project ID preference but adds little semantic meaning beyond what the schema already states, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: "Read bounded logs of one service resolved within an explicit project." This is clear enough for an agent to understand the core operation. It does not explicitly distinguish itself from the sibling tool service_logs, so it falls short of a 5.

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

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

The description offers guidance to prefer the immutable project ID returned by list_projects and notes that node grants and local token roles still apply. However, it does not explicitly say when to use this tool versus alternatives such as service_logs, 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?

With no annotations, the description carries the full burden and does substantial work: it declares this an 'Authenticated read', names the upstream source (Caddy admin API), and characterizes the route table as tri-state. It does not mention failure modes (e.g., proxy down, auth failure) or whether the admin API call can be slow, which keeps it short of a 5.

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

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

One front-loaded summary sentence followed by one supporting sentence that adds the auth source and the sibling distinction. Nothing is padding; the parenthetical field list doubles as return-value documentation.

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?

No output schema exists, so the description must preview the return shape, and it does: TLS subjects plus CA fingerprint, apex registration, respawn backoff, and a tri-state route table. The term 'tri-state' is left unexplained and failure/empty-state behavior is not covered, but an agent has enough to call the tool correctly.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly avoids inventing inputs.

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

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

Specific verb ('Get') plus a well-scoped resource ('the embedded proxy's typed state') and an enumerated list of what that state covers. It explicitly distinguishes itself from the sibling list_routes by calling itself a complement to the DB-authoritative inventory, so an agent can choose between them without reading schemas.

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

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

The line 'Complements list_routes (the DB-authoritative inventory)' signals the intended division of labor: this tool for live Caddy-runtime state, list_routes for the stored inventory. There is no explicit 'use when / do not use when' phrasing, but the routing context is clear enough.

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

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

No annotations, so the description must carry the behavior burden. It discloses the return form ('as text') and the read-then-write rationale, but says nothing about binary/non-text files, error behavior, or permissions — the 404 semantics live only in the schema.

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

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

Two short sentences, front-loaded with the action and followed by the workflow rationale; nothing wasted. The rationale clause is slightly wordy but earns its place by explaining why to call this first.

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

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

For a two-param read tool with no output schema, the description explains what comes back ('as text'), which is the key missing piece. It leaves open handling of non-text files and failure modes, though the schema covers the 404 cases.

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

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

Schema description coverage is 100% and both parameters are thoroughly documented there (workspace name, 404 behavior, path format, 256 KiB cap). The description adds no parameter detail beyond what the schema already supplies, so baseline 3 applies.

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

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

States a specific verb and resource ('Read one file back from an app's workspace as text'), which cleanly distinguishes it from the listing sibling. It implies the contrast with write_app_files but never names list_app_files, which is the closest read sibling.

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 concrete trigger: read before patching a file you did not write in this conversation so write_app_files replaces content you have seen. No explicit when-not or alternative (e.g., 'use list_app_files to discover paths'), so it stops 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?

No annotations are provided, so the description carries the full burden and does: it declares the call asynchronous and names the follow-up (wait_for_service), explains that repo/ref/subdir/credentials are re-read off the service, that folder/zip-deployed services are refused, that dry_run makes zero writes, and that a real run returns summary/hints/next_step.

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

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

Front-loaded with the trigger condition and tightly written for the amount of behavior it covers. It is dense and slightly overstuffed with response-field detail, but no sentence is filler.

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

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

With no output schema and no annotations, the description supplies the async contract, the follow-up call, the dry-run semantics, the refusal case, and the shape of the response. That is enough for an agent to invoke it correctly on the first try.

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 still adds meaning beyond the schema: it explains why only a name is needed (coordinates are re-read), and that the dry-run diff shows env key names but never values, which the schema does not say.

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 pair (re-clone the recorded repo plus ref, then rebuild) against a named resource (an existing git-deployed service). It explicitly contrasts with the sibling deploy_git, so an agent can pick between them without opening either schema.

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

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

Leads with a 'Use when: a git app needs a new commit' condition, names the alternative ('use this instead of deploy_git when the service already exists'), and states an exclusion (services deployed from a folder/zip are refused). When-to-use, when-not-to-use and the alternative are all present.

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

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

With no annotations, the description carries the full burden and does well: it discloses the permission requirement, the specific 409 error code (`ai_gateway.alias_in_use`), that dependent apps are named, and the force escape hatch. It stops short of stating irreversibility or the success-side effect, but the conflict behavior is unusually well documented.

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?

It is short and front-loads the verb and resource, then layers the conflict/force behavior. The line-broken 409 clause is slightly awkward to parse but nothing is wasted.

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

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

For a mutation tool with no annotations and no output schema, the description covers permissions, failure conditions, and the force override adequately. It omits what a successful removal does to existing configuration or whether it is reversible, which would complete the picture, but the essentials are present.

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 value by explaining the 409 behavior tied to the force parameter, giving semantic context beyond the schema's field-level text. The alias and idempotency parameters are already fully documented in the schema.

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

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

The description states a specific verb (Remove) and resource (machine AI gateway alias), and the 'remove' prefix clearly distinguishes it from the sibling set_ai_route. The permission qualifier 'submitter or admin' adds useful scope that an agent could not infer from the name alone.

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

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

It gives clear operational context by explaining the 409 conflict condition and the force override, which tells the agent when removal will be refused and how to proceed. It does not explicitly contrast with alternatives like set_ai_route, keeping it shy 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?

With no annotations, the description must carry the full behavioral burden. It usefully discloses that the route disappears on the next reconcile tick and that the operation is idempotent, but it omits auth requirements, whether the domain binding is permanently destroyed, and any effects on certificates or DNS.

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

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

Two compact clauses, with the core action stated first and the timing/idempotency caveats appended. Every phrase earns its place.

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

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

For a mutation tool with no annotations, the description gives important timing and idempotency context, and the schema is fully described. However, it leaves gaps around authorization, permanence, and edge-case behavior that an agent might need before invoking it.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces domain removal but does not add syntax, format, or parameter-level meaning beyond what the schema provides.

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

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

States a specific verb and resource: 'Remove a custom domain'. It is clearly distinguishable from the sibling 'add_domain' and from service removal tools like 'remove_service'.

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

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

The description implies a deletion use case but does not explicitly state when to use this versus alternatives such as 'unshare_service' or 'remove_ai_route'. The schema carries most of the relevant conditions, including that removal is a no-op when nothing is bound.

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

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

No annotations are provided, so the description carries the burden and does well: it discloses idempotency, that the endpoint stops answering, that the signing secret survives, and the non-obvious redeploy resurrection with a fresh address. It omits auth/permission requirements and any indication of what the call returns, which keeps it below 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 core action and effect lead the description, with the two caveats following as short, self-contained notes. Every sentence conveys a distinct behavioral fact; nothing is redundant with the name or 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?

For a three-parameter mutation tool with no annotations and no output schema, the description covers the consequential behaviors (idempotency, secret persistence, redeploy recreation) that an agent would otherwise get wrong. The remaining gap is what a successful call returns or errors on, which is minor given full schema coverage.

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

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

Schema description coverage is 100%, so both required parameters and idempotency_key are fully documented in the schema itself. The description adds only indirect context ('a webhook still declared in nerdit.toml' hints at hook_name) and no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Remove an inbound webhook') plus the observable effect ('its address stops answering'), which distinguishes it from add_hook/list_hooks and from remove_secret. An agent can tell exactly what this tool does without opening the schema.

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

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

It explicitly routes the secret-removal case to remove_secret and warns that a webhook still declared in nerdit.toml will be recreated with a NEW address on the next deploy, which is precisely the condition an agent needs before calling. It stops short of stating 'use this when you want to stop receiving deliveries' or naming list_hooks for discovery, so it is clear context rather than full when/when-not coverage.

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

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

With no annotations, the description carries the full burden, and it does disclose one real behavioral trait: deleting a shared key can break every app referencing it via ${secrets.shared.KEY}. It omits reversibility, permission requirements for the shared scope (documented only in the schema's service param), and whether omitted-key deletion is atomic.

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 the destructive branch. 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?

This is a destructive mutation tool with no annotations and no output schema, so the description should carry more weight. It covers the main risk but leaves out permission requirements, irreversibility, and what a bulk delete returns — the schema fills some of this, but not all.

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 restates the key-omission semantics but adds no format or behavioral detail beyond what the schema already documents for key, service, and idempotency_key.

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

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

States a specific verb (delete) and resource (one secret key, or all secrets for a service), and the scope distinction (single key vs. whole service scope) is spelled out. It is clearly separable from siblings like set_secret and list_secret_names.

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 'key omitted' branch clarifies which calling mode produces which effect, which is implied usage guidance. However, it names no alternative tool (set_secret for replacement, list_secret_names for discovery) and gives no explicit when-not-to-use condition beyond a consequence warning.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it only says 'teardown + remove'. It omits irreversibility, dependency guards, 409 behaviors, admin-only cases, and purge semantics — all of which live in the schema, not the description. 'Teardown' hints at state destruction but is too vague for a destructive tool with zero annotation coverage.

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

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

A single short sentence, front-loaded with the verb and resource, with zero filler. It is exactly as long as the description needs to be, given the schema handles the details.

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

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

Given a destructive operation with no annotations and no output schema, the description is minimally complete: it tells the agent the operation removes a service, but not enough about risk, prerequisites, or the stop-vs-delete decision. The rich schema compensates for parameter-level gaps but not for top-level behavioral framing.

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

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

Schema description coverage is 100%, and the parameter docs are unusually rich (force dependency bypass, purge token semantics, idempotency replay). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a service') and adds a scoping note ('teardown + remove') indicating it does more than stop it. However, it does not distinguish itself from sibling stop_service, which is the closest alternative an agent would consider.

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

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

There is no when-to-use guidance, no exclusion criteria, and no mention of stop_service as an alternative for reversible shutdowns. The agent must infer that permanent removal versus stopping are different paths.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that no values are returned, secret values are never returned by any tool, access is owner/admin only, and out-of-scope names produce 403. It also explains the missing-key workflow, which is important agent behavior not captured by 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 return shape and scope, then moves directly into the deploy-time usage and missing-key workflow. Despite covering several behaviors, every sentence contributes to correct invocation and safe handling of secrets.

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?

There is no output schema and no annotations, so the description must explain return semantics, safety, and permissions; it does all three. An agent knows what the tool returns, when to call it, how to handle missing keys, and that secret values will never be exposed.

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 project and service are already documented in the schema, including the prj_ ID preference and web default. The description adds context about scopes and service launches but does not add parameter-level syntax or constraints beyond what the schema provides.

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

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

The description states a specific operation and result shape: resolving what a launch would see per key, including winning scope and whether it is plain, with "No values." It clearly contrasts with mutation tools like set_variable by emphasizing inspection only and never returning secret values.

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

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

It explicitly says to call this before a deploy to see which keys the service will receive, and it gives a precise recovery path when a key is missing: ask the human to run `nerdit vars set <project> --secret --prompt KEY`, then call again. It also states what not to do: do not invent values or request them in chat.

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

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

No annotations are provided, so the description carries the full burden and does: it declares admin scope and auditing, the 202 response with drain counts, and the critical caveat that over HTTP the call kills its own connection (so a dropped response means success, not failure). It also fully specifies retry behavior with an idempotency key (409 daemon.restart_in_progress or replayed 202, 'never a second restart mid-drain').

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

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

Front-loaded: the action and its purpose come first, then the return contract, then the failure/recovery caveat. Slightly noisy from leaked reStructuredText backticks (``capabilities``, ``uptime_s``) and multi-line wrapping, but no sentence is wasted.

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

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

There is no output schema, and the description compensates with the status code, the transport-specific failure mode, and the exact recovery/verification procedure. For a daemon-killing mutation with no annotations, this is everything an agent needs to call it and interpret an ambiguous result.

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 value by framing why drain_timeout_s and idempotency_key matter in the failure scenario the agent will actually hit (a dropped response, then a safe retry). It reinforces rather than duplicates the schema's own parameter prose.

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

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

Specific verb+resource ('Restart the daemon') plus the condition that motivates it ('to apply restart-required config') and its scoping ('admin-scoped, audited'). The phrase 'the daemon' distinguishes it from the sibling restart_service without needing to name it, so an agent can select correctly.

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 states when to use it (config marked restart-required) and states the admin scope prerequisite, plus it names capabilities as the post-hoc verification path. It does not explicitly exclude or compare against restart_service for the case where only a single service changed, which is the main remaining inference.

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

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

With no annotations, the description carries the full burden, and it discloses one genuinely non-obvious mutation effect: backoff state is reset. It omits downtime/disruption, whether the call blocks, and what happens if the service does not exist, which are exactly the traits an agent needs for a mutating 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?

A single short sentence with the resource up front and the notable behavior in parentheses; no waste. It is arguably too terse rather than padded, so it loses a point for thinness rather than verbosity.

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 mutating, annotation-free tool with no output schema, the description never says what the call returns (immediate ack vs. blocking until healthy) or how failures surface. That is a meaningful gap an agent must guess at before invoking.

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 the schema itself explains that name accepts a service name or job id and that idempotency_key replays a prior result, so the description adds nothing but does not need to. Baseline 3 applies.

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

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

"Restart a service" is a specific verb+resource, and the parenthetical "clears backoff" disambiguates it from stop_service and redeploy_service in the sibling list. It stops short of naming an alternative outright, so it does not fully earn a 5.

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

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

The phrase "clears backoff" implies the usage context (a service stuck in crash backoff), but the description never says when to prefer this over redeploy_service, stop_service, or wait_for_service, and gives no exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden and does so: blocking semantics, the exact return envelope, the rule that a non-zero exit is a 200 not an error, the one-run-at-a-time 409, and the fact that volumes/env/secrets are shared with the live container. The idempotency deep-dive (replay yields `idempotent_replay` with no `exit_code`; failure un-pins the key; 503 `run.interrupted` may mean partial application; 24h key claim on daemon death) discloses exactly the risky, non-obvious behavior an agent would otherwise get wrong.

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

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

Front-loaded with purpose, then behavior, then retry semantics — a sensible order for a blocking mutation. It is long but nearly all of it is load-bearing; the main waste is the idempotency paragraph restating what the `idempotency_key` schema description already says.

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?

No output schema and no annotations, yet the description supplies the return envelope, error codes, timeout behavior, concurrency limit, and credential-masking implications. For a destructive-capable, minutes-blocking operation that is everything an agent needs to call it safely.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by front-loading the operational consequence of `idempotency_key` and `timeout_s` (non-zero exit vs. timed_out, 422 rather than silent truncation). It does duplicate the schema's own idempotency wording, so the added value is emphasis and retry procedure rather than new meaning.

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

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

The opening sentence names a specific verb and resource ('Run a one-off command in a deployed service's image') and immediately disambiguates with concrete use cases (migrations, seeds). The throwaway-container clause sharpens the scope further, distinguishing it from a restart/redeploy and from the live service's own process.

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 strong when-to-use context (migrations, seeds), an explicit exclusion (models and databases are refused with 422 run.not_supported), and points to `diagnose_service`'s `last_run` when you only need prior output. What it omits is any comparison to siblings that could otherwise do the job, notably `add_hook` for migrations that should run on every deploy rather than once — with ~70 siblings that is a real 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?

No annotations are supplied, so the description carries the full behavioral burden and does not meet it. It omits that names are register-only (409 on collision), that the image must already exist on the daemon, whether the container is started immediately, permission requirements, and idempotency behavior — facts that exist only in the schema property descriptions, not the tool description.

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

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

A single sentence with no filler, so nothing is wasted — but for an 11-parameter mutation tool it is under-specified rather than concise. Brevity here costs the agent needed routing and 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?

With no annotations, no output schema, and 11 parameters, the definition should explain what a successful call yields (a service record, an endpoint, a status) and how it relates to list_services/get_service/wait_for_service. Only the input schema compensates, leaving the post-call workflow undocumented.

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

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

Schema description coverage is 100% and the per-parameter text is unusually rich (name regex, script_path admin-token requirement, command argv semantics, health-check shapes). The description adds nothing beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'register a service', qualified by 'from a prebuilt image', which signals it will not build or pull. It is clear on its own, but it never names or distinguishes itself from the many near-neighbours (deploy, deploy_template, deploy_app, serve_model, redeploy_service), so the agent must infer the difference.

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

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

There is no when-to-use guidance, no exclusions, and no named alternative. An agent facing 60+ siblings that all create or deploy services gets no rule for choosing 'serve' over 'deploy' or 'deploy_template'.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses asynchronous immediate-return semantics, the 'building' intermediate state, background image/weight pulling, and where lifecycle actions live. It also explains how apps bind to the endpoint and what env vars result.

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

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

Front-loaded with the core purpose, then async behavior, then app binding. Efficient overall, though the [ai.<name>] binding paragraph is somewhat tangential to invoking the tool and could be trimmed.

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

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

For a 7-param mutation tool with no annotations and no output schema, the description covers the async lifecycle, polling target, and error behavior well enough to call correctly. It does not describe the shape of the returned 'model row', though the schema and error codes compensate.

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

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

Schema description coverage is 100%, so every parameter (gpus, backend, max_model_len, idempotency_key, etc.) is already documented with constraints and error codes. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Serve a local AI model as an OpenAI-compatible endpoint.' It is distinguishable from siblings like list_models and get_service, and it explicitly routes lifecycle operations to stop_service/restart_service/remove_service.

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

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

Gives clear operational context: serving is asynchronous, poll list_models or get_service until running, and use the existing service tools for lifecycle. It does not, however, distinguish this tool from the sibling 'serve' tool, leaving one alternative unaddressed.

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

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

With no annotations, the description carries the behavioral burden and does well: it explains server-side filtering, literal substring grep, source stream mixing, and the runtime/build ambiguity for older daemon lines. It does not discuss permissions or response shape, which are minor gaps for a read-only log retrieval 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 front-loaded with the use condition and then explains the filters in a logical order. It is somewhat long and repeats some schema details, but most of the text earns its place by clarifying tricky log semantics.

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?

It thoroughly covers input semantics and filtering behavior for a 6-parameter tool. However, with no output schema, it does not explain the return format or whether lines are plain strings versus objects with timestamps or ids, leaving the agent to infer response structure.

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 interpretation beyond the schema, especially for source='runtime' and the interaction between grep, source, and tail, though it does not mention the since_id behavior documented in the schema.

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

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

The description clearly establishes that this tool retrieves raw service or build output, with source-specific filtering. It does not explicitly differentiate itself from sibling tools such as project_logs or diagnose_service, leaving that routing to the agent.

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

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

It gives a clear when-to-use condition: when the raw output a service or build printed is needed. It also advises using bounded grep/tail queries instead of pulling large tails, but it does not name alternative tools or state when not to use this one.

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

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

With no annotations, the description carries the full burden and does so: it discloses the availability contract, null-vs-zero semantics, the docker cpu_pct convention where 100.0 is one core, and the daemon cache TTL. These are non-obvious traits an agent cannot infer from the schema.

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

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

Front-loaded with the purpose, then the return shape, then the critical branching rule, then routing guidance. Every sentence adds decision-relevant information, including the counterintuitive null-masquerade warning; 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?

No output schema exists, so the description supplies the response shape explicitly and warns how to interpret it. For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents that 'name' accepts a service name or job id. The description adds nothing about the parameter, which is acceptable given the baseline for fully-covered single-parameter schemas.

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

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

States a specific verb ('Get live CPU, memory, network and PID usage') and a precise resource scope ('for a running service'). It also explicitly separates itself from the sibling diagnose_service by framing this tool as answering 'how much' rather than 'why'.

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

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

Gives an explicit routing rule: 'For why a service is unhealthy use diagnose_service; this tool answers how much a healthy one is consuming.' It also tells the agent that loop-polling is acceptable due to the 2-second cache, which is actionable when-to-use guidance.

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