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, and the description reinforces this by promising no deployment and no cost, plus describing the response shape (ok or per-part refusal reasons). It adds real behavioral context beyond the annotations without contradicting them.

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

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

The core purpose is correctly front-loaded in the first sentence, but the rest is a single dense run-on covering Kafka examples and value rules that read more like a config reference than tool guidance. Most content earns its place given zero schema coverage, yet the packing 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 2-parameter, nested-config tool with no output schema, the description supplies the return contract ('ok, or the reason each part was refused') and the key config semantics. An agent has enough to call it correctly, though project_id's provenance is left implicit.

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% on a nested config object, so the description must carry the load — and it does, explaining that there is no port field, the rules for env_names objects with literal values, credential handling, and the managed-database scope alternative. It covers the tricky fields well but is not an exhaustive field reference.

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: check a fline.json against the last uploaded archive, explicitly without deploying or cost. This is clearly a validation action, distinguishable in spirit from deploy/refresh_config, though no sibling is named to anchor the contrast.

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 workflow: check, read refusals, edit and re-check until ok, then save the file. It implies 'use this before committing/saving' but never names a sibling alternative (e.g. submit_declaration or refresh_config) or an exclusion, so it stops short of the explicit routing a 5 requires.

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 only state the generic mutation profile (readOnlyHint=false, destructiveHint=false), while the description adds real behavior: no password/key is ever returned by any tool, secrets surface on the dashboard Services/Storage pages, the service starts as `provisioning` and becomes `active`, and engine/version/size_class default to platform choices. This goes well beyond what the annotations disclose and contradicts nothing.

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 create action and engine enumeration, which is good, but it is a single dense paragraph with digressions (the Redis-fork licensing aside, repeated 'what to ask for wherever a project wants' phrasing) that could be tightened. Most content is purposeful, but it is longer 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?

For a no-output-schema, mutation tool with five parameters, it covers creation semantics, defaults, lifecycle states, secret handling and the project-vs-workspace distinction thoroughly. The main omission is any mention of idempotency_key behavior, which matters because the annotation declares the call non-idempotent.

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. It explains engine values, the version default and the size_class default, which covers three of five parameters, but says nothing about `name` semantics or the `idempotency_key` parameter (notable given idempotentHint=false). Partial compensation only.

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

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

Opens with a specific verb+resource ('Create a data service for this workspace') and enumerates the three engine choices with plain-language meaning for each, so an agent knows exactly what it produces and which flavor to pick. It is cleanly distinguishable from siblings like get_service, list_services and delete_service.

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

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

Gives explicit when-to-use (postgres/valkey/s3 selection rationale), explicit when-not-to-use ('NEVER write a postgres, redis, valkey, minio or s3 service into a compose file or a plan'), and names the alternative path (a plan variable marked scope 'managed' is wired at deploy time). It also points to the add_a_database prompt and clarifies the bucket exception.

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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine context beyond that: the cleanup is irreversible, it stops runtime resources, and the project vanishes from the user-space list once the request is accepted. It stops short of saying what happens to attached domains/services or whether authorization scoping applies.

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, front-loaded with the action and followed immediately by the irreversible consequence. Every clause carries information; 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?

For a destructive tool with no output schema, the annotations cover safety and the description covers irreversibility and the post-condition. The remaining gap is parameter meaning (especially idempotency_key) and side effects on dependent resources.

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, and the description never mentions project_id or idempotency_key. The idempotency_key in particular is non-obvious and its relationship to the idempotentHint annotation is left unexplained, 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 (Delete) and resource (project), and adds scope detail about runtime resources. It does not explicitly contrast with the sibling deletion tools (delete_service, delete_domain, delete_env_name), but the resource name is unambiguous enough to select correctly.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., must the project be stopped first), and no warning about confirming with the user before an irreversible operation. The agent must infer everything.

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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by explaining the downstream effect (a saved fline.json is built from directly with no analysis, though a content check and build-file-writing step still run) and by warning that env_names entries may be objects carrying a value for prebuilt images. That is meaningful behavioral context beyond the structured fields, though the return format itself is left implicit.

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 text is not front-loaded on what the tool returns; instead it spends most of its length on deploy behavior, edit-time advice, and env_names semantics that belong to deploy/check_config concerns. Those are useful facts but they are not organized around this tool's job, making it read as unfocused for a trivial single-parameter getter.

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 readOnly annotations, the description should at least characterize the returned config, and it partially does via the env_names object/value note. It still omits the overall shape of fline.json, when the config would be empty or absent, and how project_id relates to the returned document, so an agent has partial but not full grounding.

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 one required parameter, project_id, with 0% schema description coverage, so the description is expected to compensate for the gap. It never mentions project_id, its format, or how it is obtained (e.g., from get_project or list_projects), leaving the only input documented solely by its name.

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 noun phrase 'The fline.json for this project's current plan' plus the title 'Get fline.json' make the resource and operation identifiable, and the mention of check_config distinguishes it from the sibling that validates edits. However, the purpose is buried under deploy-workflow commentary, so an agent gets the target only after parsing tangents rather than a crisp verb+resource statement.

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?

