tugport

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

Because no annotations are provided, the description must carry the full burden of behavioral disclosure, but it does not. It never says whether duplicate host entries fail or overwrite, whether a certificate is issued only after DNS is verified, whether the routing change is applied immediately or requires a redeploy, or whether the change is reversible; the phrase 'automatic HTTPS' only hints at certificate provisioning.

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

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

The description is a single, front-loaded sentence with no padding, which is ideal short-form structure. It is terse to the point of omitting behavior, but it contains no wasted content.

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 tool is nontrivial because it involves 6 parameters, 3 of which are required, and TLS and routing side effects, and it has no annotations and no output schema. One sentence cannot cover the failure modes an agent must anticipate, so the definition is materially under-specified for its complexity.

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 67%, and the schema leaves https and via_tunnel undocumented. The description adds no parameter meaning at all: it never mentions the host, path prefix, port mapping, or what via_tunnel changes about the setup. For a 6-parameter mutation tool, this is a real gap.

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 concrete action on a concrete resource: it routes a service to a domain and provisions HTTPS automatically. That distinguishes it from the sibling remove_domain, which is the clear inverse. The verb 'serve' is slightly indirect compared with 'add', but the intent is still easy to grasp.

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

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

There is no guidance on when to call this tool: no prerequisites, such as a deployed service or a DNS record that points at the server, and no mention of when not to call it. An agent must infer that the action is a write operation and that later removal is done through a separate tool with a sibling 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. It does disclose a genuinely important side effect — MongoDB and MariaDB primaries restart once on the first add — which is real added value. However, it says nothing about permissions, whether the operation is asynchronous, idempotency, or failure modes.

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 that front-loads the action, then the placement detail, then the risk caveat. No filler, though the parenthetical placement syntax is slightly compressed relative to its importance.

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

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

For a 2-param mutation tool with no annotations and no output schema, the description covers purpose, placement shape, and the most surprising operational consequence. Remaining gaps (async behavior, permissions) are secondary but real.

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?

At 50% schema coverage the description must compensate, and it partially does: it enumerates the placement keys {node, region, labels}, which the schema leaves as an untyped empty object. But it does not explain the semantics of each key (mutually exclusive? precedence? format of labels).

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 ('Add a read replica to a database') with the placement dimension named inline. It distinguishes itself naturally from list_replicas and promote_replica, though it never explicitly contrasts with them.

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 tool name and the 'on a given server or region' phrasing, but there is no explicit when-to-use/when-not guidance or reference to alternatives like promote_replica or list_replicas for verification.

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 full behavioral burden, yet it only discloses the sort order ('newest first'). It says nothing about read-only safety, default record count, whether results are paginated, or scope across projects/services, all of which matter for an audit 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 single fragment is front-loaded and free of waste, but it is under-specified rather than concise: there is room for one clarifying clause about scope or filters without bloat.

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

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

With no annotations, no output schema, and four optional filters, the description should explain default behavior and filter combination, but it does not. An agent cannot tell how many records come back or whether omitting all filters returns the full audit trail.

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 75%, with limit undocumented, and the description adds no parameter meaning at all — not even that limit caps the number of returned entries or that actor/project/service act as filters. The one gap in the schema is left entirely unfilled.

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 phrase 'Who did what, newest first' conveys the resource (audit entries of actor/action) and the sort order, but it has no explicit verb such as 'list' and does not differentiate this from nearby tools like get_logs. An agent can infer the purpose from the name plus this fragment, but the definition itself only vaguely pins it down.

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

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

There is no statement of when to use this tool, when to prefer get_logs or metrics, or what preconditions apply. The agent must guess from the name alone.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool returns status, live progress, and a log, which strongly implies a read-only inspection operation. However, it does not explicitly state that it has no side effects, whether it requires permissions, or what the log/progress response shape 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?

The definition is a single compact sentence with no wasted words, and the key return aspects are front-loaded. Its fragment-like phrasing ('A backup or restore run: ...') is efficient but slightly less direct than a clear verb-led sentence.

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

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

