Pethost

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

Beyond annotations (readOnly=false, destructive=false, idempotent=false, openWorld=true) it discloses that the machine writes compose.yaml and /.env and deploys the project, that the database has no address and is reached via the `<project_id>` host once linked, and that snapshot copies get their own passwords and no links. The error taxonomy (INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION, DatabaseLinkRefusal) plus the crucial 'nothing was created' guarantee on link refusal is exactly the kind of context annotations cannot carry.

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

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

It is front-loaded with the core action and wastes little on filler, but the prose is telegraphic and run-on, with clauses like 'a project_id with "_", that is a number or that every container's /etc/hosts names' requiring re-reading. The error-code block earns its space; the sentence structure is what drags this down.

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

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

For a 7-parameter, zero-required, mutating tool with no output schema, the description covers deployment mechanics, linking, snapshot provenance, and failure modes thoroughly. The remaining gap is return-value shape, deferred with 'Answers as CreateProject does', which leaves the agent to consult a sibling tool for the response.

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 already 86%, so the baseline is 3, but the description adds real semantics on top: project_id is the host name apps use and is barred from '_', numeric, or /etc/hosts names; snapshot copies carry their own passwords and none of the source's links; engine/size validity is tied to Machine.database_engines. It does not explain operation_id or wait_seconds beyond pointing at DeployProject's definitions, which the schema already does.

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

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

The opening clause states the specific resource and its two engines ('A database project, Postgres or Valkey') and the secondary snapshot-copy mode is called out explicitly. It also implicitly separates itself from CreateProject (app) and LinkDatabase by naming them as the linking path, though the dense phrasing makes the distinction slightly harder to extract than it should be.

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

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