'Edit it when the project changes, and check the edit with check_config' implies the retrieve-then-edit-then-validate workflow and names a concrete alternative for checking. It never states when to call get_config itself (e.g., before editing, or to seed a deploy) or what to do if no config exists yet.

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 a faint behavioral note that 'desired and observed arrive separately', but the phrasing is ambiguous and never clarifies what either value means or how an agent should interpret a divergence.

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

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

It is short, but the one sentence is convoluted and self-repeating ('separately... separately'), so it does not earn its place. Nothing is front-loaded because no actionable statement is made at all.

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 full responsibility for explaining the return value, and it only vaguely gestures at desired/observed fields without defining them or describing the failure modes. For a read tool whose whole value is interpreting deployment state, this is inadequate.

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 single required parameter (project_id) is undocumented in both schema and description. Unlike the zero-parameter baseline, this tool has a parameter that the description entirely ignores, leaving its format and expected value 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?

The description never states a verb or the resource being acted on; it reads as a cryptic note about deployment state fields rather than 'get deployment status'. It hints at a data model (desired vs observed) but an agent cannot confidently tell what this tool returns or how it differs from siblings like get_service, list_versions, or get_events.

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 prerequisites, and no mention of any alternative tool. With 30+ siblings covering deployment-adjacent concerns (get_service, list_versions, get_events, get_logs), the complete absence of routing guidance is a serious gap.

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

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

Annotations already 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 already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful context the annotations do not carry: the specific state components returned, including open questions and credential warnings, which tells the agent this is an aggregated status read rather than a raw config fetch.

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 that enumerates return contents with zero filler. Every clause adds information.

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

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

With no output schema, the description usefully carries the return-value burden by listing what state is included. But it leaves two gaps an agent needs filled: how this differs from get_project_detail and where project_id comes from.

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

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

Schema description coverage is 0%, so the schema provides only the name and string type for project_id. The description does not compensate at all — no format, source, or acquisition guidance for the ID. It is partially rescued by the parameter being a self-evident required identifier.

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 resource (the project) and enumerates exactly what state is returned: onboarding stage, runtime state, open questions, missing secrets, credential warnings. However, it does not differentiate from the very similarly named sibling get_project_detail, leaving a real risk of tool misselection.

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 prerequisites, and no mention of alternatives such as get_project_detail, get_config, or check_config. The agent must infer selection purely from the enumerated return contents.

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; the description supplies the material behavioral facts: figures are quantities not charges, network traffic is measured at container interfaces and overstates egress, memory peak is a 30-second sample not a true max, and null vs zero semantics. It also states the tool cannot mutate class and warns that no other tool or dashboard screen can — highly relevant for avoiding a false remediation path.

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

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

The core purpose is front-loaded and every clause carries real information (sampling caveats, null semantics, parameter defaults). It is on the long side for a three-parameter read tool and the all-caps class-immutability warning is repeated for emphasis, but little of the text is filler.

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

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

With no output schema and annotations that say nothing about returned data, the description carries the full burden and does so by explaining what each notable field (`notes`, `coverage`, null figures) means and how to interpret the numbers. An agent could call and correctly report this tool without further 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 coverage is 0%, so the description must compensate and largely does: it enumerates the allowed `window` values (1h, 6h, 24h, 7d, 30d) and its 24h default, plus the `per_service` default of false. `project_id` is only implied by 'this project' rather than explained, which keeps it from a 5.

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

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