For a simple one-parameter getter, the description covers the main return concepts: status, progress, and log. However, with no output schema and no annotations, it should do more to disambiguate this tool from run_backup and to clarify that it retrieves an existing run rather than starting one.

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 run_id parameter is already documented as coming from list_backups (last_run.id). The description adds no further parameter meaning, so baseline 3 applies 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 clearly identifies the resource as 'a backup or restore run' and names the aspects it exposes: status, progress, and log. It lacks an explicit verb like 'get' or 'retrieve', which leaves slight ambiguity against the action-oriented sibling 'run_backup', but the intended read operation is still inferable.

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 explicit when-to-use guidance, no exclusions, and does not name alternatives such as run_backup or list_backups. The only usage signal comes indirectly from the required run_id schema parameter, which is not part of the description itself.

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 disclosure burden, and it only adds the fact that queued deploys are also cancellable. It says nothing about whether cancellation is graceful, whether it is irreversible, what happens to a partially rolled-out deployment, or what authorization is required. For a mutation tool with zero annotation coverage this is a substantial gap.

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

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

A single front-loaded sentence with no filler; the qualifier about deploy state is placed immediately after the action so nothing is buried.

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 tool with no output schema, the description is minimally sufficient to identify the action. It leaves out the outcome of cancellation and any post-cancel state, which an agent would want before invoking a mutation with no annotations to fall back 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 description coverage is 100% for the single 'deploy_id' parameter, so the schema already does the work. The description adds no format, sourcing, or lookup guidance beyond what the schema states, which makes the baseline 3 correct.

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

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

A specific verb ('Cancel') and resource ('deploy') with an added state scope ('running or queued') that tells an agent exactly which deploys qualify. It does not explicitly distinguish itself from nearby siblings like 'rollback' or 'stop', 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?

'Running or queued' implies the precondition for calling it, so an agent can infer it applies to in-flight or pending deploys rather than completed ones. However, it never names alternatives such as rollback (for reverting a finished deploy) or stop (for halting a service), leaving the routing decision to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not whether the name must be unique, what happens on a duplicate name, whether the caller needs account-level permissions, what side effects occur, or what the call returns (there is no output schema either). For a resource-creating mutation this is a serious gap.

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

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

Two words, front-loaded, zero waste — but the brevity here reflects under-specification rather than disciplined editing. There is nothing to trim, yet nothing is earning its place because almost nothing is said.

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 a terse two-word description, an agent has no picture of what creating a project does in this environment or how it relates to the services/deploys that dominate the sibling list. The tool is structurally simple (one required string), which keeps this from being a 1, but the definition is not complete enough to call confidently.

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% — both parameters carry their own descriptions, including the 'Lowercase DNS-safe name' constraint — so the schema does the work. The description adds nothing beyond it, which is the baseline expectation when coverage is complete.

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 is essentially a restatement of the tool name: 'Create a project.' It does convey verb (create) and resource (project), but adds no scope, no distinction from siblings like create_service or list_projects, and no sense of what a 'project' means in this platform.

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?

No guidance on when to create a project versus creating a service directly, no prerequisites, and no mention of the sibling tools (list_projects, get_project, create_service) that an agent would need to consider first. Usage is inferable only from the tool 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?

No annotations are provided, so the description bears the full burden. It never states whether creation triggers a deploy, requires specific permissions, is idempotent, or what happens on conflict — all important for a mutation 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?

Two tight sentences, front-loaded with the action, then the kind and per-kind payload guidance. Little waste, though the compressed brace-notation is dense to parse.

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

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

For a 6-param tool with nested objects and no output schema, the description covers the two most complex parameters (spec.source, database) well. Gaps remain around the compose kind and creation side effects, but the core call path is clear.

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%, but the schema only says 'Service spec (see docs/API.md)', so the description adds real value by spelling out the spec.source union shapes ({type: git...}, image, dockerfile) and the database engine enum. This meaningfully compensates beyond the schema's pointer to external docs.

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

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

The description opens with a specific verb+resource ('Create a service in a project') and clarifies the kind dimension. It doesn't explicitly contrast with update_service/delete_service, but the create verb and kind detail make intent unambiguous.

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

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

It gives conditional routing ('for apps pass spec.source...; for databases pass database...'), which helps select the right parameter path. However, there's no explicit when-to-use-this-vs-alternatives or when-not guidance against siblings like update_service or create_project.

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 disclosure burden; it does name a permission requirement and warns that volumes=true destroys data. However, it never says the service deletion itself is irreversible, nor what happens to dependents such as deploys, domains, or env vars.

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

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

