fline

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

Annotations already declare this is a write (readOnlyHint=false), idempotent, and non-destructive, so the safety profile is covered. The description adds nothing behavioral beyond that: it doesn't say whether answers replace prior ones, whether the questions are returned first, or what completion 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?

A single short sentence with no padding, which is efficient. But the brevity stems from under-specification rather than disciplined editing, so it earns a middling score.

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 zero schema description coverage, no output schema, and a nested parameter shape, the description is far too thin. An agent cannot tell what a valid answer payload looks like or what happens on success.

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

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

Schema description coverage is 0% across three parameters, including a nested answers array of key/value objects, so the description carries the full burden and fails to. It never explains the key/value structure, how keys map to questions, or what idempotency_key does, adding no meaning beyond the field names.

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 verb+resource ("answer the questions") and adds the scoping phrase "raised during source analysis," which distinguishes it from the generic sibling set. However, it never explains what these questions are, where they originate, or what an "answer" constitutes, leaving the core purpose only half-defined.

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 invoke this tool, what prerequisite state (e.g., a completed analysis) must exist, or how it relates to siblings like submit_declaration or declare_env_names. The agent must infer the workflow entirely.

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

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

Despite annotations covering safety and idempotency, the description adds rich behavioral detail: it returns TXT record values (challenge_name, challenge_token), explains that fline checks automatically for 48 hours, and notes that check_domain checks immediately. This goes well beyond the structured annotations.

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

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

The description is dense but front-loaded, starting with the core action and following with return values, verification process, and guidance. Every sentence contributes useful information without redundancy.

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

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

With no output schema and low parameter documentation, the description does a good job explaining the expected response and verification flow. However, it omits details about project_id and idempotency_key, which an agent may need to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It gives an example for domain (www.example.com) and implies project context, but it never explains project_id or the optional idempotency_key, leaving two of three parameters semantically unclear.

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: attaching a web address/domain to a project. It clearly distinguishes this tool from siblings like list_domains, check_domain, and delete_domain by explaining its unique action and outcome.

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

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

It provides clear context: prefer a subdomain because most DNS providers allow no CNAME on a bare name, and it references the use_a_web_address prompt. It also names related tools (list_domains, check_domain) and their roles, though it does not explicitly state when not to use this tool versus alternatives.

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 the safety profile (idempotentHint=true, destructiveHint=false), and the description adds genuinely new traits: the project transitions to awaiting_secrets, no credentials are ever accepted here or anywhere, and a duplicate variable is refused with the conflicting alias named. This is strong behavioral disclosure beyond the annotations.

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

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

Front-loaded with the core constraint, then defaults, then the workflow and error rule. Dense but every clause adds meaning; the only slightly redundant line is 'This takes the shape only,' which restates the no-credentials point made later.

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

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

No output schema exists, and the description compensates by describing the resulting state (awaiting_secrets) and the refusal condition. It is nearly complete for a 5-parameter mutation, with idempotency_key semantics being the main unexplained element.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: offering is enumerated (postgres, redis, mysql, mongodb, rabbitmq), alias is explained as the discriminator with a default of 'db', and variable is mapped to per-offering defaults (DATABASE_URL, REDIS_URL, MONGODB_URI, AMQP_URL). Only idempotency_key and project_id semantics are left unstated.

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 ('Declare a backing service the tenant ALREADY RUNS') and immediately distinguishes it from the provisioning path ('so the platform does not provision one'). An agent can separate this from create_service and detach_external without opening a 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?

Clear context for use: only when the tenant already operates the service, with the natural contrast that the platform would otherwise provision it. It also names the follow-on tool (get_secrets_link form) that the human must use. It never explicitly names create_service as the alternative to pick instead, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: no cost, no deployment, and 'answers either ok, or the reason each part was refused,' which tells the agent this is a pure iterative validator. It is consistent with the annotations.

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

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

The purpose is reasonably front-loaded, but the body is dense and drifts into schema-level detail (rules for env_names values and health_path) framed as prose. The port-field tangent ('There is no port field and there is no need for one') is verbose, weakening economy, though the detail does compensate somewhat for empty schema descriptions.

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 supplies the return contract ('ok, or the reason each part was refused') and detailed domain rules for the config format, which is substantial for a validator. It falls short only on the two input parameters, neither of which is explained.

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

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

Schema coverage is 0% with two required params (project_id, config) and a nested config object. The description elaborates heavily on the fline.json content rules (env_names, health_path), which implicitly informs the config param, but it never maps that to 'config' and never mentions project_id at all, leaving 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 gives a specific verb+resource: 'Check a fline.json against the last uploaded archive,' and disambiguates from deploy by stating 'without deploying and without cost.' It's clear what the tool does, though it never explicitly names a sibling (e.g. deploy, refresh_config) to route against.

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 implies a workflow context ('edit and ask again until it is ok, then save the file'), which suggests pre-deploy validation. However, it never mentions alternative tools (deploy, submit_declaration) or when-not-to-use, leaving the agent to infer the validate-then-deploy ordering.

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 only declare the broad hints (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds substantial context the annotations cannot: the check reaches out to DNS, is rate-limited behind a certificate budget, expects minute-scale polling, and defines the 48-hour hard-failure window that maps to domain_failed.

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, then the prerequisites and timing constraints; every sentence carries operational information. It is dense and slightly run-on, but there is no filler to cut.

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 does describe the result semantics (answers the check, yields domain_failed on permanent failure) and the full remediation loop, which is what an agent needs. The remaining gap is the unaddressed idempotency_key and the exact success/failure response shape.

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

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

Schema coverage is 0% across three parameters, so the description must carry the load, and it largely does not. hostname and project_id are only obliquely implied by 'one of the project's domains', and idempotency_key — important given idempotentHint=false — is never mentioned.

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 the ownership check for one of the project's domains now') and even describes the answering behavior. It is clearly separable from siblings such as list_domains, attach_domain, and delete_domain.

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 says when to call it ('after the DNS record is published'), how to call it ('poll in minutes rather than in seconds' due to the certificate budget), and what to do on permanent failure (delete_domain, fix the record, attach_domain again). Alternative tools are named with the condition that selects them.

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 say it is not read-only and not destructive, and the description adds real behavioral context: the platform does not observe the upload, the old runtime keeps running during an update, and this is the trigger that moves the project out of awaiting_source. It does not discuss error cases or whether idempotency_key protects against re-submission.

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

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