Gives explicit ordering guidance ('Make it before the app that uses it') and names the alternative path for linking ('`link`, or LinkDatabase after the app's CreateProject'). It also frames the snapshot-copy variant as an alternative to an empty database. No explicit when-not-to-use case, which keeps it off 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?

Beyond the annotations it discloses that the call waits for the deploy, what the response contains (URL, service states, problems), the meaning of `violations` (nothing created, retry after fixes), that SUCCEEDED does not mean the page serves, the 401 password-page caveat, and the ALREADY_EXISTS/FAILED_PRECONDITION semantics. This is exactly the extra behavioral context annotations cannot convey.

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

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

The core action is front-loaded well, but the body expands into a long compose-file rulebook (volumes, ports, refusals, interpolation). Much of that knowledge is necessary for a successful call, yet it reads as an embedded manual rather than a description, which hurts scanability.

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

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

For a complex eight-parameter nested deploy tool with no output schema, the description covers sources, response shape, error codes, and the deployment contract thoroughly. Nothing an agent needs to invoke it correctly is obviously missing.

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

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

Schema coverage is 100%, so the schema already documents every field, but the description still adds substantive meaning: the precedence of pethost.compose.yaml over compose.yaml, what an upload_id requires, how `source` interacts with `files`, and the x_pethost route/password semantics. This goes well past the schema descriptions.

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

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

The first sentence states a specific verb and resource — 'Creates a project from its files and deploys it' — and the description then positions the tool against siblings by assigning databases to CreateDatabase and archives to CreateTransfer. An agent can tell this apart from DeployProject without opening either schema.

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

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

It gives clear conditions for each file source (directory, CreateTransfer archive, `files`, `source.github`) and explicitly routes databases and archives to sibling tools. It does not, however, explicitly state when to prefer this over DeployProject for an existing 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?

Annotations already flag destructive=true and non-idempotent, and the description goes well beyond them: it discloses the 2 GiB archive limit, 422 unsafe-archive reasons, replacement semantics ('replacing any file there'), that a failed transfer keeps nothing and needs a fresh URL, disk-full/dump-in-progress constraints, and a full status-code-to-meaning table. That is exactly the extra behavioral context the annotations cannot carry.

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

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

Purpose and variant list are front-loaded and the bullet structure makes modes scannable. The trailing error-code paragraph is a run-on chain of terse clauses ('404 used or expired URL, 409 FAILED_PRECONDITION...') that is dense to parse, though each clause carries distinct, non-redundant information.

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

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

For a multi-variant, nested-object tool with no output schema, the description covers the return artifact (a one-request URL), expiry, per-mode constraints, and failure semantics thoroughly. It is slightly incomplete in that the command/http modes it mentions are absent from the schema, leaving the agent unsure which modes are actually callable.

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

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

Schema description coverage is 100%, so the baseline is 3, and the bullets mostly restate variant semantics already in the schema (file_name default, empty=root, at-most-one constraints). Worse, the opening sentence advertises 'run `command` in a shell, or send `http_method` to `url`' parameters that do not appear anywhere in the input schema, creating a mode/schema mismatch rather than added parameter meaning.

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

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

The opening sentence names the operation (create a one-request URL that moves a file or runs a command against the machine) and the four schema variants are spelled out as bullets, so the resource and scope are identifiable. It does not, however, distinguish itself from siblings such as ReadPath or RunServiceCommand, which perform overlapping read/exec work, so the agent must infer the boundary.

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?

Each variant carries a use condition: upload_archive is explicitly 'for CreateProject's or DeployProject's upload_id', download notes 'at most one of service, volume', download_database warns 'one at a time per database', and upload_archive says to exclude build output. This is clear context for choosing a mode, but no explicit when-not-to-use or routing to the command/http siblings.

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

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

Annotations flag destructive/openWorld but the description carries substantive extra detail: what `files` overwrite, that stopped services are started and containers recreated, the wait logic (healthcheck/job-exit/route-listening up to 15s), the SERVICE_PORT_CLOSED vs 502 distinction, the at-once x-pethost path, the pinned-commit side effect on auto_deploy, and per-error-code semantics including Operation.made_current. This goes well beyond the annotation safety profile.

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

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

The purpose is front-loaded, but the body is an extremely dense, run-on wall of text with heavy abbreviations and cross-references ('answers as CreateProject does') that strains comprehension. Given the tool's complexity the length is defensible, but the structure does not earn the density.

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

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

For a 12-parameter, nested, mutation-heavy tool with no output schema, the description covers lifecycle, waiting, error codes, and interdependencies (auto_deploy pinning, route/password timing) well. Return-value details are omitted, but they are largely delegated to CreateProject's answer shape, leaving only minor gaps.

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

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

Schema description coverage is 92% and the schema itself documents every parameter and nested field in detail, so the baseline is 3. The prose adds some cross-parameter meaning (operation_id retry semantics, base_deploy_id abort behavior, rollback_deploy_id scope) but much of the rest defers to 'CreateProject's rules' rather than adding new parameter semantics.

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

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

The opening sentence states a specific verb and resource ('Deploys a new version of a project') and immediately bounds the operation ('answers as CreateProject does'), so the agent knows it acts on an existing project rather than creating one. The subsequent enumeration of inputs (files, x_pethost, mount_volume, upload_id, commit, rollback) makes the scope concrete and distinguishable from CreateProject.

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

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

It gives explicit sequencing and preconditions: set the password in a separate call before deploying to hide content, write /compose.yaml when no new version exists, and use base_deploy_id then 'reread, redo' on ABORTED. It names alternatives and their selecting conditions ('GetOperation waits on' when still IN_PROGRESS, CreateTransfer for oversized files, set_source to re-enable auto_deploy), which is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond them: figures are the latest sample, and disk sizes and the day's traffic lag a few minutes. That staleness caveat is exactly the kind of detail an agent cannot get from structured fields.

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

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

A single dense sentence that front-loads 'Start here' and then lists returned content, followed by the freshness caveat. The enumeration is long but each item maps to real content the caller will receive, so little 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?

With no output schema, the description carries the burden of describing return contents, and it does so by enumerating the main sections plus the freshness caveat. It omits nothing critical for a zero-argument orientation tool, though it does not hint at response shape or size.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema accepts an empty object with additionalProperties false, which is consistent with a no-argument read.

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-plus-resource ('the machine') and then enumerates exactly what it returns: resources, the person's domain, backups, SSH, every project with problems and URL, deleted projects with snapshots, GitHub repos. This makes it clearly distinguishable from narrower siblings like GetProject or ListCommits.

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?

'Start here' is an explicit entry-point directive that tells the agent when to reach for this tool first. It stops short of naming alternatives or stating when-not to use it (e.g. vs GetProject for a single project), so it is clear but not fully routing-aware.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, but the description adds real behavioral context: the wait semantics, the requirement to re-call while IN_PROGRESS, the incremental log-reading protocol via after_log_line/next_after_log_line, and the ProjectBusy-wait/UNAVAILABLE outcome. These are operationally important traits not conveyed by the annotations. It stops short of describing return shape or pagination limits in full.

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 content is dense and mostly earned, but the sentence fragments and mid-sentence pivots ('then the project as it is, and the log's end if it FAILED') make it hard to parse. The most important concept, that this is a polling operation-status tool, is not front-loaded clearly.

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

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

There is no output schema, so the description must explain what comes back. It references the project state and the log's end (on FAILED) and the UNAVAILABLE outcome, giving partial return context, but the actual response shape (fields, how IN_PROGRESS vs FAILED results differ) remains underspecified for a 5-parameter tool with no output schema.

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

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

Schema coverage is 80%, so the baseline is 3, but the description meaningfully extends it: it explains the wait_seconds behavior, the after_log_line chaining ('0' to start, then each next_after_log_line, oldest first), and the ProjectBusy wait semantics. This adds non-obvious protocol detail beyond the schema descriptions.

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

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

The title and name say 'Get an operation,' and the description implies fetching an operation while waiting for it to finish, but the opening fragment 'An operation, after waiting for it to end' never states a clean verb+resource. It does distinguish a polling/status-read tool from siblings like QueryContainerLogs and GetProject by mentioning IN_PROGRESS and log reading, but the telegraphic phrasing leaves the core purpose partly to inference.

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

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

'Call again while it is IN_PROGRESS' gives explicit polling guidance, and the ProjectBusy/UNAVAILABLE note hints at retry conditions. However, it offers no guidance on when to prefer this over siblings such as GetProject or QueryContainerLogs, 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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the exact data surface returned, and the sensitive-data constraint that env-file values and database passwords (Project.database.connection) appear only with include_secret_values. No contradiction with annotations.

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

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

Dense but front-loaded: the data surface is listed first, then the secrecy caveat, then the file-handling pointer. Every clause conveys return content or a constraint; slightly long but nothing feels wasted.

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

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

There is no output schema, so the description must carry the return-value burden — and it does, enumerating the returned collections and the secret-gating rule. For a read-only project getter this is nearly complete; only the pagination-parameter interplay (incidents_before/snapshots_before) is left to the schema.

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

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

Schema coverage is 86%, so the baseline is 3, but the description reinforces the most consequential parameter — include_secret_values — including what is gated (env values, DB password) and where to edit .env instead. This adds meaning and safety guidance beyond the schema text.

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

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

States a specific verb+resource ('one project in full') and enumerates the returned sub-resources (services, volumes, routes, hosts, snapshots, HTTP traffic), so the agent knows exactly what it retrieves. It is distinguishable from GetMachine and GetOperation by the project scope, though it never names those siblings explicitly.

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

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

Usage is implied (this is the full-project getter) rather than stated. The one routing hint given — 'Its files: ReadPath' — points away for file content, but there are no when-to-use/when-not conditions or alternatives for the project data 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?

Beyond annotations, the description discloses immediate effect, that nothing is deployed, how credentials are obtained via GetProject include_secret_values, the return value, and concrete error mappings including DatabaseLinkRefusal causes. This gives the agent substantial operational context for a destructive 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?

The description is front-loaded with the core purpose and is dense but generally efficient. The terse error-code notation and packed clauses reduce readability slightly, but there is little 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?

For a 3-parameter mutation tool with no output schema, the description covers purpose, effects, credentials, return value, and key failure modes. An agent has enough information to invoke it correctly and anticipate common errors.

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 already describes link and unlink, but database_project_id has no schema description. The description compensates by stating it must be a database project and explaining the resulting host/port behavior, while also clarifying the mutual-exclusion constraint between link and unlink.

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 action: linking projects to a database project so they can reach it. It also explains the resulting host/port behavior and sign-in mechanism, making the tool's purpose distinct from siblings such as CreateDatabase or CreateProject.

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

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

It explains when linking takes effect and notes that both link and unlink can be used, with a specific INVALID_ARGUMENT rule for overlapping IDs. It does not explicitly compare this tool to sibling alternatives, so it falls short of full when-to-use/when-not guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description earns credit for adding pagination size (30 a page), sort order (newest first), and concrete error semantics (FAILED_PRECONDITION causes). The 'volumes keep their current data' note is useful rollback side-effect context.

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

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

The purpose is front-loaded, but the paragraph is dense and some clauses are garbled, e.g. "with whether the files are at it and its last deploy," which costs clarity. Rollback guidance is useful but competes with the primary list semantics in one run-on block.

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

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

With no output schema, the description carries the return-value burden and does partially disclose what comes back (commit list with deploy/file state). Error conditions and pagination are covered; only project_id semantics and a cleaner return description are missing.

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

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

Schema description coverage is 50%: before_commit is documented in the schema itself, but project_id is undocumented in both places. The description references before_commit only indirectly ("not on it") and adds no format or usage detail beyond the schema, so baseline 3 is appropriate.

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

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

The description names a specific verb (list) and resource (a github project's branch commits) and even scopes it to commits that change the directory. It is distinguishable from siblings like DeployProject or GetProject, though the phrasing is telegraphic and includes unrelated rollback context that muddies the core purpose.

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

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

It gives clear conditions for the related rollback path (use DeployProject with an older commit) and enumerates the FAILED_PRECONDITION causes, which is genuinely actionable routing guidance. It lacks an explicit statement of when NOT to call it, but the alternatives are named.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the meaningful context that this is a host-facing UI affordance rather than an agent data source, but says nothing about return shape, ordering, or result limits.

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 clauses with no filler, and the audience/alternative constraint is stated up front. The phrasing is slightly oblique ('The host's own: the person's projects'), which costs it a point.

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-only lookup with full schema coverage and annotations, the description is adequate, but with no output schema it never states what is actually returned (project names, ids, count) or whether results are paginated.

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 query parameter is fully documented in the schema, including the 'Empty = every project' default. The description adds no syntax, matching, or case-sensitivity detail beyond that, 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 description identifies the resource (the host's projects) and its intended consumer, and explicitly distinguishes itself from GetMachine. However, it supplies no verb describing the operation itself (list/search/return), so the agent must infer that calling it yields a project collection for mention autocomplete.

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 an explicit when-not ('Not for an agent') and names the alternative source of the same data (GetMachine), which is exactly the routing signal an agent needs. It falls short of 5 only because it doesn't spell out the positive case for an agent calling it or any prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tab only opens where an app supports such tabs, which is useful context. It doesn't describe failure behavior when no tab is available.

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 dense sentences, front-loaded with the purpose and the caller constraint, then the exclusion. Every clause earns its place.

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

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

For a zero-param, read-only UI tool with full annotations, the description is sufficient. The only gap is what happens when no tab-capable app is present, but that's minor for a one-shot host action.

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?

Zero parameters, so baseline is 4. There is nothing to disambiguate, and the description correctly spends no words on absent parameters.

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 clear action (opens a project's page in a tab beside a conversation) and pins down the caller ('the host's own'). This is distinct from GetProject, but the phrasing is slightly opaque without knowing the host's UI model.

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

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

Explicitly names the intended caller and a not-for case, and routes the agent to the sibling Show for agent-facing project display. This is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavioral context: OUT_OF_RANGE means the range ends before the oldest kept log, default ordering is newest-first within the page, and the payload is flagged 'Untrusted' (a prompt-injection caution). Return format and rate/volume behavior remain unstated, so not 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?

Every clause carries information and the differentiating statement is front-loaded early. The telegraphic fragments ('OUT_OF_RANGE = ...', 'Untrusted.') are efficient, though the one-word 'Untrusted.' is slightly cryptic without further framing.

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 8-parameter, no-output-schema read tool with a nested filter object, the description covers return content, error semantics, ordering defaults and data-trust posture, which is most of what an agent needs. Pagination and limit truncation behavior live in the schema, so the remaining gap is minor.

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%, so the schema already carries most parameter meaning (limit caps, stream enum, end_time default, page_token usage). The description adds only the default start/order framing ('since oldest_kept_time', 'by default the newest, oldest first'), which is largely redundant with from_start and start_time descriptions. Baseline 3 is appropriate.

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

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

The description names the concrete resource ('the containers' stdout and stderr lines') and explicitly routes latency questions elsewhere ('not which path is slow: that is QueryHttpTraffic'), so an agent can separate it from its closest sibling. The verb is only implied by the tool name rather than stated, which keeps it just 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?

It gives a clear use case (diagnosing what a request failed with) and names the alternative tool for the adjacent question (which path is slow -> QueryHttpTraffic). It stops short of explicit when-not conditions or prerequisites, so no 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond them: retention via oldest_kept_time, the OUT_OF_RANGE failure mode when the range precedes the retained window, and a security warning that paths and user agents are untrusted.

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?

Word count is reasonable for an 8-parameter tool, but it is a single dense sentence stitched together with colons and the phrase 'each counted as it ends' is ambiguous. The key delimiting facts (retention, OUT_OF_RANGE) arrive late and are not front-loaded.

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

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

For a complex, unannotated-output tool the description usefully enumerates the return shape (totals, series, top paths, requests), substituting for the absent output schema, and discloses the retention boundary. It omits auth/permission needs and pagination behavior, but the schema's page_token field partly fills that gap.

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

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

Schema description coverage is 75% and the nested filter object is well documented, so the schema carries most parameter meaning. The description only restates 'one filter and range' without adding syntax, defaults, or interaction rules (e.g. last_seconds vs start_time), so the baseline of 3 applies.

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

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

The description names the resource (HTTP requests reaching the project through the proxy) and the returned artifacts (totals, time series, top paths, requests), plus the use case 'which paths fail and which are slow'. It is not a clean verb+resource phrasing and the colon-chained run-on makes the core action harder to extract, but an agent can tell this apart from the project/machine 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?

Usage is implied by the framing 'which paths fail and which are slow' and by the constraint 'for one filter and range', and it clarifies OUT_OF_RANGE semantics. However it names no alternatives and gives no explicit when-to-use/when-not-to-use guidance relative to QueryContainerLogs or other siblings.

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

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

Annotations cover read-only/idempotent/non-destructive, but the description adds substantial behavior: per-call and per-read size caps, page sizes, container-state-dependent visibility, and specific error semantics (NOT_FOUND names the nearest directory; FAILED_PRECONDITION covers no-deploy and /proc /sys). The 'Untrusted' security warning is a valuable disclosure not present in the structured fields.

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

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

Heavily front-loaded with the core action and free of filler. It is information-dense but structured as one long semicolon-heavy sentence, which costs some parseability.

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 8 parameters, 88% schema coverage, rich annotations, and no output schema, the description covers modes, limits, pagination, and errors thoroughly. It could say a bit more about the return shape (entries vs. bytes) since no output schema exists, but it references page tokens and sizes, making it largely sufficient.

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 88%, so the schema already carries most parameter meaning, and its own description field already states 'at most one of service, volume' and that neither means the project's deployed files. The top-level description largely restates these, adding little syntax or constraint detail 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 ('Reads') and resource ('a file or a directory's entries'), then enumerates the exact sources: project's deployed files, a container filesystem (or its volumes when stopped), or a volume. It is immediately distinguishable from siblings like RunServiceCommand, which it names as the alternative for /proc and /sys reads.

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

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

Gives clear context for the various modes and explicitly routes one case to an alternative ('use RunServiceCommand' for /proc or /sys files). It also ties file freshness to DeployProject and CreateTransfer, implying when results may change. It stops short of stating when to prefer this over Show or GetProject for introspection.

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

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

Annotations declare destructiveHint=true, openWorldHint=true, idempotentHint=false, readOnlyHint=false, which already signals this is a mutating, potentially destructive operation. The description adds some specific behavioral notes like 'its key can open new ones until removed' and 'Containers come back per restart policy', which are useful beyond annotations. However, it does not fully disclose side effects like session termination implications or permission requirements, so the added value is moderate.

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

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

The description is a single, front-loaded sentence that efficiently lists the operations and key outcome. It is appropriately sized and contains no redundant information, though it could be slightly more structured with bullet points for clarity.

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

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

Given the complexity (5 parameters, nested objects, destructive operations) and the lack of an output schema, the description is minimal. It states what the tool does and returns (the machine), but does not cover important context like return value details, error handling, or prerequisites. With annotations covering safety, it is borderline adequate but leaves gaps.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema itself. The description does not add syntax, format, or validation details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states clearly what the tool does: 'One machine action: add or remove the person's SSH public key ... end a session, schedule or cancel a restart.' This is a specific verb and resource (machine action) and enumerates the operations. It does not explicitly differentiate from siblings like RunProjectAction or RunServiceCommand, but the scope (machine-level actions) is clear enough that an agent can distinguish it.

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

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

The description lists possible actions but does not explain when to use this tool versus alternatives. It gives some implied usage via the SSH key context (for SSH and SFTP to containers), but there is no explicit when-to-use guidance or exclusions. An agent must infer the context from the operations available.

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

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

Annotations already declare destructive/non-idempotent/open-world, and the description adds substantial behavior beyond them: which actions run as asynchronous operations and block on wait_seconds versus completing on return, that the response is the project as it then is, that delete_project leaves snapshots restorable, and that stop honors each service's grace period and restart policy.

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

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

Front-loaded with the action list, and each sentence carries information (operation semantics, return value, snapshot restriction). Some passages are densely telegraphic ('as is the end of a cancelled one'), but nothing is purely filler.

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

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

For a 13-parameter, 0-required, no-output-schema tool, the description supplies the missing return-value statement and the async/sync split for each action. It is close to complete, with the remaining gap being explicit sibling routing for deploy and operation polling.

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 92%, so the schema carries most parameter detail (baseline 3). The description still adds meaning by tying operation_id/wait_seconds to the specific actions that run as operations and by stating that restore_snapshot only accepts this project's own snapshots, which the schema text does not make as explicit.

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 enumerates the concrete verbs and resources this polymorphic tool performs (start/stop/restart services, recreate, back up, restore, cancel, set_source, delete volume/project) and states that exactly one action runs. It is clearly distinguishable from read-only siblings like GetProject, but it never explicitly says that deploying is DeployProject's job, leaving one ambiguity against that sibling.

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

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

Usage is implied through the action enumeration and the schema-level 'at most one of ...' constraint rather than stated as when/when-not. It does give one explicit exclusion ('A database's snapshot as a new database is the person's to make, in the panel'), but no routing to siblings such as DeployProject or GetOperation for polling operations.

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

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

Goes well beyond the annotations (destructive/openWorld/idempotent=false) by disclosing return shape (exit code plus only the tail of output), truncation behavior, that over-bound command/stdin/timeout is refused with the offending parameter named, that failure to start surfaces as exit 127/126 with Docker's error in stdout, and that output is untrusted.

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

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

Purpose and return contract are front-loaded in the first clause, and every later sentence carries real operational information. The telegraphic fragments ('Over a bound on command, stdin or timeout = refused (named)') cost some readability 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 destructive, open-world exec tool with no output schema, the description covers return values, truncation, refusal and failure modes plus a security caveat. It stops short of stating permission/auth requirements or environment restrictions, which are the remaining 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 71% and the schema already documents stdin, command, run_as_user, timeout_seconds and working_directory. The description adds the useful refusal semantics tied to the command/stdin/timeout bounds, but service and project_id remain undocumented and no syntax detail is added beyond the schema's examples.

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

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

States a specific verb and resource ('Runs a command in a running service's container') and anchors it to a familiar analogue ('like `docker exec`'), which immediately separates it from siblings such as RunMachineAction, RunProjectAction and QueryContainerLogs.

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 docker-exec analogy, and refusal conditions are given, but the description never states when to choose this over the sibling action/log tools or any prerequisites for calling it.

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

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

Beyond the destructive and idempotent annotations, the description discloses what gets replaced, what remove_* does, which alerts are always enabled, what the tool returns, and that delivery channels cannot be set here. This is strong behavioral context for a destructive mutation tool.

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

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

The purpose is front-loaded and the description is information-dense without wasted filler. The single dense paragraph and awkward phrasing such as "send Project.alerts' with your change" keep it from being maximally clear.

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

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

For a complex destructive tool with nested alert rules, the description covers replacement semantics, removal behavior, defaults, always-on alerts, and the return reference. It is nearly complete, though it gives only the Project.alerts return name without describing the returned structure because no output schema is provided.

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 high at 86%, so baseline would be 3. The description adds useful semantics beyond the schema, especially that a list replaces the project's whole list and that callers should send the existing Project.alerts with their change to avoid losing entries.

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

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

The description states a specific operation, changing a project's monitored site checks and traffic rules, plus off and mute behavior. It clearly distinguishes alert configuration from alert delivery by noting that alert channels are set in Settings → Alerts and that no tool sets 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?

It explains important update semantics: a supplied list replaces the existing list, remove_* empties it, omitted scalars remain unchanged, and crashes/backups are always watched. It also states a clear limitation about alert channels, though it does not give explicit use-versus-alternative guidance beyond that.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-obvious behavior: it renders a view in the conversation, returns no data, supports user-adjustable filters, and changes the required post-call narration. That is substantial context beyond the structured metadata.

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

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

The core purpose is front-loaded and every sentence carries information, though the single dense paragraph is somewhat run-on and could be broken up for scanability.

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

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

With no output schema, the description correctly explains that no data is returned and that a sibling should be used for data, and it covers the follow-up behavior expected of the agent. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and every parameter already carries a per-value description, so the schema does the heavy lifting. The prose restates the view modes and notes that filters apply to requests/logs, but adds little beyond the enum documentation.

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 pairs a specific verb ("shows ... a live view") with a concrete resource and enumerates all five view modes (machine, project, uptime, requests, logs). It clearly distinguishes this rendering tool from the data-returning siblings GetMachine/GetProject/QueryHttpTraffic/QueryContainerLogs.

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

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

It states explicitly when to call it ("when they ask to see something, or when a view says more than a sentence would") and names the alternative tools that return data instead. The routing condition between this and the query tools is unambiguous.

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