Two sentences, zero filler, with the destructive capability surfaced before any secondary detail. Every clause adds information an agent would otherwise have to guess.

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, two-param tool with no annotations and no output schema, the essentials (permission, data deletion) are covered, but side effects on related resources and confirmation of permanence are absent. That is a meaningful gap for an irrecoverable operation.

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 only 50%: the `volumes` param has no schema description, and the description compensates by explaining that volumes=true deletes the service's data — the key semantic an agent needs. The `service` identifier format is handled in the schema, so nothing is left ambiguous.

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 ('Delete a service') with the destructive scope stated up front. It is plainly distinguishable from the lifecycle siblings (stop, restart, update_service) because it removes the resource rather than altering its state.

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

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

The prerequisite '(needs the destroy grant)' is a useful call condition, but the description never contrasts this with stop or restart, which are the obvious alternatives an agent will be choosing between. The agent must infer that delete is the terminal option.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the blocking-by-default behavior and what is returned ('the deploy and the end of its log'), but says nothing about permissions, what happens to a running service during deploy, failure behavior, or the effect of no_cache/ref.

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 then the wait behavior; nothing is wasted, though the return-value sentence could be folded in 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 deployment mutation with no annotations and no output schema, the description covers the essentials of invocation and return shape but omits failure modes, blocking duration expectations, and cache/ref implications that an agent would need to call it confidently.

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 75%, covering service, ref, and no_cache; the description adds the missing semantics for wait, explaining that it controls blocking versus immediate return, which the bare default in the schema does not convey.

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

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

States a specific verb and resource ('Deploy a service') plus the key scope modifier (waits for result by default). It is distinguishable from list_deploys/get_deploy, though it never contrasts itself with the closely related restart or rollback siblings.

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

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

The parenthetical '(set wait=false to return immediately)' gives one concrete usage condition, but there is no guidance on when to use deploy versus restart, rollback, or promote_replica, and no prerequisites are stated.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions only that the command runs 'with its env' and returns output, but says nothing about security implications, required permissions, side effects, whether the command runs as root, how failures or timeouts behave, or whether it blocks. For an arbitrary shell-execution tool, these omissions are significant.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys purpose, execution context, and return behavior efficiently.

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 high-risk arbitrary-command-execution tool with no annotations and no output schema, the description is incomplete. It does not explain timeout behavior, what happens if the service is not running, permission requirements, or whether the command is run interactively or non-interactively. These gaps leave an agent without enough context to invoke the tool safely and 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 67%: 'command' and 'service' are documented in the schema, while 'timeout_s' has only a default value. The description reinforces the meaning of 'service' and 'command' but adds nothing for 'timeout_s' or richer argument syntax. A baseline 3 is appropriate given the moderate schema coverage.

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

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

The description uses a specific verb ('Run') and resource ('a shell command') and scopes it precisely to 'inside a service's running container (with its env)', including the return behavior. This clearly distinguishes it from siblings like restart, get_logs, 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?

There is no explicit guidance on when to use this tool versus alternatives such as get_logs or restart. The description states what it does but does not mention prerequisites (e.g., service must be running), exclusions, or the conditions under which an agent should choose exec over other diagnostic or management 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. It implies a read via 'get' and suggests the log is not truncated ('full log'), but it says nothing about permissions, behavior for an unknown deploy_id, or whether the log is inline vs. paginated.

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 very short and front-loaded, which is good, but a single unpunctuated fragment provides no structure or informative lead. There is no wasted text, yet the minimalism comes at the cost of specification rather than efficiency.

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

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

For a simple one-parameter lookup with no output schema, the description minimally covers what it returns ('with its full log'). It remains thin on error behavior and log size/format, gaps that matter since no annotations or output schema exist to fill them.

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% for the single deploy_id parameter, so the baseline is 3. The description adds no syntax, format, or example meaning for the id beyond what the schema already states.

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 fragment 'A deploy with its full log' implies fetching a single deploy along with its log output, which is enough to distinguish it from list_deploys and get_logs at a rough level. However, it is a noun phrase rather than a verb+resource statement, so the agent must infer the operation (retrieve) rather than read it 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?