Four sentences, each adding a new fact: what it does, why it is needed, what happens on update, and where blob_key comes from. Front-loaded with the action, then the rationale, then the prerequisite, so it is well-structured and dense.

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

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

For a three-param mutation with no output schema and no annotations about side effects beyond flags, the description covers the state transition, the source of blob_key, and the update behavior. Missing: what the response contains and whether idempotency_key is recommended to avoid duplicate analysis.

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

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

Schema coverage is 0%, so the description must compensate. It explains that blob_key comes from create_project or get_upload_url, which is critical linkage that the schema does not provide. project_id and idempotency_key are not explained, but the flow context makes project_id obvious.

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?

It states a specific verb and resource ('Report that the archive is uploaded and start the analysis'), separating it from sibling tools like get_upload_url and create_project, which is exactly the flow it sits in. The dual mode, first submit vs. update of an already submitted project, is also called out.

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?

'until this call the project stays in awaiting_source' implies when to call it, and naming create_project and get_upload_url as the sources of blob_key gives the agent the ordering needed. It does not explicitly state when not to call it, but the context is clear for this flow.

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=false, destructiveHint=false, openWorldHint=false, so the write profile is known. The description adds genuinely non-obvious behavior that annotations cannot convey: the call returns upload_url and blob_key, and the actual archive PUT goes straight to storage outside this interface, with complete_upload required for visibility. That is strong added context, though nothing is said about failure modes or what happens to a project left incomplete.

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

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

Three tight sentences front-loading the action, then the return values, then the mandatory next step in causal order. The opening sentence merely restates the title, but everything after it is load-bearing and there is no filler.

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

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

With no output schema, the description correctly compensates by naming the two returned fields and explaining the two-phase upload. For a two-parameter creation tool with explicit annotations, the missing piece is only the semantics of idempotency_key and what happens if complete_upload is never called.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it explains neither parameter. The purpose of idempotency_key — the one parameter whose semantics are genuinely non-obvious — is left entirely undocumented, and the annotations even say idempotentHint=false, which makes its role more, not less, confusing.

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?

"Create a project" gives a specific verb and resource, and the follow-on sentences clarify what the call actually produces (upload_url, blob_key) rather than just a project record. It never contrasts itself with create_service or the list/get siblings, so an agent must infer placement from naming alone.

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

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

The description gives a clear mandatory follow-up: after uploading the archive, complete_upload must be called or the upload is invisible to the platform. That is real workflow routing to a named sibling. It stops short of stating when to create a project versus an alternative path (e.g., create_service), and no prerequisites or permissions are mentioned.

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 the write/non-idempotent profile, and the description adds substantial behavior the annotations cannot: no password or key is returned by any tool, where the connection string is surfaced, the provisioning→active status lifecycle, and the engine/version/size_class defaults. This is genuinely additive rather than restating annotations.

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

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

The purpose is correctly front-loaded, but the first sentence is a run-on packing three engine definitions into nested dashes, and the body is a dense wall of caveats. Each claim is useful, yet the formatting makes it harder to scan than it needs to be.

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 no output schema and 0% param coverage, the description does heavy lifting: it states defaults, the returned status, where secrets live, and the workspace-vs-project ownership rule. The only real gap is any mention of the idempotency_key semantics.

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

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

With 0% schema coverage and 5 parameters, the description must carry the full burden. It explains engine values and the defaults for version and size_class, but the required `name` parameter's acceptable values/format is only implied through the <project name>-postgres discussion, and `idempotency_key` is never mentioned at all.

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

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

The opening sentence gives a precise verb+resource ("Create a data service for this workspace") and immediately enumerates the three valid engine values with a plain-language gloss for each. An agent knows exactly what the tool produces and which inputs map to which backend without opening the schema.

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

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

Explicit when-not guidance is provided: NEVER write postgres/redis/valkey/minio/s3 into a compose file or plan, a project does NOT need this tool to get a database via the managed-ref path, and buckets are the exception that must be created here. It even points to the add_a_database prompt as the alternative workflow.

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 non-read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely new behavioral context beyond those hints: input values are rejected, a human fills them via browser, and no tool ever returns the values. It stops short of describing duplicate handling or the response 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?

Two tight sentences with the core constraint front-loaded; the second sentence earns its place by preventing a common misuse. The first sentence does lightly restate the title, which is the only waste.

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

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

The most important agent-facing fact (names only, values are human-entered and never retrievable) is covered, which is essential for a mutation-like tool with no output schema. However, idempotency_key semantics, duplicate-name behavior, and what a successful call returns or produces are all unaddressed.

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

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

Schema description coverage is 0% and there are three parameters. The description adds meaning only for 'names' (names, not values); 'project_id' and 'idempotency_key' are left completely undocumented in both the schema and the description, so the coverage gap is only partially compensated.

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 (declare the NAMES of environment variables) and sharpens the scope with the uppercase 'NAMES' constraint. It implicitly separates the tool from set_env by emphasizing that values are not accepted, though it never names that sibling 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?

It clearly bounds when this tool applies: only names, never values, and a human supplies the values in a browser. That is strong context, but it does not point to the alternative tool for setting values, leaving the agent to infer that set_env exists.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real consequence context: the name stops being served and the project retains its platform hostname. It does not clarify auth requirements, whether DNS records are removed, or how the idempotency_key behaves, so it is not fully transparent.

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

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

Two short sentences, front-loaded with the action and followed immediately by the observable effect. No filler or repetition.

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

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

For a low-complexity destructive operation with no output schema, the outcome description is useful, but with 0% parameter coverage an agent still lacks guidance on hostname format, project_id source, and idempotency behavior. 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 description coverage is 0% across three parameters, so the description carries the full burden and fails: hostname, project_id, and idempotency_key are never explained (format, source, or semantics). 'The name stops being served' only loosely hints at hostname.

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 ('Detach a domain from the project'), which is unambiguous and clearly the inverse of the sibling attach_domain. It does not name any sibling or alternative explicitly, so it stops short of the top band.

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: the agent can infer this is the tool for removing a domain association, but there is no statement of when to prefer it over delete_project, list_domains/check_domain, or what prerequisites (e.g., domain must be attached) apply.

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

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