First sentence states precisely what is returned — CPU, memory, disk, files and network consumption for a project over a window — with a specific scope qualifier ('what this project actually consumed'). This clearly separates it from siblings like get_project_detail, get_logs or get_events, which serve different purposes.

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 concrete operating context: read `notes` before restating figures, `coverage` tells you how complete the window is, a null is not a zero, and it prescribes what to tell a user when a project has outgrown its class. It lacks an explicit 'use this instead of X' comparison to sibling tools, so it stops short of a 5.

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

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

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results include state and address, which is genuinely useful since there is no output schema, but it says nothing about pagination, result limits, ordering, or whether inactive projects 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?

A single compact sentence with no filler, and the resource is front-loaded. It loses a point only because the fragment lacks a verb and reads more like a label than an instruction.

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

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

For a zero-parameter read-only list tool with annotations covering safety, the description is nearly sufficient, and it helpfully names returned fields in the absence of an output schema. It is still thin on result-set behavior (pagination, ordering, volume), which matters for a tenant-wide list.

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 per the baseline this dimension is a 4. The description has no parameters to explain and correctly introduces none.

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

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

The phrase 'The tenant's projects with their state and address' identifies the resource (tenant-wide projects) and hints at returned fields, but it is a noun fragment with no verb and does not distinguish itself from siblings like get_project, get_project_detail, or list_services. An agent can infer it lists projects, but the scope distinction (all projects vs. one) is left implicit.

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

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

No guidance on when to use this versus get_project, get_project_detail, or the other list_* tools. There are no prerequisites, exclusions, or alternative-routing statements anywhere in the text.

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?

It discloses behavior the annotations can't: it's asynchronous ('Accepted immediately, not done'), requires polling ('poll get_project until it leaves analyzing'), and carries a cost ('This costs an analysis'). It also warns it ignores the existing file, which is the meaningful mutation detail beyond readOnlyHint=false.

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, front-loaded with the action and effect, then trigger, then follow-up, then the cheaper-alternative warning. Sentences each earn their place; the only mild cost is the parenthetical about the stack, which 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 an async mutation with no output schema, it covers the call-return distinction, the polling loop, and the cost tradeoff. What it omits is parameter guidance and any note on what happens to the archive if the analysis fails, which keeps it from a 5.

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 should carry parameter meaning, but it never mentions project_id or idempotency_key. project_id is inferable from context ('the project's stack'), yet idempotency_key is entirely opaque and only the schema name hints at its role. With two params and no schema docs, this leaves 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?

It states a specific verb ('Re-run the analysis'), resource ('fline.json' in the archive), and effect (write a new one), which distinguishes it from the read-only check_config/get_config siblings. The check isn't quite a 5 because 'the analysis' and 'fline.json' are only loosely identified without context on what the configuration is, so it's clear enough for routing but not crisp for an unfamiliar caller.

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 ('a configuration that has gone stale because the project's stack changed') with concrete examples (different package manager, new lockfile), and even names the cheaper alternative ('editing the file yourself is free'). The follow-up sequence (poll get_project, then get_config) routes the caller cleanly.

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 description discloses a critical behavioral trait the annotations do not: the tool is not implemented and refuses. That is exactly the kind of context annotations cannot carry. However, the annotations declare destructiveHint=true and idempotentHint=true, which imply a real mutation occurs, conflicting with 'this refuses'.

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

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

Three short sentences, front-loaded with the verb and the blocking fact, then the remediation. Every sentence earns its place with zero filler.

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

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

For a non-implemented no-op with no output schema, the description is complete: it states the tool refuses and gives the correct alternative paths. Nothing an agent needs to avoid a wasted call is missing.

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

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

Schema description coverage is 0% and the description says nothing about project_id or idempotency_key. project_id is inferable from the tool name, but idempotency_key is entirely undocumented in both schema and description. Since the tool refuses anyway, the practical impact is low, but no meaning is added.

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 ('Stop the project') and immediately qualifies it with 'NOT IMPLEMENTED: the platform has no stop, and this refuses.' An agent can tell exactly what this tool is (a no-op) versus the real service-removal 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?

Explicitly says when NOT to use it and names concrete alternatives with their conditions: 'delete_project it or take its domain off with delete_domain.' This is a textbook routing instruction with no inference required.

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.