There is no guidance on when to use this instead of siblings such as get_logs, list_deploys, or get_service. The 'full log' mention hints at log retrieval but never states the condition that selects this tool over get_logs.

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 behavioral burden. It discloses matching semantics for q and the timestamp units for since/until, which is genuinely useful, but says nothing about result ordering, the default limit of 200, truncation behavior, or whether the call is read-only and cheap.

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 front-loaded sentences with no filler; the most decision-relevant detail (what is searched) comes first. It is slightly too terse for a six-parameter tool, 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 six-parameter tool with no annotations and no output schema, the description omits result shape, ordering, pagination/limit semantics, and what replica scoping means. An agent could call it, but could not predict what it gets back or how to narrow large result sets.

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 only 50%, but the description compensates for the two weakest fields by defining q as a case-insensitive substring and giving epoch-millisecond units for since/until. It still leaves limit and replica undefined in both places, so it does not fully close the gap.

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 (search a service's logs), which is enough to separate it from siblings like audit_log or metrics. It does not explicitly name a contrasting sibling, so it stops short of 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?

No guidance on when to use this versus audit_log or metrics, and no prerequisites or exclusions. The agent is left to infer usage purely from the verb.

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 little: 'live status' hints that the call hits runtime state rather than a cache, which is useful. It says nothing about permissions, whether an unknown project errors, latency/cost of a live query, or whether variable values (versus only names) are exposed.

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?

There is zero waste, but the single sentence fragment is under-specified rather than efficiently concise. It is front-loaded only in the sense that there is nothing else to front-load.

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 and no output schema, the description does list what comes back, which is the main thing missing from structured data. It still leaves gaps on error behavior and on whether env values or only names are returned, so it is adequate but not complete.

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

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

Schema coverage is 100% and the single 'project' parameter is documented as 'Project id or name'. The description adds no further meaning — no note on name-vs-id resolution behavior or ambiguity handling — 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?

The fragment names the resource ('a project') and the two things returned (services with live status, shared variable names), which is enough to distinguish it from list_projects or get_service. But it is a noun phrase with no verb, so the agent must infer that it retrieves rather than renders or summarizes. Purpose is inferable, 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?

There is no when-to-use guidance and no mention of alternatives, despite a crowded sibling set containing list_projects, get_service, list_services and list_env. An agent cannot tell from the description whether this is the right call for a single service lookup or whether list_env would give the variables more cheaply.

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, yet it says nothing about read-only safety, required permissions, or behavior when the service id is unknown. The listed fields weakly imply a read operation, but that is inference, not 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?

One compact fragment with no filler, and the most useful information (what comes back) is up front. It loses a point for being a fragment with no verb, which reads more like a field list than a definition.

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 read with no output schema, enumerating the returned fields is genuinely useful compensation. However, with zero annotations it still omits permission requirements and failure behavior, so it is adequate rather than complete.

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

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

There is a single required parameter with 100% schema description coverage including the `project.service` format example, so the schema does the work. The description adds no parameter meaning beyond what is already structured, which is the baseline case for full 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 is a noun fragment listing the payload ('spec, live status, replicas, domains, env var names and last deploy') rather than a verb+resource statement, so the retrieval action is only implied. It does implicitly distinguish itself from list_services and get_project by scoping to a single service's internals, but the agent has to infer that.

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 get_project, list_services, or list_deploys, and no prerequisites or exclusions. The agent must infer usage purely from the field list.

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: it implies a read of backup jobs and hints that each job comes with its last run, but says nothing about permissions, ordering, volume of results, or error behavior. The second sentence adds domain vocabulary about volume jobs but no operational behavior.

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

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

It is short and front-loads the resource, which is good. However, the second sentence is a dangling clarification that references 'the service' without ever establishing context, so part of the limited space is spent on an ambiguous aside.

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 should explain what a call returns, yet it only vaguely mentions 'last run' without field names or shape. For a zero-parameter list tool with no annotations, the agent is left without enough to predict the response or confirm read-only safety.

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

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

The tool takes zero parameters, so the schema-side baseline is 4. The description instead spends its words on interpreting a returned field (volume being a named volume or a server path), which is useful but does not substitute for parameter documentation since none exists.

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 noun phrase "Backup jobs with their last run" identifies the resource and a bit of content, but there is no verb and no differentiation from siblings run_backup and backup_run. An agent can guess this is a read/list of backup jobs, but the description never says 'list' 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?

There is no indication of when to call this versus run_backup (which presumably triggers a backup) or backup_run (which presumably fetches a single run). No prerequisites, no contexts, no exclusions are given.

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. 'Recent' is the only behavioral signal — it does not say how many deploys are returned, their ordering, whether history is truncated, or what permissions are needed, and it mentions no return shape.

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 compact sentence, front-loaded and free of waste. It is arguably under-specified rather than verbose, but structurally it is clean.

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

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

For a read tool with no annotations and no output schema, the description should explain what a deploy entry looks like and how much history is returned. It leaves both unaddressed, so an agent cannot predict the response or the scope of 'recent'.

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 `service` parameter is documented in-depth in the schema (including the `project.service` id format). The description adds nothing beyond it, 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?

The phrase 'Recent deploys of a service' identifies the resource and scoping (recency, single service), but it is a noun phrase with no explicit verb and no differentiation from close siblings like get_deploy, deploy, or cancel_deploy. An agent must infer that this is the list operation rather than a single-deploy fetch.

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

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

There is no statement of when to use this versus get_deploy (single deploy), deploy (create), or audit_log. The word 'Recent' hints that it is a browsing/listing call, but no exclusion or selection rule is given.

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 it does disclose a real behavioral trait: values are returned only with the secrets:read scope. However, it does not say what happens without that scope (names only vs error), nor anything about ordering, volume, or masking.

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 short sentence with the key access constraint parenthetically front-loaded; nothing wasted. It reads as a fragment rather than a complete sentence, which costs a little clarity but no 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?

There is no output schema, so the description should say the return is a set of key names (and when values appear); it only implies this. For a simple single-param read it is near-adequate but leaves the response shape and the no-scope behavior ambiguous.

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 single `service` parameter with an id/project.service example, so the description adds nothing parameter-specific. Baseline 3 applies when the schema does the work.

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

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

The fragment identifies the resource (env var names for a service) but never uses a verb and omits the tool's name/title entirely, so the agent must infer 'list'. It contrasts implicitly with set_env by saying 'names', which helps distinguish read from write.

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?

No guidance on when to use this versus setters or other service-inspection siblings; usage is only inferable from the word 'names'. The conditional access note hints at a permission gate but not at 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 behavioral burden. It discloses visibility scoping and that each project includes the caller's role, but says nothing about permissions, pagination, ordering, or whether all projects are returned at once.

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 filler. The scope and role-inclusion details are both useful and earn their place.

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

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

For a zero-parameter listing tool with no output schema and no annotations, the description covers the core call semantics but leaves gaps around result shape and whether listing is paginated or complete. It is minimally sufficient but not fully self-contained.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to add meaning to, and the description does not misleadingly imply otherwise.

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

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

The description states a specific verb ('List') and resource ('projects') and adds a scope qualifier ('you can see') plus result detail ('with your role in each'). It is clearly distinguishable from get_project and create_project by name and operation, though it does not explicitly name those siblings.

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

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

The scope 'projects you can see' lightly implies when to use it for discovery, but there is no explicit guidance on when to choose this over get_project, list_services, or other listing tools. Usage is inferable but not directed.

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 disclosure burden, and it discloses almost nothing: it doesn't confirm the operation is read-only, doesn't say whether output is paginated or ordered, and doesn't mention permissions or what happens for a service with no replicas. Only the implicit 'replicas are read-only followers' notion is conveyed.

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

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

It is a single short sentence with no filler, which is good, but the brevity comes at the cost of under-specification rather than efficiency — key facts (verb, return contents, scope) are absent. Short, but not front-loaded with actionable 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?

This is a simple one-parameter read tool, so requirements are modest, but with no annotations and no output schema the description should explain what is returned (replica identities and their follow/health status) and any ordering or limits. It leaves the agent without enough to know what the call yields.

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

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

There is a single required parameter and schema description coverage is 100%, with an example format ('shop.api') already in the schema. The description adds no meaning about the service identifier beyond what the schema states, so the baseline of 3 applies.

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

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

The description identifies the resource ('read replicas') and adds that replication/follow status is included, which the name alone doesn't convey. However, it is a noun phrase with no verb, so it reads as a caption rather than a statement of what the tool does (list vs. inspect). An agent can infer listing from the name, but the description itself never says 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?

No guidance on when to call this versus sibling tools such as add_replica, promote_replica, get_service, or list_services. There are no stated prerequisites (e.g. that a service id is needed) and no exclusions, leaving the agent to infer all routing from the name alone.

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

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

With no annotations, the description carries the full burden. It discloses the returned fields (status, versions, size) and the special 'local' id, which is genuinely useful, but says nothing about read-only safety, permissions, pagination, or whether any of the listed data is sensitive.

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 a single short sentence, so nothing is padded, but the fragmentary phrasing with a mid-sentence parenthetical ('the panel's own is id local') reads awkwardly and buries the key identification detail rather than front-loading 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 zero-parameter, no-output-schema listing tool the description gives an adequate sketch of what comes back (status, versions, size) plus the 'local' id convention. It still omits what a 'server' means in this setup relative to services/projects and whether results are paginated or ordered.

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 nonetheless adds value by noting the special 'local' id for the panel's own server, which clarifies how to interpret that entry in the results.

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 noun phrase 'The servers in this setup' identifies the resource and the trailing clause names the returned attributes (status, versions, size), so the purpose is inferable as a listing tool. However, no verb is stated and nothing distinguishes it from close siblings like list_services or server_status, leaving the agent to guess which listing it needs.

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 tool versus server_status, list_services, or list_projects. The only routing hint is the parenthetical that the panel's own server is id 'local', which is context rather than usage 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 burden. It usefully discloses the permission-scoped visibility model ('you can see') and that state is included in each entry. It does not state that this is a non-mutating read, nor anything about ordering, pagination, or result size for an unbounded cross-project listing.

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 zero filler, scoping ('across projects') and content ('with its state') front-loaded. 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?

No output schema, no annotations, and no parameters, so the description must fully define behavior. It covers scope and payload shape at a high level but omits result ordering and whether the list is truncated or paginated for large cross-project tenants, which matters for an unbounded list 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 baseline is 4. The description correctly implies there is nothing to filter by; an agent need not hunt for options that do not 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?

States a specific verb (implicitly list) and resource (services) plus an important scope qualifier: 'across projects', which separates it from a project-scoped listing. 'with its state' adds what each entry contains. It does not explicitly distinguish itself from get_service or list_env, but the plural + cross-project scope makes the intent readable.

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?

No indication of when to use this instead of get_service (single service) or list_projects (project view). 'Every service you can see' implies no parameters are needed, but there is no explicit routing guidance or stated ordering/pagination expectations.

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 alone. It does disclose a meaningful behavioral trait — that service scope is 'added up over every server' — but omits permissions, whether the call is read-only, pagination/downsampling behavior, and the default range.

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 tight sentences, zero filler, and the scope semantics are front-loaded before the range enumeration. Every clause carries 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?

No output schema exists, but 'time series' adequately signals the return shape and the valid range values are stated. Minor gaps remain: the default range ('1h' lives only in the schema) and whether node is required for service scope are not clarified.

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 documents all four parameters and the baseline is 3. The description adds real meaning beyond it by defining what a service-scope series actually is (aggregated across servers), which the schema's 'service:<id>' text does not convey.

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

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

The description states a specific resource and return shape ('Time series') and enumerates the three scope variants (host, gpu:0, service:<id>), which lets an agent distinguish it from get_logs or server_status. It does not name a sibling tool explicitly, 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?

Usage is only implied through the scope enumeration — an agent can infer that host scope queries a server and service scope queries a service, but there is no explicit 'use this when' guidance, no exclusions, and no mention of when to prefer get_logs or server_status instead.

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

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

With no annotations, the description carries the burden and does disclose two important traits: admin privileges are required, and the old primary's URL variable is repointed as a side effect. It does not say whether the operation is reversible, whether the old primary is demoted, or whether it causes downtime.

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

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

Two short sentences with zero waste; the action and precondition are front-loaded and the side effect follows logically.

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 mutation with no annotations and no output schema, the description covers the action, the trigger condition, the privilege requirement, and the resulting state change. It stops short of describing failure modes or reversibility, which an agent would want for a failover operation.

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 parameter 'service' is already fully documented including the `project.service` format. The description adds nothing about the parameter, 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 ('Make a replica a primary') plus the exact triggering condition ('when its primary is lost'), which cleanly separates it from siblings like add_replica, list_replicas, and update_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 a clear condition for use ('when its primary is lost'), which is the decisive selection criterion. It does not name an alternative or state when not to use it (e.g., versus normal failover or deploy), so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden, yet it only implies mutation via 'Remove'. It says nothing about irreversibility, impact on services currently bound to the domain, required permissions, or what is returned on success.

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 short sentence with no filler, and the verb is front-loaded. Brevity here is not padding, though it borders on under-specification given the destructive nature.

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

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

For an irreversible removal tool with no annotations and no output schema, the description should disclose consequences and side effects. Instead it gives only the bare minimum, leaving the agent to guess at risk.

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 there is a single required parameter already typed and documented as 'Domain id'. The description adds no format, provenance, or lookup hints 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 ('Remove a domain') with the identifier used, so the operation is unambiguous. It does not differentiate from the sibling add_domain or clarify whether this deletes the domain object, detaches it, or both.

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?

No guidance on when to use this versus add_domain, whether the domain must be detached from services first, or whether prerequisites exist. The agent must infer all of that from context.

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

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

With no annotations, the description bears the full disclosure burden. It implies disruption by saying containers are restarted, but doesn't state whether this is downtime-causing, rolling, or readiness-aware, nor whether it requires the service to be running or what it returns.

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 short front-loaded sentence with zero waste. It is arguably too terse, but nothing in it 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 an operational mutation tool with no annotations and no output schema, the description should cover disruption/availability implications and post-restart behavior. It covers only the bare action, leaving the agent guessing about risk and results.

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

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

Schema coverage is 100% and the single parameter is documented with format and an example ('shop.api'). 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 ('Restart') and resource ('a service's containers'), which distinguishes it from sibling verbs like start, stop, rollback, and deploy. It doesn't explicitly name those siblings as alternatives, but the action itself is unambiguous.

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

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

No indication of when to use restart versus stop+start or rollback, and no prerequisites or exclusions mentioned. The agent must infer usage from the verb alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose that rollback is a mutating and potentially disruptive operation, whether it is reversible, what happens to current traffic or replicas, or what permissions are required.

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

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

The description is a single, front-loaded sentence with no wasted text. It is appropriately sized for the tool's purpose.

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

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

For a mutating deployment operation with no annotations and no output schema, the description is incomplete. It omits consequences, safety profile, and expected outcome, leaving the agent without enough context to invoke it confidently in risky scenarios.

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 service and deploy_id parameters are already documented. The description mentions the optional deploy_id but adds no format, constraints, or behavior beyond the schema.

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

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

The description states a specific verb and outcome: roll back a service to its previous version or a specified deploy_id. It clearly identifies the operation, though it does not explicitly distinguish it from siblings like restart, deploy, or promote_replica.

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 briefly explains the default and optional target, but gives no when-to-use guidance relative to alternatives such as restart or deploy. There are no prerequisites, exclusions, or conditions under which rollback is inappropriate.

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 for a mutating, potentially long-running operation. It says nothing about whether the call blocks or returns immediately, required permissions, whether it can run concurrently with an existing backup, or how to learn of completion — all material for an agent invoking a backup kickoff.

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 short, front-loaded sentence with zero padding. It is efficient, though its brevity comes at the cost of the operational detail 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, no output schema, and a confusingly similar sibling `backup_run`, the description should explain the return/async behavior and differentiation. As written, an agent must guess on both counts.

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 parameter `job_id` is already documented in the schema, so the baseline of 3 applies. The description adds no meaning beyond it — notably it does not say that a job id is obtained from `list_backups`.

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 ("Run a backup job"), so the basic action is clear. However, the sibling list contains `backup_run`, a near-identical operation, and the description does nothing to distinguish the two — an agent cannot tell from this text which of the pair to call.

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 word "now" faintly implies on-demand execution versus a scheduled backup, but that is inference, not guidance. No alternatives are named, no exclusion is given, and the near-duplicate sibling `backup_run` is never acknowledged.

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 behavioral context. It discloses the scope of returned status data and the default target, but says nothing about permissions, rate limits, response structure, or whether the operation is strictly read-only.

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 efficient sentence with no wasted words. The core resource and returned status dimensions are front-loaded, and the default is appended compactly.

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, optional-parameter status tool, the description covers the returned data categories and default target. The main gap is lack of explicit contrast with the adjacent metrics tool, but the definition is otherwise sufficient to call it correctly.

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

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

The schema coverage is already 100% and the single node parameter is documented as a server id from list_servers. The description adds meaningful default behavior by saying the panel's own server is used when node is omitted.

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

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

The description clearly states a specific resource and the status dimensions returned: CPU, memory, disks, network, GPUs and per-service usage. It does not distinguish this tool from the sibling metrics tool, so it falls short of full sibling differentiation.

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 default clarifies that omitting node returns the panel's own server status, which is useful context. However, it does not explicitly say when to use this instead of metrics or list_servers, leaving usage mostly implied.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that null values delete variables and that a redeploy is required, but it omits permissions, overwrite/merge behavior, and whether changes are reversible.

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

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

The definition is compact and front-loaded, with no wasted wording. It communicates the operation, variable format, and required follow-up in one short statement.

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 covers the core call semantics and the redeploy requirement, but leaves important ambiguity for a mutation tool with no annotations and a nested object: whether provided vars merge with or replace existing variables, and what permissions or safety constraints apply.

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

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

The schema documents the service parameter, while the description compensates for the undocumented vars object by explaining its exact shape: {NAME: "value" or null}. This adds important meaning beyond the schema, especially the null-delete convention.

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: set or delete environment variables. It also explains the null-value deletion semantics, though it does not explicitly differentiate this tool from the sibling list_env tool.

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 post-call requirement ("Redeploy to apply") but does not explain when to use this tool instead of alternatives such as list_env, deploy, or restart. There is no explicit usage context or exclusion guidance.

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

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

With no annotations, the description carries the full behavioral burden but discloses almost nothing: no indication whether the operation is idempotent, whether it fails or no-ops on an already-running service, whether it's asynchronous, what permissions are required, or what is returned. This is a mutation/lifecycle tool, so these gaps matter.

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

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

Five words, front-loaded verb, zero waste. It is appropriately sized for a simple one-parameter action, though the terseness comes at the cost of the behavioral detail above.

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 structurally simple (one required string param, no nested objects, no output schema), but with no annotations and no description of post-call behavior or state preconditions, an agent cannot predict what happens when starting an already-running or nonexistent 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% and the single 'service' parameter already documents the id-or-`project.service` format. The description adds nothing 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?

"Start a stopped service" names a specific verb and resource, and the qualifier "stopped" implicitly distinguishes it from the sibling 'restart' (which would apply to running services). It's clear but doesn't explicitly call out that distinction or mention the 'stop' counterpart.

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 word "stopped" hints at the precondition, but there is no explicit guidance on when to use start vs restart, or what to do if the service is already running. Usage is only implied.

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

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

With no annotations, the description carries the full burden and discloses nothing beyond the verb. It doesn't say whether the stop is graceful or forced, whether traffic/connections are drained, whether the service can be resumed with 'start', or what permissions are required for this mutation.

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

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

A single front-loaded sentence with zero waste, but the brevity borders on under-specification rather than efficient precision.

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 on live infrastructure with no annotations and no output schema, the description should explain reversibility, shutdown semantics, and error behavior. None of that is present, so an agent cannot predict the outcome of calling 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%, and the schema itself explains the 'service' parameter including the `project.service` format. 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 ('Stop') and resource ('a service'), so the action is unambiguous. However, it does nothing to distinguish this from sibling tools like 'restart', 'start', or 'delete_service', leaving the agent to infer the boundary on its own.

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 stop versus restart or delete_service, nor any stated preconditions (e.g. service must be running, or already-stopped services are a no-op). The single sentence provides only the bare action, no context for 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 disclose two real behavioral traits: the update is a JSON merge patch (partial, unspecified fields preserved rather than replaced) and changes do not take effect until a redeploy. It omits permissions/authorization requirements and whether the change is reversible, which keeps it from 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 with zero filler; the core action is front-loaded and the operational caveat follows immediately. Nothing is repeated from the schema or 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, no output schema, and an opaque nested `spec` object, the description covers the merge semantics and the redeploy requirement but leaves the agent guessing about valid spec fields and the response shape. Adequate but with clear gaps.

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

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

Schema coverage is 50%: the `service` parameter is documented in the schema ('Service id or `project.service`'), but `spec` is an untyped nested object with no field-level documentation. The description adds real meaning by saying the spec is a JSON merge patch, implying partial specs are acceptable, but it never says which spec fields are valid or required.

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

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

States a specific verb ('Change') and resource ('a service's settings') plus the mechanism ('JSON merge patch of its spec'), which clearly separates it from create_service and delete_service in the sibling list. It stops short of naming the siblings it is distinguished from, so it lands at 4 rather than 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?

'Redeploy to apply' gives a useful follow-up cue pointing toward the deploy/restart siblings, and 'Change a service's settings' implies the mutation use case. There is no explicit when-not guidance (e.g., use create_service to create, delete_service to remove) and no prerequisites, so usage is only implied.

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