Annotations already flag destructive=true and idempotent=true, yet the description adds substantive context beyond them: the name record survives so a required variable becomes 'unset rather than unknown', and a bad deletion holds the next deploy at the secrets gate instead of failing with no explanation. It also states the effect timing (next deploy or restart), which no structured field conveys.

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

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

Front-loaded with the core action and tightly sized for a destructive operation; the consequence sentences earn their place. The second sentence is long and comma-chained, slightly reducing scannability.

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

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

With no output schema and annotations covering the safety profile, the description supplies the deploy/restart timing and failure-mode consequences an agent needs. It omits permission requirements and any parameter guidance, but the operational picture is largely complete.

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

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

Schema description coverage is 0% for three parameters, so the description must compensate — and it does not. It never explains project_id, the expected form of name, or the purpose of idempotency_key, which matters given idempotentHint=true.

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 variable from the project's secret set') and precisely delimits scope by noting the declared name record is retained while the value is removed. That nuance separates it cleanly from set_env, declare_env_names, and list_env_names without naming 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 action and the warning about deleting a needed value, but no alternative is named and no condition for choosing this over set_env or declare_env_names is given. An agent can infer when to call it, but nothing is explicit.

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 destructiveHint=true and idempotentHint=true, and the description meaningfully extends this: runtime resources are irreversibly cleaned up, the project vanishes from the user-space list as soon as the request is accepted (implying async acceptance), and saved passwords/keys plus any workspace database are explicitly preserved. That distinction between what is destroyed and what survives is exactly the context a mutation tool needs.

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

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

Three tight sentences, front-loaded with the core action and then layering destruction scope and preserved resources. The opening sentence merely echoes the title, but the remaining content is dense and 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?

With no output schema, the description does the heavy lifting on lifecycle and side effects, and annotations cover the safety profile. It is nearly complete for a two-parameter mutation, lacking only any word on the idempotency key and permission requirements.

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

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

Schema description coverage is 0% for two parameters, so the description carries the full burden — yet it never mentions project_id or, more importantly, idempotency_key. Given the annotations claim idempotentHint=true, the absence of any explanation of how to supply an idempotency key 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?

States a specific verb and resource ('Delete the project'), which cleanly separates it from the sibling delete_domain, delete_env_name, and delete_service tools by noun alone. An agent can identify the operation without opening the schema.

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

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

The description explains consequences but never says when to reach for this tool versus alternatives, nor states prerequisites (e.g. stopping the project first, required permissions, or that no confirmation is needed). The agent must infer usage entirely 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?

The annotations declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral facts: connections are cut immediately, data is retained for seven days, then irreversibly destroyed. That retention window and irreversibility deadline are exactly the context an agent needs and are not present in the annotations.

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

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

Three short sentences with zero filler: the action first, then the immediate and delayed consequences, then the confirmation requirement. The destructive warning is front-loaded rather than 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?

With no output schema, the description is responsible for the return/behavior picture, and it covers effect timing, data retention, and irreversibility well. It omits what happens to dependent resources or error conditions, which keeps it just short of fully complete for a destructive 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 description coverage is 0% across two parameters, so the description carries the full burden — and it says nothing about service_id or idempotency_key. The retry-safety implication of idempotency_key is only obliquely covered by the idempotentHint annotation, leaving the parameters effectively undocumented.

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

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

The description gives a specific verb and resource ("Delete a service"), which cleanly separates it from siblings like delete_domain, delete_project, and delete_env_name. It doesn't explicitly contrast itself with softer alternatives such as pause_service or stop, but the resource specificity is enough to identify the target of the action.

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

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

It provides one explicit usage constraint — confirm with a human before invoking ("Ask the person first") — which is real, actionable guidance. However, it never states when to delete versus pause_service/stop/resume_service, nor any preconditions such as stopping the service first or required permissions, so routing guidance is only partial.

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 only declare the safety profile (not read-only, not idempotent, not destructive); the description adds genuine behavioral context — the call is state-gated, may simply echo the state instead of acting, and the refusal case tells the agent what must happen first. It never addresses the idempotency_key parameter, though, despite the tool being annotated non-idempotent, so it misses one behavioral dimension.

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

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

The purpose is front-loaded in sentence one, which is good, but roughly half the text is a port/container tangent that is only loosely related to invoking this specific tool. The state semantics are dense and slightly hard to parse, and the port digression crowds out parameter-relevant 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 non-read-only deployment tool with 0% parameter coverage and no output schema, the description covers workflow state thoroughly but leaves the calling contract unexplained: neither input parameter is described, and the non-idempotent behavior implied by the annotations is unaddressed.

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

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

Schema description coverage is 0% and the description says nothing about project_id or idempotency_key. For a tool carrying an idempotency_key parameter, the omission is significant — the description should explain how that key behaves given idempotentHint=false.

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?

"Build the images and hand the project to the platform" gives a concrete verb and resource, and the state discussion (locked / post-complete_upload) implicitly separates it from siblings like restart, stop, and complete_upload. It does not name an explicit alternative, so it stops short of a 5.

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

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

It states precisely when the tool is needed (get_project shows locked, from complete_upload onward), what happens after that point (the project analyses, builds, and launches by itself), and what the tool does when called outside that state (answers with the state or refuses with the prerequisite). That is explicit when-to-use plus when-not behavior.

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, so the description's real value is specifying exactly what is destroyed: the attachment plus the variable when a value exists, or the declaration when it does not. It also explicitly reassures that the tenant's own service is untouched and holds nothing to delete, which meaningfully refines the destructive profile without contradicting the annotations.

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

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

Three tight sentences that front-load the action, and each adds behavioral information. However, the metaphorical phrasing ('stops asking', 'give an alias back') costs precision that would not have taken more space to state directly.

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

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

For a destructive mutation with no output schema, the description covers the crucial branch logic and the no-collateral-damage guarantee, which is enough for an agent to invoke it safely. The remaining hole is parameter meaning (especially idempotency_key), which the annotations cannot supply.

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

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

Schema description coverage is 0% across four parameters, and the description never mentions project_id, offering, alias, or idempotency_key. The words 'alias' and 'value' appear only as narrative, not as parameter meaning; notably the idempotency_key is unexplained despite idempotentHint=false.

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 conveys the effect (returning an alias to the platform and removing what was declared) but never plainly states 'detaches the reference to a tenant-supplied external service,' leaning on metaphor ('give an alias back'). The two-branch explanation of outcomes is specific, yet the core resource is only inferable from the title and the attach_external 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?

There is no guidance on when to call this versus attach_external, list_external, delete_service, or on preconditions such as whether the service must already be declared. The reader learns what happens, not when to choose 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?

Annotations already cover readOnlyHint and openWorldHint, and the description adds substantial context beyond them: the file must be saved at the archive root, the next deploy builds directly from it with no analysis (except a short content check and the build-file write step), and an empty file means fline checks the front page. This is real behavioral depth the annotations do not provide.

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

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

The opening sentence is a fragment, so the purpose is not front-loaded. The text then bundles unrelated material — env_names object formatting, health_path semantics, edit-and-retain rules — into a dense run-on that reads more like scattered notes than a structured 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?

With no output schema, the description should clarify what the call returns, but it only implies retrieval of fline.json and drifts into file-format and deploy-pipeline details. It is informative about the artifact's behavior yet incomplete about the tool's own contract.

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

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

Schema coverage is 0% for the single project_id parameter, and the description never mentions it by name — only 'this project's current plan.' The parameter is self-evident, so the omission is minor, but the description adds no format or scoping detail the schema lacks.

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 is a fragment ('The fline.json for this project's current plan') rather than a verb+resource statement, so it never cleanly says the tool retrieves/returns the config file. The name and title ('get_config' / 'Get fline.json') salvage the intent, and the mention of check_config hints at the sibling relationship, but the description itself is vague about the core action.

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

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

It gives partial guidance — 'Edit it when the project changes, and check the edit with check_config' — which routes validation to a sibling. However, it never states when to call get_config versus refresh_config or the other config-related siblings, 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine value by interpreting return fields (desired vs observed are separate, app_health reflects fline's checks, not_answering means failures for at least two minutes), which is real context beyond annotations. It stops short of describing response shape, timing, or auth needs.

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

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

Two sentences with little padding, but the phrasing is dense and awkward ('arrive separately and mean different things separately') and it is not front-loaded with the tool's purpose. The most important information, what the tool returns, is buried behind jargon.

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 reasonably attempts to explain return semantics, which is the right instinct. However, for a status-retrieval tool it omits the core purpose statement and any project_id guidance, leaving key gaps for an agent deciding how to call 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 0% and the description says nothing about project_id, so the one required parameter carries no documented meaning beyond its self-evident name. The reference to get_project implies project scoping but does not define or constrain the argument.

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 supplies the verb+resource ('Get deployment status'), but the description itself opens with a fragment ('Deployment state:') and never states what the tool returns or does. It jumps straight into field semantics (desired/observed/app_health), so an agent must infer the purpose from the name rather than the prose.

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

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

There is no when-to-use guidance, no conditions distinguishing it from siblings like get_project, get_service, or get_events, and no prerequisites. The trailing '(see get_project)' points to a related read tool but does not frame it as an alternative or explain when to prefer one over the other.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior — chronological ordering, per-entry contents, and the identity of the emitting component. It stops short of disclosing pagination or truncation behavior, which matters for a timeline that can be long.

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, both front-loaded and dense with actionable content. The ordering and field list come first, the sibling contrast lands last as a routing cue. Nothing is padding.

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 takes on the job of describing the return shape and does it well. The remaining gap is the undocumented limit parameter and its truncation semantics, which an agent needs in order to trust the timeline it gets back.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden — but it only implies project_id and says nothing about limit: no default, no maximum, no statement of whether a truncated timeline is silently cut or flagged. The one parameter an agent actually has to reason about is left entirely undocumented.

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

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

The description states a specific verb and resource — the project's state timeline, ordered oldest first — and enumerates exactly what each entry carries (state transition, reason, originating platform component, request id). It explicitly distinguishes itself from the sibling get_project, which 'shows the current state and nothing about how it got there.' An agent can pick between the two 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 names the alternative (get_project) and the exact diagnostic condition that selects this tool: telling a slow analysis apart from one that failed and was retried. That is a concrete when-to-use rule plus an explicit when-not-to-use boundary, not an implied one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this by stating it will not start a new build or deploy. It also discloses the shape of the returned history, which matters since there is no output schema. It omits pagination/ordering and retention behavior for the history.

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

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

Two tight sentences with no filler; the resource and returned fields come first, followed by the read-only framing. The enumerated field list is dense but earns its place given the absence of an output schema.

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

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

Without an output schema, enumerating the returned fields is the right call and largely closes that gap, and the read-only intent is explicit. The remaining hole is the limit parameter's semantics and pagination, which neither the schema nor the description covers.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it says nothing about project_id or the limit parameter. It only names build_id/hash/digest, which are outputs, not inputs. An agent gets no guidance on bounding or filtering the history.

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

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

States the specific resource ('history of images the builder produced for the project') and enumerates the content returned (build_id, build state, plan version, source hash, service digests). The closing clause distinguishes it from build/deploy actions, so an agent can tell it is a read-only inspection tool rather than a trigger.

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

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

Clearly frames the use case: checking which version is actually built, explicitly 'without starting a new build or deploy.' It gives a condition for use and an implied exclusion, though it does not name a specific sibling tool as the alternative route (e.g. get_deploy_status).

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the description is free to add the non-obvious traits: build logs persist indefinitely while runtime logs are a bounded tail held by the node with no history and no search. That retention/searchability disclosure is exactly the kind of context an agent cannot infer from the schema. It stops short of mentioning pagination or ordering.

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

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

Three dense sentences with no filler; the kind distinction is front-loaded and the service caveat follows. Every clause carries semantics. Slightly harder to scan than a bulleted kind/parameter layout would be, but there is no wasted text.

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

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

For a read-only tool with no output schema, no enums, and 0% schema coverage, the description covers behavior and kind semantics well but leaves `lines` and `project_id` unexplained, and says nothing about what a returned log record looks like. Adequate but with clear gaps given the schema contributes no documentation.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains `kind` and `service` well, including the effect of omitting `service` on multi-service projects. However, `lines` (the tail size) and the required `project_id` are never explained, leaving two of four parameters undocumented anywhere.

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 tool reads logs for a project, and the description goes further by defining the two `kind` values precisely (build output vs. running-container tail). It clearly distinguishes itself from data-listing siblings by naming get_project_detail as the source of service names. The opening 'Logs.' is terse rather than a stated verb, which keeps it 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 explicit guidance for choosing between kind=build and kind=runtime, including the retention tradeoff ('answerable long after the build' vs. 'no history and no search'). It also states the condition that makes `service` worth passing. It does not, however, address when to prefer this tool over any other sibling for log-like information.

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 only declare readOnlyHint and openWorldHint, leaving the substantive behavior to the description, and the description delivers: it defines each app_health status (answering, not_answering, checking, paused), the two-minute failure threshold, and the cause semantics of 'problem'/'ai_text'. It stops short of describing pagination, caching, or what happens for a project that hasn't been deployed, but the added context is well beyond the annotations.

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

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

The payload sentence is front-loaded and information-dense, but the app_health passage sprawls into a long run-on sentence with parenthetical asides and typos ('fline', 'fline is putting a new version online'), making it harder to scan than it needs to be.

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 must explain the returned fields, and it does so thoroughly for status/app_health, the most operationally important part of the response. It leaves the required project_id undefined and says nothing about the shape of the onboarding/questions/secrets sections, so it is strong but not fully complete.

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

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

Schema description coverage is 0% and the description never mentions project_id or its format (slug vs UUID), so the single parameter carries no semantics anywhere. The narrative is entirely about return values, so the description does not compensate for the coverage 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+resource ('The project's full state') and enumerates what that state comprises: onboarding stage, runtime state, open questions, missing secrets, credential warnings, app_health. That is concrete and distinguishable in substance, but it never acknowledges the sibling get_project_detail, which an agent could easily confuse with this 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?

There is an implicit routing cue for the failure case ('read get_logs kind=runtime and fix the app'), which is genuinely useful guidance about what to do next. However, there is no explicit statement of when to call this versus the many sibling state/config tools (get_project_detail, get_config, get_usage), so selection guidance is only partial.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description nevertheless adds a non-obvious behavioral trait: the platform half is best-effort, a never-deployed project has no record there, and the response degrades to get_project rather than failing. That is genuine disclosure beyond the annotations, though it says nothing about auth or rate 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?

Three front-loaded sentences ordered as payload, usage trigger, then caveat, with no filler. The long middle enumeration of return fields is dense but every item earns its place for a diagnostic tool lacking an output schema.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly, while also stating the degradation path and the usage trigger. An agent has everything needed to select and call this read-only diagnostic tool correctly.

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

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

Schema description coverage is 0% and the description never defines project_id or its format, though the repeated references to 'the project' and the get_project superset relationship make the parameter's intent self-evident. With a single obvious identifier it adequately compensates but adds no real semantic value.

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 precise relationship to a sibling tool: 'Everything get_project returns, plus what the platform observes,' then enumerates the added payload (container state, health, restart count, image digest, node/tier, ingress hostnames, disk quota, secret set version, last failure class). An agent can tell exactly what this tool yields and how it differs from get_project without opening the schema.

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

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

It gives an explicit trigger ('Use this when a deploy has failed or a service is not answering and get_deploy_status has told you only that'), naming the sibling that precedes it in the workflow. The condition that selects this tool over get_project, get_deploy_status, get_logs, and get_events is stated rather than 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?

Adds substantial behavior beyond the annotations: the link is single-use and expires at expires_at, a new link cancels the previous unused one, sign-in to fline is required, and a waiting project auto-continues while an online project needs a restart. Annotations only cover readOnly/idempotent hints, so this extra context is genuinely valuable. It stops short of 5 because it says nothing about required permissions or rate 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?

Front-loads the purpose, then layers usage, behavior, and downstream effects without redundancy. It reads as somewhat dense prose rather than crisp bullets, but each sentence carries distinct information, so it is efficient overall.

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 no-output-schema action tool this covers the lifecycle well (single use, expiry, cancellation, restart semantics), which is the important part. However, the two input parameters remain undocumented at 0% schema coverage, leaving a gap that an agent could trip on when supplying idempotency_key.

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

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

Schema description coverage is 0% and there are two parameters (project_id, idempotency_key), yet the description never mentions either by name or explains their meaning. The phrase 'the project needs' only hints at project scoping. With no schema descriptions to lean on, the description should compensate and does not, especially for idempotency_key.

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

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

States a specific verb and resource: 'Issue a link to the form where the person types the passwords and keys the project needs.' An agent can tell this creates a secrets-entry URL rather than setting env vars. It does not explicitly name siblings like set_env or declare_env_names, 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?

Gives strong operational guidance ('Give the url exactly as returned... Do not open it, do not follow it'), which is really how-to-use-the-result advice. But it never states when to choose this tool versus alternatives such as set_env or declare_env_names, nor any prerequisites, so usage routing 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the meaning of the returned state, why a non-active service carries a reason, and that no credentials appear in the result.

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

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

Three tight sentences, front-loaded with the return shape before the polling guidance. The em-dash interruption is slightly awkward but no sentence is wasted.

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

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

With no output schema, the description correctly compensates by describing the return (state + non-active reason) and the lifecycle semantics. Only the parameter's origin/format remains undocumented.

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

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

The single parameter service_id has 0% schema description coverage, so the description carries the burden. 'One data service by id' conveys that the parameter is the service identifier, but adds no format, source, or lookup guidance (e.g., where to get the id from).

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 ('One data service by id') and immediately scopes what is returned (its state, plus the failure reason when not active). This clearly separates it from list_services and the other get_* 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?

Names the trigger explicitly ('Poll this after create_service'), explains the expected lifecycle ('provisioning until its certificate is issued and verified'), and says what to do when it stalls. It also preempts a likely follow-up question by stating no credentials are returned by any tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds the useful notion that links are re-issuable and that the link is bound to a project, but it never says whether issuing a new link invalidates the previous one, how long the link lives, or whether it is single-use — the key behaviors for an upload-link 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?

Two sentences, no filler, with the core action front-loaded and the conditions following. The second sentence is a long three-item list, but each clause carries distinct routing information, 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 should describe what comes back (a URL, its form, its validity window), and it does not. Combined with 0% schema coverage on the idempotency_key, an agent has enough to pick the tool but not enough to call it correctly in edge cases.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and it largely does not. 'For an existing project' loosely hints at project_id, but the idempotency_key parameter — the only non-obvious one — is never mentioned, explained, or given a format anywhere.

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 ('Issue a new archive upload link') and scopes it to an existing project, so an agent knows exactly what is produced. It also implicitly distinguishes itself from the sibling create_project by referencing that tool's link as the thing being replaced.

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 three explicit triggers for use: an expired link from create_project, a re-upload of the archive, or updating an already deployed project with new code. That is clear context, but there is no explicit when-not-to-use or a direct directive such as 'use create_project for first-time uploads'.

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 only declare readOnlyHint and openWorldHint=false, and the description adds substantial context beyond that: usage is quantities not charges, ceilings are enforced not billed, the net figure counts at container interfaces, the memory peak is sampled every 30s (not a true max), coverage indicates window reach, and null is not zero. This is exactly the kind of behavioral disclosure 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?

It is long, but front-loads the core purpose and the most important disclaimers first (quantities vs charges, read notes before restating figures). The sentences are dense yet each addresses a real ambiguity an agent would otherwise get wrong; some could still be tightened.

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 explaining return values and does so: coverage semantics, null-vs-zero, the notes caveats, and the sampled memory peak. Combined with the window/per_service defaults, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 0%, so the description must compensate and mostly does: it enumerates the window values (1h, 6h, 24h, 7d, 30d) with a 24h default, and gives per_service's default of false. project_id is left unexplained, but its meaning is self-evident from the tool's subject.

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

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

The opening sentence names a specific verb+resource: 'What this project actually consumed: CPU, memory, disk, files and network over a window.' This clearly separates it from config/logs/events siblings by subject matter. It does not explicitly name an alternative tool, so it falls just short of the highest tier.

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

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

It provides conditional action guidance ('If the answer is that the project has outgrown its class, say so plainly') and states the window/per_service defaults, implying when the tool is relevant. However, it never says when to prefer this over sibling tools such as get_config, get_logs, or get_events, 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value by disclosing exactly what the response contains (per-domain ownership state, TXT record, last-checked timestamp, last objection, platform hostname), which matters because there is no output schema.

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

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

Two sentences, information-dense but front-loaded with the return contents and closing with the actionable relationship to attach_domain. No filler, though the first sentence is a long pile-up of clauses.

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 so thoroughly. For a single-parameter read tool the only remaining gap is pagination/ordering behavior, which 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 0% and project_id is undocumented in the schema, but the phrase 'the project's custom domains' conveys that the parameter scopes the list to one project. It adds modest meaning but never names or explains project_id directly, so it only partly compensates for the coverage 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 the resource (the project's custom domains) and enumerates what is returned for each (ownership-check state, TXT record, last checked time, failure reason, platform hostname). It is specific and operational, though it never frames the verb 'list' and does not explicitly differentiate from check_domain, only from attach_domain.

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 usage context: attach_domain returns the record only once, and this tool is how you verify whether attachment took. That tells the agent when to reach for it, but there is no explicit when-not or named alternative such as check_domain.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds substantial behavioral context: no secret value is ever returned, a shown value implies set_env with secret=false, non-declared secrets are hand-added, and a required-but-unset name is what holds a project in awaiting_secrets. That is real value beyond 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?

The returned-fields list is front-loaded and every sentence carries information, though the em-dash clause about secret vs. declared variables is dense and takes a second pass to parse. No filler or redundancy.

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

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

No output schema exists, and the description fully enumerates what the call returns, including the secret-suppression rule and the awaiting_secrets semantics. For a one-parameter read tool with annotations covering safety, nothing needed to call it correctly is missing.

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

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

There is a single required project_id with 0% schema description coverage, and the description never explains its format or scope. The parameter is largely self-evident, but with the schema silent the description could have compensated and does not.

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 and resource ('environment variables BY NAME') and immediately enumerates the returned fields (set status, declared status, last-written time, value for non-secrets). It also contrasts itself with sibling tools set_env and get_secrets_link, so an agent can place it without opening the schema.

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

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

It routes the agent for the secret case ('see get_secrets_link') and explains the relationship to set_env, but it never states when to prefer this over sibling list/declare tools such as declare_env_names or delete_env_name. Context is clear, exclusions are only implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description needn't reiterate safety. It adds valuable behavioral context: distinguishes completed vs. pending attachments, names the 'host' field, mentions 'get_secrets_link' for pending variables, and explicitly states no connection URL is returned. This is useful transparency beyond annotations, though it doesn't mention rate limits or pagination.

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

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

Three sentences with zero waste. It front-loads the purpose ('backing services...'), then details output differences (completed vs. pending), then clarifies a limitation (no URL). Every sentence 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?

The tool is simple (one parameter, read-only, no output schema), and the description covers output nuances. However, it omits the parameter's meaning and doesn't clarify how it differs from list_services or attach_external, which are present siblings. For a simple list tool, this is minimally adequate but leaves gaps an agent would need to infer.

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

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

Schema coverage is 0% and there's one required parameter (project_id) that isn't described in either schema or description. The description adds no information about the parameter's format, constraints, or whether it's the project ID or tenant ID. Baseline 3 for one parameter with no added semantics but not misleading.

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+resource: 'backing services this project's tenant supplies themselves.' This is clear, though it doesn't explicitly say 'list' or mention the project_id parameter, and sibling differentiation is only partial (distinguishing external vs. internal services is implied by 'tenant supplies themselves' but not contrasted with list_services or attach_external).

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 explicit guidance on when to use this tool versus alternatives like list_services, attach_external, or get_project_detail. The description implies usage by describing the output format, but doesn't state when-not-to-use or name any alternatives.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral detail beyond that: app_health only appears 'once online', i.e. a conditionally populated field. It does not cover ordering, pagination, or result size.

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 with no redundant sentences, and the key scoping information ('the tenant's projects') is front-loaded. The mid-sentence 'and, once online,' interjection is slightly awkward but does not obscure meaning.

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

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

With no output schema, the description carries the burden of describing returns, and it does name the primary fields (state, address, app_health) plus the conditional availability rule. For a zero-parameter, read-only tenant listing, that is close to sufficient; only pagination/ordering behavior is unstated.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify; the baseline for a 0-param tool is 4. No parameter information is missing or misleading.

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 specific resource (the tenant's projects) and enumerates the fields returned (state, address, app_health), so an agent knows this is a bulk listing rather than a single-record fetch. It cross-references the get_project sibling, which helps distinguish it, though the phrasing is a noun fragment without an explicit verb.

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 over get_project or get_project_detail; the only hint is 'see get_project' for fuller detail on app_health, which is a weak cross-reference rather than usage guidance. No exclusions, prerequisites, or selection criteria 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?

The readOnlyHint annotation already covers the safety profile, so the description's added value is the credentials caveat ('none is returned by any tool'), which stops an agent from hunting for secrets via this call. It also enumerates the returned fields, useful given no output schema, though it doesn't say whether stopped or deleted services are included.

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, with the resource scope front-loaded and the credentials caveat appended as a caution. Nothing could be cut without losing signal.

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

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

With no output schema, the description must convey return shape, and it does list the fields. Minor gaps remain — no mention of filtering, ordering, or whether inactive services appear — but for a zero-argument list tool this is close to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The listing of return fields is a bonus rather than parameter guidance.

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 (the workspace's services) and enumerates exactly which attributes come back (engine, version, state, hostname, size class), which is more precise than the title alone. It doesn't explicitly contrast with get_service, but the list-vs-single distinction is carried by the name and the plural scope.

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

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

There is no statement of when to call this versus get_service, list_projects, or list_versions, and no preconditions or exclusions are given. Usage has to be inferred entirely 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: ordering (newest first), the exact fields returned, and an explicit exclusion (the specification is not returned). It does not mention pagination or result-size behavior, which would have earned 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 dense sentences with no filler. The core purpose and ordering come first, then the returned fields, then the exclusion and the pointer to get_config — properly 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?

There is no output schema, so the description correctly carries the burden of explaining return values, which it does by enumerating the four fields. The remaining gap is the undocumented 'limit' parameter, which leaves result-set control unspecified.

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

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

Schema description coverage is 0% and neither parameter is documented in the description. 'the project's' only loosely implies project_id, and the 'limit' parameter is entirely unexplained — no default, no max, no effect on results. With zero schema coverage the description was required to compensate and does not.

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

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

States a specific verb and resource ('List the project's deployed versions') with scope and ordering ('newest first'), and explicitly differentiates itself from get_config by declaring that the specification itself is not included. An agent can distinguish it from siblings like get_config or get_project_detail without opening the schema.

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

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

Routes the agent clearly: it names get_config for version contents and states the returned state_version is 'to pass to rollback', which implies the intended workflow. It lacks explicit when-not guidance against other read tools (get_events, get_project_detail), so it falls just 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?

Adds real behavioral context beyond the annotations: connections stop, running-instance cost stops, and the volume and certificate are retained. Annotations carry the safety/idempotency profile (destructiveHint=true, idempotentHint=true), and the description supplies the state-retention and cost consequences. It does not, however, address the mild tension between 'reversible' and destructiveHint=true, nor any auth requirements.

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

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

Three short clauses, front-loaded with the action, then behavior, then the alternative comparison. No filler; each sentence adds routing or behavioral information.

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

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

For a 2-parameter mutation tool with no output schema, the description is nearly complete on behavior and sibling routing. The one gap is parameter documentation, which is left entirely to an undocumented 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?

Two parameters with 0% schema description coverage, and the description says nothing about either service_id or idempotency_key. An agent gets no hint that an idempotency key exists or what it accomplishes, so the description fails to compensate for the schema 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 ('Pause a data service') and immediately scopes it against siblings: resume_service is 'the exact reverse' and delete_service is the non-reversible alternative. An agent can distinguish it from delete_service, stop, and resume_service without opening any 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?

Explicitly frames the choice: this is 'the reversible way to put a service down,' while delete_service is not and 'starts a seven-day clock on the data.' Both the when-to-use and the when-not-to-use (with the selecting condition) 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?

Adds substantial behavior beyond the annotations: the call is asynchronous ('Accepted immediately, not done'), it instructs the agent to poll get_project until it leaves the analyzing state, then call get_config, and it discloses a cost ('uses one of the account's fresh analyses for the month'). The annotation set (non-readOnly, non-idempotent, non-destructive) does not carry any of this asynchronous or quota information.

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, then usage, then the asynchronous follow-up, which is a sensible ordering. Three sentences with little waste, though the closing clause ('while editing the file yourself is free and you know what changed') is conversational and slightly over-long.

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, quota-consuming, asynchronous tool with no output schema, the description supplies the critical lifecycle (accepted → poll → fetch) and the cost. The remaining gap is that idempotency_key is undocumented, leaving the agent without guidance on retry behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does not. project_id is only implied through 'the project's stack changed', and idempotency_key is never mentioned at all — notable given the annotations declare idempotentHint=false, which makes this parameter's semantics (retry safety) important and undocumented.

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

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

States a specific verb ('Re-run the analysis') and its object (the archive's fline.json, which it overwrites), making the exact effect clear. It is readily distinguishable from read-oriented siblings like get_config, check_config, and get_project.

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

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

Gives an explicit triggering condition ('a configuration that has gone stale because the project's stack changed — a different package manager, a new lockfile') and an explicit alternative ('editing the file yourself is free and you know what changed'). This is a rare case of stating both when to use and when not to.

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 the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely non-obvious behavior: it is the ONLY way a secret entered after the last deploy reaches running containers, via re-pinning the secret set version. This is exactly the kind of hidden consequence the agent cannot infer from structured fields.

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

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

Front-loaded with the action, then the critical secret-behavior aside. 'This is the restart' mildly restates the name/title, and the em-dash clause is long, but nearly every sentence carries useful 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?

No output schema, so return values need not be described, and annotations cover safety. However, with 0% schema coverage the idempotency_key parameter is left unexplained, and the description offers no guidance on its use for a tool marked non-idempotent — a meaningful omission.

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

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

Schema coverage is 0%, so the description must carry the parameters, yet it never mentions idempotency_key and only implies project_id via 'the project's current version.' One of two parameters is entirely undocumented anywhere, which is a real gap for a mutating call.

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: 'Re-apply the project's current version: the same images, deployed again.' The phrase 'the same images, deployed again' implicitly separates it from deploy (which would push new images), though no sibling is named explicitly. Clear purpose with only light 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?

Gives an explicit trigger condition: 'Call it after a human has filled in the form behind get_secrets_link on a project that is already running,' naming a sibling tool and a precondition. It stops short of stating when NOT to use it (e.g., deploy vs restart), so it's strong but not fully routing.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds genuine behavioral value beyond that: the data and hostname are preserved unchanged, which tells an agent this is a non-destructive state transition rather than a recreate. It omits idempotency_key behavior and any error/state preconditions.

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 state-preservation qualifier is attached where it is relevant.

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 mutation's outcome is well described and annotations carry the safety profile, and no output schema exists to explain. Still, with 0% parameter coverage the description leaves the idempotency_key unexplained and offers no precondition or failure-mode context for a state-changing tool.

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

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

Schema description coverage is 0% and the description mentions no parameters at all. service_id is inferable from 'a data service', but idempotency_key — a non-obvious parameter whose semantics matter for retries — is completely undocumented in both the description and 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 (start again) and resource (paused data service), and the phrase 'paused' implicitly distinguishes it from the neighboring restart/stop/pause_service tools. It stops short of naming an alternative sibling explicitly, so it is clear but not fully differentiated.

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 a paused data service again' implies the trigger condition (the service must be paused), which is useful context. However, it never states when to choose resume_service over restart or deploy, nor what happens if the service is not paused.

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 past the annotations, which only say non-read-only/non-destructive/non-idempotent. It discloses two non-obvious behaviors: the version number advances rather than reverting (consistent with idempotentHint=false), and secrets are re-pinned from current values rather than restored. It also explains failure semantics ('refused rather than deploying something similar' with a reason), which 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?

Purpose is front-loaded, then the two caveats are clearly enumerated ('First... Second...') plus the validation-refusal clause. Slightly wordy framing ('Two things surprise people and you must not report either one wrongly'), but every sentence carries real 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 mutation tool with no output schema, the description covers the surprising semantics and the failure mode thoroughly. The only gap is that project_id and idempotency_key are undocumented anywhere, which an agent would need to infer.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning. It does explain that 'to' takes a state_version from list_versions, but leaves the mapping from the parameter name 'to' implicit and says nothing about project_id or idempotency_key. Partial compensation for a 3-parameter, zero-coverage 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+resource ('Redeploy an earlier version of the project') and pins the identifier source to 'state_version from list_versions', which separates it cleanly from siblings like deploy, restart, and list_versions. An agent can identify the operation without opening the schema.

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

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

Gives clear context for use (rolling back to a prior state identified via list_versions) and a refusal condition (stored version fails validation). It lacks an explicit 'prefer X instead when...' contrast against siblings such as deploy, but the triggering scenario is unambiguous.

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 and idempotentHint, and the description adds substantial context beyond them: plaintext values are visible in list_env_names, the console, and every service environment, while secret values are unreadable by any tool. It also discloses the four refusal rules, the platform-managed-database trap, and that changes apply on next deploy/restart. The only gap is it never mentions idempotency behavior even though idempotentHint=true is asserted.

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 required-parameter rule and the plaintext/secret split, and nearly every sentence carries a rule or remedy worth keeping. It is nonetheless long, with a few cryptic or redundant lines (e.g. 'A plaintext value survives the next analysis; a secret still does not') that could be tightened.

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, 5-parameter, no-output-schema tool, the description covers refusal modes, side effects, visibility, and alternatives comprehensively. Missing only the `idempotency_key` parameter semantics and any statement about what the call returns or signals on success.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it explains why `secret` is required, what each mode means, naming rules for `name`, and the empty-`value` refusal. However, `idempotency_key` is never mentioned, and `project_id` is left implicit, so it does not fully compensate for the 0% 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 opening sentence gives an exact verb+resource ('Set one environment variable for the project') and the body immediately distinguishes the two write modes, making this clearly separable from siblings like declare_env_names, delete_env_name, and get_secrets_link.

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

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

Explicitly states when to use secret=true vs secret=false, when to use get_secrets_link instead ('for a password or key the person has not given you'), and enumerates four refusal conditions each paired with a remedy. Nothing is left to inference.

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

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

The annotations declare destructiveHint=true and readOnlyHint=false, implying a destructive write operation. The description states that the platform has no stop and that this tool refuses, meaning no destructive action occurs. That directly contradicts the destructiveHint annotation.

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

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

Four short sentences with the critical warning front-loaded: stop project, not implemented, refuses, use delete_project. The additional delete_domain distinction is also useful and 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 deliberately non-functional tool, the description is sufficient to prevent misuse and redirect to alternatives. However, it omits any explanation of the required parameters and leaves the destructiveHint contradiction unreconciled, so it is not fully complete.

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

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

Schema description coverage is 0%, and the description never explains project_id or idempotency_key. For a two-parameter tool with no schema documentation, the description fails to compensate for the coverage 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?

It states a specific verb and resource (stop the project) and immediately clarifies that the tool is NOT IMPLEMENTED and refuses. It also names the correct siblings to use instead, so an agent can distinguish it from delete_project and delete_domain.

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

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

The description explicitly tells the agent not to use this tool, and gives alternatives: delete_project for taking an application out of service, and delete_domain for removing only a web address. This is clear when-not-to-use and when-to-use-an-alternative 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 establish that this is a write operation that is idempotent and non-destructive. The description adds a genuine behavioral note beyond the annotations: the submitted content is treated as a third-party claim and cannot affect platform rules. However, it omits how the declaration is validated, whether it can be replaced or appended, and what errors look like.

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

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

Two short sentences with no filler, and the semantic constraint on the submitted content is front-loaded after the core action. Nothing is padded, though the brevity is partly under-specification rather than discipline.

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 write tool with a nested object parameter, 0% schema coverage, and no output schema, the description is too thin. It does not explain the declaration's expected structure, the response on success, or how idempotency is honored, leaving key call-shaping details to guesswork.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden. It gives a hint that the 'declaration' payload is semantically inert (a third-party claim) but says nothing about the shape of that nested object, the meaning of project_id, or when idempotency_key should be supplied.

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 verb and resource ('Supply the project description'), but the term 'declaration' is never defined and the wording is close to a restatement of the title 'Describe the project'. An agent cannot infer what a declaration actually contains or how it differs from other project-mutating siblings like create_project or set_env.

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 call this tool, what prerequisites exist, or how it relates to alternatives such as answer_questions or create_project. The only implied usage is that a project description is needed, which the agent must guess from the title.

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