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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds non-obvious behavior: the scheduled request carries an x-antideploy-cron header that anyone can spoof, so real-work endpoints should verify their own secret. This is valuable beyond structured fields, though it doesn't cover auth requirements or duplicate/error behavior.

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

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

Two sentences, front-loaded with the action and example, then the security note. Every sentence earns its place with no 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?

For a 3-parameter creation tool with full schema coverage and no output schema, the description supplies the important operational and security context an agent needs. Some details, such as whether the new schedule is active immediately or how conflicts are handled, are omitted, so it is not complete.

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

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

Schema coverage is 100%, with path, method enum, and cron format fully documented. The description adds only conceptual context and no syntax or meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific action (call a path) and resource/scope (this application, on a schedule), with a concrete example. It is clear enough to distinguish from list/remove schedule siblings by name, but the description itself does not explicitly contrast them, so not 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 a representative use case (nightly cleanup) and a security caveat, which helps decide usage. But it never states when to prefer this over set_schedule_enabled/list_schedules/remove_schedule or any exclusion, so guidance is implied rather than 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: the top-up cannot be performed by the agent, the URL must be surfaced to the user, and the agent should wait — a meaningful constraint not derivable from 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?

Two short sentences, no filler, and the top-up caveat is stated up front alongside the content summary. The telegraphic first sentence is slightly clipped but costs nothing in length.

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

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

With no output schema, the description carries the burden of explaining return values, and it does list the key fields (balance, rate, AI keys, topUpUrl). It stops short of describing structure or units, but for a zero-parameter read tool that is a minor gap.

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

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

Zero parameters, so the baseline is 4 and there is nothing for the schema to document. The description uses the space productively by enumerating what comes back (balance, rate, keys, topUpUrl), which is the only parameter-adjacent semantics an agent needs here.

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

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

The description names the specific resources returned — balance, per-usage rate, and AI keys on the account — which clearly separates it from siblings like create_ai_key or request_keys. It lacks an explicit verb (it reads as a noun phrase describing return contents rather than 'retrieve the wallet'), so the action must be inferred, but the purpose is unambiguous.

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

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

The line 'Only the user can add money: give them the `topUpUrl` and wait' gives real operational guidance about the top-up handoff and implicitly frames this as a read-only inspection call. However, it never states when to call this versus create_ai_key or request_keys, so the agent must infer the boundary.

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?

readOnlyHint=true and openWorldHint=false already establish the safety profile, so the description only needs to add context. It does: the payload includes limits and 'current behaviour', and the caveat about disagreement implies the manual may lag the live server — useful for an agent deciding whether to trust it. It says nothing about response size or structure, which keeps it below 5.

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

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

Two short sentences, no filler, with the content scope front-loaded and the usage hint second. Every clause carries information an agent can act on.

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-argument documentation fetch with no output schema, the description tells the agent what topics the response covers and when it is worth consulting. The only real gap is that the return shape and size are unstated, which an agent may want to know before pulling a large manual.

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

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

Zero parameters, so there is no parameter semantics to explain; baseline is 4. The schema is empty and fully described, and the description correctly implies a single no-argument 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?

The description specifies the resource precisely: the platform's own self-description covering endpoints, limits, and current behaviour. That content set distinguishes it from operational siblings like health, metrics, and logs, which report live state rather than documentation. It lacks an explicit verb ('returns'/'fetches'), but the noun phrase is unambiguous.

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

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

It gives a concrete trigger: read it when something here disagrees with what the server actually does. That is a specific, actionable usage condition rather than vague encouragement. It does not name alternatives (health, logs) or state when not to bother, so it stops short of a full 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a useful field inventory (address, source, repository, branch, deployOnPush, root directory), but it omits that it reads settings for the linked/current app and gives no return-shape notes.

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

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

The single sentence is compact, but it is a sentence fragment with an unclear subject ('Its') and does not front-load the retrieval action. The field list is efficient, but the structure could be clearer.

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

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

This is a low-complexity read-only getter with no params and no output schema, and the field list partially describes return values. However, it does not say which application (linked/current) the settings belong to, leaving a real gap.

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

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

There are zero input parameters, so the baseline is 4 and there are no parameter semantics to explain. The description does not need to compensate for schema coverage.

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

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

The description never states an action verb or that it returns settings; 'Its address...' is a fragment with an unclear referent. A reader can infer it describes app settings fields, partly aided by the name/title, but the purpose is not explicit and is not differentiated from update_app_settings.

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

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

No indication of when to use this instead of update_app_settings or list_applications, and no prerequisites or context about which app's settings are read. Usage is only implied by 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?

Beyond the annotations (openWorldHint=false, destructiveHint=false), the description discloses idempotency ('safe to call twice'), a real side effect (creates a database if none exists, consuming a plan database slot), rate limits (~nine attempts per ten seconds, 429), which error codes are terminal (402/409), and that the cookie secret is deliberately withheld. These are exactly the behavioral traits an agent cannot infer from structured fields.

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

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

The opening sentences are front-loaded with the core action and the key constraint (requires an existing project with accounts). The description is long and its later half drifts into HTTP endpoint and rate-limit detail, but for a zero-param tool with this much side-effect surface, most sentences still earn their place; the parenthetical style makes it slightly denser than ideal.

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 a qualifying annotation set, the description covers everything an agent needs: prerequisites, side effects, idempotency, error semantics, secret handling, and the concrete next step (auth_env_to_file) plus framework-specific follow-up. Nothing material 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description adds no parameter-level information, but none is needed.

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 action (switching on sign-in / Neon Auth) and the resource it provisions (accounts stored in a neon_auth schema of the app's own Postgres). It is clearly distinguishable from siblings like auth_env_to_file, which it explicitly names as the follow-up step for retrieving secrets.

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 when-to-use ('while the project is still being written'), explicit when-not-to-use (no accounts, user already chose Clerk/Auth0/Supabase Auth, project already has its own database), and maps those exclusions to concrete error answers (409 own_auth / own_database). It also states the correct response to failures: a 402 database_limit is not retryable, and refusals should be reported to the user rather than worked around.

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

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

With only `openWorldHint: false` provided, the description carries the behavioral burden and does so well: it discloses replacement of existing variables, preservation of other entries, .gitignore modification, return of names only, and secret-handling constraints. It also warns not to read the file back to the user and states the auth requirement for reading the secret.

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 and front-loaded, with each sentence contributing operational context. It is slightly paragraph-heavy and packs several constraints into long clauses, but there is no wasted content.

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

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

For a mutation tool with no output schema and minimal annotations, the description is complete: it covers side effects, return shape, prerequisites, auth needs, and secret-handling behavior. An agent can infer whether and how to call it without opening the schema.

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

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

Schema coverage is 100%, so the schema already documents both `file` and `directory` parameters. The description reinforces that the file lives in the project directory but adds little parameter-specific syntax or format beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: writing four named auth variables into a .env file and returning only their names. It also distinguishes this from set_env by warning not to copy the variables there, making the tool's scope clear against 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?

It gives explicit prerequisites and routing: sign-in must exist first via `auth_create`, and an account token from `login` is required. It also says not to copy the variables into `set_env`, which directly distinguishes this tool from a sibling alternative.

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?

readOnlyHint and openWorldHint already carry the safety profile, and the description adds genuine context: that this is a pre-flight availability check and that the label becomes the user-visible shared URL. It does not say what a taken label looks like in the response, whether labels are globally unique, or whether checking reserves anything — gaps that matter for an agent deciding what to do next.

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

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

Two sentences, zero filler, with the action and the resulting address front-loaded and the workflow hint second. Nothing repeats the title or the schema.

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

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

For a single-parameter read-only check with no output schema, the description covers purpose, timing, and what the label denotes. The only meaningful omission is the shape/meaning of the answer (free vs. taken), which the agent must infer from 'check whether ... is free'.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's 'The label to check, like my-app' by explaining that the label is the subdomain portion of my-app.antideploy.app and that it is user-chosen. That mapping adds real meaning an agent would otherwise have to infer.

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 whether an address label ... is free') and immediately gives the concrete form the label takes (my-app.antideploy.app). The 'before creating the application' framing separates it cleanly from create_application without ambiguity.

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 places the tool in a workflow: call it before creating the application with that label, which implicitly routes the agent to create_application afterwards. It stops short of stating exclusions (e.g., whether to call it on redeploy or on an existing link), so it is clear context rather than a full when/when-not rule.

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 context beyond annotations: the secret is deliberately not returned, it lands in the app's environment, and a key with no funds is disabled until top-up. That is exactly the operational detail an agent needs to set user expectations after calling.

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 and the follow-up requirement; every sentence carries operational meaning. The parenthetical about hundreds of models and the API URL is slightly promotional but does clarify what the key unlocks.

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 single-parameter tool it covers the full lifecycle: create, save, redeploy, and the disabled-until-funded caveat. Nothing an agent needs to call it correctly or explain the result is missing.

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

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

Only one parameter and the schema already documents it at 100% coverage ('A label for the key, like chatbot'). The description adds nothing further about naming conventions or constraints, so the baseline 3 applies.

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

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

A specific verb+resource: creates an OpenRouter key and stores it as OPENROUTER_API_KEY in the application. It also disambiguates from generic env tools like set_env by naming the exact provider and env var, and from ai_wallet by describing the key rather than the wallet.

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 the required follow-up step ('Then `redeploy` so the running app picks it up'), naming the sibling tool. It doesn't cover when to prefer this over request_keys or ai_wallet, which keeps it 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 substantial context beyond the sparse annotations: it discloses idempotent-ish collision behavior (returns the existing application, links it, marks reusedExisting), the risk that the reused app belongs to another project and will be replaced by a deploy, auth requirement ('Needs login'), and the meaning of a 402 (plan limit, not a rate limit, do not retry). That is exactly the operational detail annotations do not supply.

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

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

The purpose is front-loaded in the first sentence and nearly every sentence carries a decision rule or risk. It is dense but slightly overlong and semicolon-heavy, with one mildly expendable sentence ('This is the step the dashboard used to be for').

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 and thin annotations, the description covers prerequisites (login), ordering relative to database_create/deploy/check_address/update_app_settings, side effects (writing .antideploy.json, linking an existing app), and a specific error path. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real decision guidance the schema does not: when to supply subdomain (only after check_address and only if the user chose it) and what happens when it is omitted. It also reinforces the folder-name default for name and the working-directory default for directory.

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 ('Create an Antideploy application') plus the concrete side effect of recording it in .antideploy.json. It clearly separates itself from siblings like link_application, list_applications and update_app_settings by describing creation-with-persistence rather than linking or listing.

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 sequencing ('Do it once per project, before database_create and deploy'), explicit when-to-ask-the-user behavior for the reused-application case, and explicit branching on subdomain ('if they have said what they want, pass it as subdomain after check_address; otherwise leave it out and settle it with update_app_settings'). Alternatives and orderings are named 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?

Beyond the sparse annotations, the description discloses idempotency, plan allowance impact, the meaning of a 402 database_limit error, refusal handling, and the fact that the connection string is not returned. These are important operational traits for a create tool.

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

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

The definition is dense but front-loaded with the core action and use case, followed by skip conditions, error handling, and follow-up steps. Every sentence carries operational value for a tool with no parameters but nontrivial workflow constraints.

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 minimal annotations, the description still explains the key return limitation, error behavior, approval fallback, and the required next sibling call. It is complete enough for an agent to invoke and recover correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline for zero-parameter tools is 4, and nothing in the description suggests missing parameter information.

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: create this application's Postgres database now. It also distinguishes the action from the follow-up sibling by noting the connection string is not returned and directing the agent to `database_env_to_file`.

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 conditions for use and for skipping it, including projects that store nothing or already point at a user-chosen database. It also names the resulting 409 own_database state and routes the agent to `database_env_to_file` afterward.

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 openWorldHint=false, so the description carries the burden and does so thoroughly: the password is written to disk and never returned, existing variables are replaced while others are kept, the file is added to .gitignore, and the DB may hold real data that must not be reset or dropped without asking. These are exactly the merge semantics, secret-handling, and destructive-risk traits an agent needs beyond a single locality hint.

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 and the return contract, then ordered by importance: secret handling, merge semantics, auth requirement, data-safety warning. It is long but every sentence contributes an operational rule that cannot be derived from structured fields.

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 still states precisely what is returned (names only) and what is not (the password). With only two optional parameters and a minimal annotation set, nothing an agent needs in order to invoke this safely is missing.

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

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

Schema coverage is 100%, with the `file` parameter already explaining the .env.local Next.js case, so the schema does the heavy lifting. The description adds only ambient context ("in the project directory") rather than new meaning for `file` or `directory`, which matches the baseline 3.

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

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

Starts with a specific verb and resource: writes DATABASE_URL and the PG* variables into a .env file, and states the return value is only the names. The database scoping clearly distinguishes it from the storage_, auth_, and email_env_to_file siblings, which an agent can tell apart 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?

Gives concrete preconditions (needs the account token saved by `login`; a project key cannot read a connection string) and an explicit prohibition (do not read the file back out to the user). It names `login` as the dependency but stops short of routing to sibling alternatives like set_env or set_env_from_file for the non-database case, leaving that to be inferred from the DATABASE_URL scoping.

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 already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context beyond that: it discloses the masked connection string and explains that the platform provisions Postgres and sets DATABASE_URL automatically.

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

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

The description is short and front-loads the returned information. The second sentence is relevant context about automatic provisioning, though the initial pronoun is somewhat vague without the title.

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

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

For a zero-parameter read-only info tool with annotations covering safety, the description gives enough context to call it correctly and describes the main returned fields. It could be slightly more complete about what happens when no database exists or the exact response shape, but the core information is present.

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

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

This tool takes zero parameters, so there are no parameter semantics to document and the baseline is 4.

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 makes clear that this is the application's database info tool, returning state, size, tables, and a masked connection string. The resource is specific, though the opening pronoun "Its" relies on the title and there is no explicit inspect/retrieve verb.

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

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

Usage is mostly implied by the returned fields. The description mentions `database_create` as the way to request earlier provisioning and warns against sending users to sign up elsewhere, but it does not explicitly say when to use this tool versus other database-related siblings such as `database_env_to_file`.

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 give openWorldHint=false and destructiveHint=true; the description adds substantial context beyond that — upload exclusions (.env, node_modules, build output, private keys, virtualenvs), the single-file/assets-404 failure mode, async behavior via taskId, and the note that the result names skipped .env files. It never explains why it is destructive (that the existing live deployment is replaced), which is the one behavioral gap.

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

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

Front-loaded with the action and dense with useful constraints; nearly every sentence carries information. The closing instruction ("tell the user where it is live and on which account") is agent-behavior guidance rather than tool semantics, a minor off-domain addition in an otherwise tight paragraph.

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 covers the async taskId return and the polling sibling, plus upload exclusions and linking prerequisites. The missing piece is what happens to the previously live deployment on success, which matters given destructiveHint=true.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning for `env` (variables come from set_env/set_env_from_file or here, and platform-managed ones are set automatically) that the schema does not convey. `force` and `directory` are left entirely to the schema.

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

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

Opens with a specific verb and resource ("Package a project directory and deploy it") and immediately clarifies scope: the whole directory is uploaded, not an entry point. It names the sibling to poll (deployment_status) and the sibling needed for prerequisites (create_application), so an agent can distinguish it from redeploy and the env-setting tools.

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

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

Provides real preconditions (folder must be linked via create_application unless a project key exists) and routes env configuration to set_env/set_env_from_file or the env argument. What it lacks is an explicit deploy-vs-redeploy distinction, which is the most likely sibling confusion given redeploy 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 establish a safe read (readOnlyHint=true, openWorldHint=false), and the description adds genuinely non-obvious behavior: newest-first ordering and the fact that `error` carries the full failure sentence rather than a code. The warning that an unchanged redeploy reproduces the failure is real operational guidance not derivable 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?

Two short sentences, zero filler. The return fields are front-loaded and the usage rule follows immediately, so the agent gets the essentials on first read.

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 enumerates returned fields and their ordering, covering most of what an agent needs for a read-only one-parameter tool. The gap is whether older history is retrievable past the 50-item limit — neither description nor schema says how to page further 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?

The single parameter has 100% schema coverage with 'How many. Default 10.', so the schema does the heavy lifting. The description's 'newest first' implies what the limit counts, but adds no bounds or paging information (max 50 is only in the schema).

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

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

Names a specific resource (recent deploys) and enumerates what comes back (status, commit, address, error sentence), with ordering stated as newest first. It doesn't name the ambiguous sibling `deployment_status` to distinguish the pair, so an agent must infer that this is a history list versus a current-state check.

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 conditional trigger: read this before redeploying after a failure, justified by 'an unchanged redeploy fails the same way.' It stops short of naming alternatives (e.g. `logs` for deeper diagnostics) or exclusions, so it's clear context without full 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 declare readOnlyHint and openWorldHint, but the description adds behavior those annotations cannot express: the call blocks for up to 20 seconds, the recommended retry cadence, the realistic total wait time, and the fact that an unchanged redeploy fails identically. That last point is a genuinely non-obvious behavioral warning.

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 what is returned, then retry policy, then failure handling – a logical order with no filler. It is on the long side and repeats the 20-second figure that the schema already carries, which keeps it just short of a 5.

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

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

No output schema exists, so the description carries the return-value burden and does it: it names the key fields (`summary`, `error`, `failedStep`, logs) and says how to act on each. For a two-parameter polling tool with a clear failure path, nothing an agent needs is missing.

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

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

Schema description coverage is 100% – taskId's origin ('returned by deploy') and waitSeconds' bounds and default are already documented in the schema. The description restates the 20-second wait but adds no new parameter semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Progress for one deployment') and enumerates what it returns: status, per-step detail, analyzed spec, warnings and hazards. This distinguishes it cleanly from the sibling `deploy` (which initiates) and `deployment_history` (which lists past deploys).

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

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

Explicit when-to-use and how: call it again immediately until status is succeeded or failed, explicitly forbidding pause-based or custom polling loops. It also gives an expected duration ('one to three minutes') and prescribes a failure path: read `error`, `failedStep`, logs, fix the cause, then redeploy.

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

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

With readOnlyHint and openWorldHint already declared, the description still adds real behavioural context: ordering (newest first), the deliberate absence of subject/body/address, and the rule that `outcome` is null until Resend reports and while `reporting` is false. It omits retention window and any rate/volume limits, which keeps it from a 5.

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

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

Front-loaded with what the log is, then use cases, then the data-absence caveat, then the null/pagination mechanics — every sentence carries information an agent needs and none repeats the schema verbatim.

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

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

No output schema exists, so the description carries the return-value burden, and it does: the row contents, ordering, and the `next` cursor are all described well enough to write a correct query and interpret the response. The `reporting` flag is referenced, which fills a gap the input schema leaves open.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the null-until-reported semantics of `outcome` (telling the agent that outcome filters will miss pending rows) and by restating the cursor contract for `before` in operational terms ('the `next` of the last answer'). It does not clarify `limit` behaviour or defaults beyond the schema.

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

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

The description names a specific resource and scope: the relay's log for this application, newest first, with the fields it carries (timestamp, address count, relay status, report outcome, reason). An agent can distinguish it from general settings tools, but it never explicitly contrasts itself with near-neighbours like email_status, email_overview or email_deliverability, so the sibling boundary is inferred rather than stated.

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

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

It gives concrete triggering questions ('did my email go out', 'why did that one not arrive'), which is clearer than most definitions. It does not say when to prefer email_deliverability or email_status, and names no exclusions, so it falls short of a 5.

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

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

The description discloses many operational details beyond the annotations: the call is safe to call twice, credentials are not returned, errors have specific meanings, and refused/blocked calls should not be retried through another route. It also explains sending behavior, reply-to handling, relay configuration, quotas, rate limits, and refused features such as attachments, scheduling, templates, and batch sends. This gives the agent a rich and accurate behavioral picture.

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 most important information is front-loaded: what the tool does, when to use it, and when to skip it. The remainder is long but largely earns its space with concrete setup, error, sending, and quota details. Some sentences could be tightened, but the structure remains purposeful.

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 setup tool with no output schema, the description covers the practical lifecycle an agent needs: when to call it, what it does, how to retrieve the resulting token, what sending behavior to expect, and how to handle errors or refusals. The annotations cover safety flags, and the description complements them with the operational context an agent would otherwise lack.

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 are no input parameters, so schema-level parameter semantics are not a concern. The baseline for a zero-parameter tool is 4, and the description does not need to explain parameter meaning.

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

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

The description clearly states that this tool enables the application to send email through the platform, using a real setup rather than a user-owned Resend account. It distinguishes this setup action from related tools by referencing `email_env_to_file` for retrieving credentials and by describing the `own_email` conflict case. The phrasing is narrative rather than a crisp verb-resource statement, but the purpose is still unambiguous.

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

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

It gives explicit inclusion and exclusion criteria: use only for projects that send mail, skip if the project already sets its own `RESEND_API_KEY`, and skip if email is not needed. It also explains what to do on `409 own_email`, `503 email_unavailable`, refusal, or blocking, and points to `email_env_to_file` for the token. This is strong when-to-use and when-not-to-use guidance.

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

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

The description adds critical behavioral context beyond the readOnly and openWorld annotations. It explains that when `reporting` is false, zero counts mean 'unknown' rather than 'healthy', and it exposes the platform's automatic email-stopping thresholds including at least three bouncing addresses that are a fifth of a day's mail, or two spam reports in a week.

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

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

The description is front-loaded with the time window and resource, and every clause contributes relevant information. The long opening sentence is dense, but it remains efficient and the important reporting caveat is clearly separated.

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 parameters and no output schema, the description carries the necessary burden well. It enumerates what the tool returns, specifies the seven-day window, explains health status, covers recent problems, and clarifies the meaning of zero counts when reporting is disconnected.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and schema description coverage is 100%.

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

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

The description states a specific resource and scope: the last 7 days of this application's mail, covering delivered, bounced, spam-reported, health, recent problems, and platform rules. It is clear what the tool reports, but it does not name or distinguish itself from sibling tools such as email_activity, email_overview, or email_status.

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: the tool is for checking mail deliverability health and recent problems. However, the description gives no explicit guidance on when to use it instead of related sibling tools, nor does it state any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the non-obvious platform limitation that user-owned domains are not supported, but it does not describe the return shape, error behavior, or whether an app must be linked.

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

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

Two short sentences, front-loaded with the core values and then the key constraint. The first sentence is a noun-phrase fragment rather than a full sentence, but it wastes no words and keeps the important limitation visible.

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 lookup with no output schema, the description lists the three values the caller can expect and warns about the unsupported custom-domain path. It does not explicitly state the return structure or required app-linking context, but it is largely complete for this simple 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?

The tool has zero parameters and an empty schema, so there are no parameter semantics to explain. Baseline 4 applies because the description does not need to compensate for missing parameter documentation.

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

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

The description names the specific resource—the platform sending domain, the application's address under it, and the From value—so the agent knows what information is available. It lacks an explicit verb like 'returns' and does not distinguish itself from siblings such as email_overview or email_status, but the resource itself is clear.

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 includes a clear negative instruction: never send the user to add DNS records, because custom-domain sending is unsupported. However, it does not say when to call this tool rather than email_overview, email_status, or email_create, so tool-selection guidance is only implied.

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

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

With only `openWorldHint: false` in annotations, the description carries the full behavioral burden and does so well. It discloses replacement semantics (existing variables replaced, everything else kept), a side effect (.gitignore is updated), secret-handling requirements, the return shape, and the authentication prerequisite involving the token saved by `login`.

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

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

The definition is front-loaded with the core action and return behavior, and every clause adds useful information about security, prerequisites, or side effects. It is slightly dense and run-on in places, but there is no filler or repetitive 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 secret-writing operation with no output schema, the description is complete enough to call correctly. It covers prerequisites, authentication, file mutation behavior, security constraints, and return values, leaving no major operational gap.

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

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

Schema description coverage is 100%, so the two parameters are already documented in the input schema. The description adds context that the file lives in the project directory but does not elaborate on syntax, defaults, or path constraints beyond what the schema provides. This is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: write named email variables into a .env file and return only the written names. It distinguishes itself from nearby tools by explicitly saying not to copy the variables into `set_env`, and its scope as an email-specific env writer is clear against siblings like `set_env_from_file` and `database_env_to_file`.

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 when-to-use guidance: email must be set up first via `email_create`, and the variables must not be copied into `set_env`. It also states a clear operational exclusion: do not read the file back out to the user, because the relay token must never enter the conversation.

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 already indicates a safe read operation, and the description adds useful context about credential-dependent scope and what data is surfaced, including applications with no email. It does not describe pagination or exact response formatting, but it substantially enriches the behavioral picture.

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 compact and front-loads the account-wide email overview. The parenthetical field list is dense but informative, and the second sentence carries necessary credential-scope 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 input parameters and no output schema, the description does a good job explaining the returned information and the key credential-dependent scope difference. Some details such as pagination or exact response shape are omitted, but the core context is present.

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

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

There are no input parameters, so the baseline is 4. The description adds only implicit context about account token versus project key authentication, but there are no parameter semantics to clarify.

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

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

The description clearly states that this is an account-wide email overview across every application, including state, pausing actor, recent sends versus allowance, deliverability, and applications with no email. It distinguishes the account-wide scope from single-application views implicitly, though it does not explicitly name any sibling tool.

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

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

It explains the credential-dependent scope: with an account token it covers every application, and with only a project key it shows this application alone. However, it does not explicitly say when to use this versus alternatives such as email_status, email_activity, or email_deliverability.

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

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

Beyond the annotations, the description discloses the concrete effect: the token is refused with `403 suspended_api_key` until `email_resume`, while the application itself keeps running. It also explains the required account token and that the user should be told the email is paused, which is important operational context for a mutation-like action.

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

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

The description is front-loaded with the action and urgency, then covers effect, resume path, runtime impact, and auth requirements in a compact set of sentences. Every sentence contributes useful operational guidance without waste.

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

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

For a no-parameter, no-output-schema tool, the description provides enough context to invoke it correctly: what happens, what is required, how it relates to `email_resume`, and what the agent should communicate to the user. No essential behavioral or usage information appears to be 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?

This tool has zero input parameters, so there is no parameter schema for the description to enrich. The mention of the required account token is auth context rather than an input parameter, making the baseline score appropriate.

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

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

The description states a specific verb and resource: "Stop this application's email at once." It also adds scope and distinguishes the action from `email_resume` by explaining that the token remains refused until resume. An agent can identify exactly what this tool does 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?

The description explicitly gives triggering conditions: a leaked token or a loop in the code. It names the complementary tool `email_resume` and states the prerequisite authentication requirement, including that a project key cannot perform the action. This leaves little ambiguity about when and how to use it.

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

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

Beyond the `destructiveHint=true` annotation, the description discloses the concrete consequences: the token is refused, the running app keeps its existing variables, and mail fails until `email_create` restores setup. It also reveals the 409 behavior when the platform has paused the email service and states the account-token requirement, which is unusually rich behavioral context for a destructive tool.

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

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

The action and immediate consequence are front-loaded, followed by usage restriction, conflict behavior, and auth requirement. Every sentence contributes operational information, with no redundant restatement of the tool name or annotation.

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 parameters and no output schema, the description supplies the context an agent needs: what is destroyed, what happens to the running app, how to restore email, when not to use it, the 409 pause condition, and the auth requirement. Nothing material is missing for correct invocation.

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

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

The input schema has zero parameters, so there is no parameter semantics burden and the baseline is 4. The description appropriately focuses on behavioral effects and prerequisites rather than inventing parameter details.

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 destructive action on a specific resource: taking email away from an application and refusing its token from then on. It clearly distinguishes the operation from setup by noting that mail fails until `email_create` runs again, so an agent can identify the tool's role without ambiguity.

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 strong use restriction: only when the user asked for it. It also explains a conflict condition (409 while the platform has it paused) and the prerequisite account token. It could be slightly stronger by explicitly pointing to `email_pause` or `email_resume` as alternatives, but the operational context is clear.

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

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

Goes well beyond the annotations: it discloses a specific failure mode with its HTTP status code (409 paused_for_deliverability), explains that such a pause cannot be lifted by this tool and why, and states the authentication requirement ('Needs the account token'). Annotations only cover destructiveHint=false and openWorldHint=false, so this added error and auth context is genuinely valuable.

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 action and its prerequisite in the first clause, then spends the remaining sentences on the one non-obvious edge case and the workaround to avoid. No filler or restatement of the title.

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

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

For a zero-parameter, non-destructive state-change tool with no output schema, the description covers everything an agent needs: preconditions, the blocked-case behavior, remediation guidance, and auth. Nothing is left to inference.

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 and the baseline of 4 applies. The only implicit input requirement is the account token, which is mentioned but not framed as a parameter.

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 ('Start this application's email again') and explicitly anchors it to the sibling that precedes it, `email_pause`. An agent can distinguish resume from pause, remove, create, and deliverability tools 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?

Gives the triggering condition (after `email_pause`), an explicit exclusion with the exact error signal (409 paused_for_deliverability), the correct alternative behavior (tell the user, who replies to the notice they were emailed), and a named anti-pattern to avoid (removing and re-adding email). This is the full when/when-not/alternative triad.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavioral details beyond them: it reports the last 24 hours and 14 days, includes pausedBy/pausedReason, describes health, and explicitly says it never returns the token. That security and return-scope context is valuable and consistent with the annotations.

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

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

The description is front-loaded with the core status information and every clause carries substantive meaning. The first sentence is long and somewhat run-on, but it is not padded with vague 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 input parameters and no output schema, the description carries the burden of explaining what the tool returns. It enumerates the key result areas: send capability, sender address, allowance, 24-hour activity, pause state with pausedBy/pausedReason, 14-day history, last-send timing, and health. That is complete enough for an agent to understand and use the status 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?

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description does not need to compensate for a parameter schema.

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

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

The description states a clear read-only purpose: reporting whether the application can send email, from which address, allowances, recent sends, pause state, and deliverability health. It is specific about the resource and returned concepts. It does not explicitly distinguish itself from nearby siblings such as email_overview, email_activity, or email_deliverability, so sibling differentiation is missing.

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

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

It gives clear usage context: 'Read it before telling the user whether email works.' This tells an agent when to call it. It does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the sparse annotations, the description discloses the key behavior: it sends a real message through the relay exactly as application code would, it consumes one address against the daily quota, and it requires the account token. These are important operational details for a tool with openWorldHint=true.

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

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

The description is front-loaded and every sentence contributes useful information. There is minor redundancy in repeating the account's own address as the recipient, but overall it is efficient.

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

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

For a no-parameter, no-output-schema tool with minimal annotations, the description covers the important gaps: real delivery, relay path, fixed recipient, quota consumption, and authentication. An agent has enough to call it correctly and understand the side effects.

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 are zero parameters, and the schema confirms an empty object, so the baseline is 4. The description correctly states that the recipient is fixed and not caller-controlled, but no parameter-level detail is needed beyond that.

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: send one real test message to the account's own address through the relay. That is clearly distinguishable from sibling tools such as email_status, email_activity, and email_deliverability, which inspect rather than send.

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 purpose and the intended outcome are explicit: use it so the user can see that email works, and the recipient is always the account's own address. It does not explicitly name alternative email tools or exclusion conditions, but the usage context is clear enough for an agent to choose it over diagnostic siblings.

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

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

Annotations already declare readOnlyHint and closed-world; the description adds the crucial non-obvious trait that the data is stale (five-minute sweep, not a probe taken now) and the exact semantics of the returned state and checkedAt. That latency disclosure is exactly the behavioral 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?

Two sentences, front-loaded with the return semantics then the staleness caveat. Every clause earns its place, with no restating of the name or title.

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

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

No output schema exists, and the description compensates by naming the returned fields and their meaning. For a zero-parameter read tool the description supplies everything needed to call it and interpret the result correctly.

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

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

There are zero parameters, so the baseline is 4; the schema is trivially complete and the description correctly describes the return shape (state plus checkedAt) rather than inventing inputs.

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

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

The description states a specific resource and its value set: last observed state (healthy/degraded/down/unknown) plus when it was checked. It clearly reads as a status/health read, distinct from siblings like deployment_status or metrics, though it doesn't explicitly name an alternative to distinguish itself.

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 tells the agent this is a five-minute sweep, not a live probe, and instructs to 'compare checkedAt with your deploy' — a concrete when-to-use rule. It stops short of naming sibling alternatives (e.g., metrics or deployment_status), so it lands at 4 rather than 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 only declare openWorldHint=false and destructiveHint=false, so the description carries the real burden and does so: it names the file it mutates (.antideploy.json) and warns that a wrong choice overwrites live deployment state. It stops short of saying what happens if a link already exists or how failures surface, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with what the tool does, then the value source, then the risk. Nothing is redundant with the schema beyond a brief reinforcement of the id source, and every clause adds actionable information.

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

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

For a two-parameter tool with no output schema, the description covers purpose, value provenance, and the destructive downstream consequence, which is what an agent needs to call it safely. It could still state whether re-linking an already-linked folder is idempotent or an error.

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

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

Schema coverage is 100% and both parameters are described there, including the same 'An id from list_applications' hint, so most param guidance is duplicated rather than additive. The one genuinely new constraint, never guess and never take an id the user did not name, is a usage rule more than a parameter semantic.

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 pair (record an existing application in .antideploy.json for a folder) and adds the downstream effect, 'so deploys and the other tools act on it'. The wording 'the user already has' cleanly distinguishes it from create_application, and the reference to list_applications separates it from the discovery tools.

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

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

Gives an explicit precondition ('Only when the user said which one; never guess') plus the exact source of the required value ('Take the id from list_applications'). It also names the consequence of violating the rule (a deploy would replace what is live), which is a true when-not condition rather than generic advice.

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 useful scope context — that results may cover the whole account or only the application tied to the server's key — which affects how the agent interprets the list. Pagination and empty-result behavior are still unstated.

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

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

A single dense sentence that front-loads what is returned and closes with the action it enables. No filler or repetition of the title.

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

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

With no parameters and no output schema, the description carries the return-value burden and does so by enumerating the fields returned. Nothing an agent needs before calling it 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?

The tool takes zero parameters, so the baseline is 4. The description instead spends its words documenting the response fields (id, name, address, account), which is the useful place for detail here.

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 ('Every application on the account ... with its id, name and address') and even answers the account-context question. An agent can immediately tell this apart from create_application, link_application, and other 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 names the downstream use: 'Use it to pick an id for `link_application`.' That routes the agent to the right follow-up, though it does not state any exclusion or alternative for other listing needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a non-obvious and important behavioral fact: values are never returned, by design, which prevents an agent from expecting secret values in the response.

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 extremely short and front-loads the critical constraint ("Names only"). Every fragment earns its place by preventing a common misunderstanding about returned values.

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

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

For a zero-parameter read-only listing tool with no output schema, the description covers the key return-value limitation. It could additionally state the scope (e.g., current application) or exact return shape, but the essential caveat is present.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter schema is 4.

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 does not itself state the action or resource; "Names only" primarily clarifies the output shape and relies on the tool name/title to convey that it lists environment variable names. It does distinguish the tool from value-returning operations, but the purpose statement is implicit rather than explicit.

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 such as set_env, set_env_from_file, or remove_env. The output constraint is useful but does not tell an agent when this listing tool is the right choice.

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 this to be read-only and not open-world, but the description adds useful behavioral context: returned fields include next and last run, last status, and error, and it discloses scheduling rules (UTC, a few jobs per application, runs at least five minutes apart). It does not mention whether disabled jobs are included, but this remains a helpful 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?

The description is a single front-loaded sentence with no filler. The returned fields and scheduling rules each add useful information, though the phrase 'plus the rules' is slightly less direct than it could be.

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

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

With no parameters, no output schema, and read-only annotations, the description gives an agent enough to understand what the tool returns and the scheduling constraints. A minor gap is that it does not explicitly say whether all schedules (including disabled ones) are listed or whether ordering is guaranteed.

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 are zero parameters, so the baseline is 4. The description appropriately does not waste space documenting nonexistent parameters and instead focuses on what the returned schedule records contain.

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

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

The description identifies the specific resource, the application's scheduled jobs, and enumerates the returned fields (next/last run, last status, error). It implies listing but does not use an explicit verb or explicitly contrast with the sibling mutation tools add_schedule, set_schedule_enabled, and remove_schedule.

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

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

There is no explicit guidance on when to use this tool versus add_schedule, set_schedule_enabled, or remove_schedule. The resource name implies a read/list operation, but no conditions, prerequisites, or alternatives 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?

Despite the annotations (openWorldHint=false, destructiveHint=false) already covering safety, the description adds substantial context: the token persists to ~/.antideploy, the token is never shown to the agent, it waits for approval, an account is created if none exists, and it is revocable at a URL. This is rich, non-redundant behavioral detail.

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

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

It is front-loaded with the purpose and every sentence carries flow or behavioral information. It is somewhat dense with nested parentheticals, but not padded with 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?

With no output schema, the description fully explains what each call returns (link and code, then the connected account) and how to surface it to the user. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the single `force` parameter is already documented as starting a new login to switch accounts. The description adds flow context but does not further explain `force` beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Connect this machine to the user's Antideploy account.' It is clearly distinct from siblings like logout, list_applications, and deploy, and an agent grasps the intent immediately.

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 sequences usage: first call returns a link/code, second call waits for approval and saves the login, later calls confirm the connection. It also states the exclusion behavior (if the user declines, stop and don't start another unless asked).

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

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

Annotations already flag destructiveHint=true, and the description adds genuinely non-redundant behavior: it is a local-only deletion that leaves the server token valid, and it does not touch a project key in ANTIDEPLOY_API_KEY. That is exactly the context an agent needs to avoid misreporting to the user that they are fully logged out server-side.

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, each carrying distinct information: the action, the gating condition, the server-side caveat with remediation URL, and the unaffected credential. Nothing is wasted and the action leads.

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

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

No output schema exists, but the tool takes no parameters and the description fully covers the side effects, the boundaries of the deletion, and the follow-up path. An agent has everything needed to call it and describe the result accurately.

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

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

Zero parameters, so the baseline is 4. The description still adds useful meaning by clarifying that an ANTIDEPLOY_API_KEY environment variable is out of scope, ruling out an input an agent might otherwise assume matters.

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

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

States a specific verb and resource (delete the locally saved account token) with explicit narrow scope ('on this machine'), which distinguishes it cleanly from the sibling 'login'.

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 when-to-use condition ('only when the user asked to sign out'), names what it does not do (server-side revocation), and points to the alternative path for that case (https://antideploy.com/tokens).

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 genuine context beyond that: the source is the running container's stdout and entries are ordered oldest→newest. It says nothing about volume, truncation, or whether the log stream is live, which would have raised the score.

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 filler, and the key fact (ordering) is placed at the end where it is easy to miss but present. It is lean to the point of being slightly thin, but nothing is wasted.

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

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

For a one-parameter read-only tool with full schema coverage and clear annotations, little more is required. The absence of any statement about return shape (raw text vs structured lines) is the main residual gap, and no output schema exists to cover it.

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

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

Schema description coverage is 100% and the single 'limit' parameter is fully documented there, so the baseline is 3. The description adds nothing about the limit (e.g. how lines are selected when truncated) and instead spends its words on stream semantics.

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

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

The description states the resource concretely – printed output of the running container – and the title supplies the verb ('Read'), so the tool's function is unambiguous. It implicitly distinguishes itself from siblings like metrics and health by being raw container output, though it does not name 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?

There is no guidance on when to reach for logs versus metrics, health, or deployment_status. The only contextual hint is 'newest last', which describes ordering, not usage selection.

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

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

The annotations already establish that this is a read-only, non-open-world operation. The description adds valuable data semantics by warning that requests include bots and every page asset, so they are not equivalent to visitors.

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 compact and front-loaded: first the returned metrics, then the usage trigger, then an important caveat. Every sentence contributes useful information without 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 one-parameter read-only metrics tool with no output schema, the description supplies the metric set, the correct usage scenario, and the key interpretation caveat. Nothing necessary for correct invocation appears to be 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?

The single optional 'days' parameter is fully documented in the schema with range and default. The description does not add further syntax or meaning beyond that, so the schema-coverage baseline of 3 applies.

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

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

The description names the exact metrics returned: requests, server-error rate, p50/p95 response times, and requests per day. It also distinguishes this from the sibling logs tool by contrasting 'what happened' with 'how often'.

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

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

It gives a concrete trigger: check this when the user says the site is slow or failing. It also explicitly routes the agent to logs for detailed event context, making the selection between alternatives clear.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, and the description adds useful context (default = last-sent version + current env vars, `latest` pulls newest commit, returns a taskId). But it never discloses what is destructive about it – app restart/downtime or interruption of the running release – which is exactly the behavior the destructiveHint implies. Adds value, but leaves a meaningful behavioral gap.

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

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

Four short sentences, front-loaded with the core action and the default behavior, then the exception, then the return value. Every sentence carries information an agent needs and none repeats the schema verbatim.

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 supplies the return contract ('a taskId to poll with `deployment_status`'), which is essential. It is almost complete for a one-parameter mutation, missing only the restart/downtime implication and any permission prerequisite.

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

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

Schema coverage is 100% and the single `latest` parameter is documented, so the baseline is 3. The description goes slightly beyond by explaining the contrast: default is the last-sent version, while `latest` (GitHub apps only) deploys the newest default-branch commit.

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 ('Build and release the application again without uploading it'), which clearly separates it from the sibling `deploy` that would upload code. However, it doesn't explicitly name `deploy` as the alternative, so the differentiation is inferable rather than stated.

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

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

It states a concrete trigger condition: 'this is how a changed variable or a new AI key reaches the running app', which tells an agent when to pick this over other deployment tools. It also explains the `latest` branch case. It stops short of explicit when-not-to-use guidance or naming the sibling it replaces.

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

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

Beyond the `destructiveHint: true` annotation, the description discloses the delayed effect (the app keeps the value until the next deploy) and the irreversibility of visibility (a removed value cannot be shown again, only set again). These are exactly the non-obvious behavioral traits an agent needs for a destructive mutation.

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

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

Three compact sentences with zero waste. The core action is front-loaded, and the deployment consequence and irreversibility follow in logical order.

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

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

The description is complete for a one-parameter destructive tool with no output schema: it states the action, the delayed effect, the remedy (`redeploy`), and the loss of visibility. Nothing further is required for an agent to invoke it correctly.

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

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

The input schema has 100% description coverage for the single `key` parameter, so the schema already documents parameter meaning. The description reinforces that exactly one variable is removed but adds no syntax or format detail beyond the schema baseline.

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

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

The description gives a specific verb and resource: 'Remove one variable.' It clearly distinguishes removal from setting or listing variables, and it references the related `redeploy` tool for applying the change.

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

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

The description explains that the running app keeps the variable until the next deploy and that `redeploy` applies the removal. That is useful contextual guidance, but it does not explicitly say when to use `remove_env` instead of alternatives such as `set_env` or `list_env`.

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, so the safety profile is known. What the description fails to add is any consequence detail: whether removal is permanent, whether past runs/history are lost, what happens if the id is unknown, or that the job stops firing immediately. For a destructive tool it should disclose more than 'remove it'.

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

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

One sentence, zero padding, with the use case front-loaded. It is efficient but so short that it sacrifices a direct statement of what the tool actually does.

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, irreversible-looking operation on a single id, the description omits outcome and failure semantics entirely, and there is no output schema to fill the gap. An agent knows when to call it but not what it will observe or what it risks destroying.

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

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

There is a single required parameter with 100% schema description coverage that already points the agent to list_schedules for obtaining the id. The description adds nothing about the id's format or sourcing beyond that, so the baseline 3 applies.

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

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

The description never directly states the core action ('permanently removes a scheduled job'); it only says 'remove it and add it again' as a workaround pattern, leaving the name and title to carry the verb+resource. It does link implicitly to the sibling add_schedule, but an agent must infer the primary effect from the tool name.

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

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

It gives a clear, specific trigger: use this when you want to change a job's schedule or path, because that cannot be done in place. It names the follow-up action (add it again) rather than an alternative sibling, but the when-to-use condition is explicit and actionable.

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

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

Beyond the annotations (openWorldHint=false, destructiveHint=false), it discloses the security-relevant behaviour: the secret goes to an Antideploy page and into encrypted variables without passing through the conversation. It also reveals that this tool alone does not finish the job — the agent must poll list_env and then call redeploy — which is exactly the kind of cross-tool behaviour an agent cannot infer from structured fields.

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

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

Front-loaded with the purpose, then the security rationale, then the procedural steps and exclusions. Every clause carries actionable information — there is no restatement of the name or filler prose, despite the description being two long sentences.

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

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

No output schema exists, yet the description names the return field to surface (`url`) and prescribes the complete surrounding workflow (show url, tell where to find the value, poll list_env until all names appear, redeploy). An agent has everything needed to call it and to handle the result correctly.

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

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

Schema coverage is 100% and the single `names` array is already documented, so the baseline is 3. The description adds real meaning by illustrating the kinds of values (Stripe secret key, bot token, AI provider key) and by constraining which names are legitimate via the platform-provided exclusion list, though it doesn't discuss batching or format specifics.

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

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

States a concrete verb+resource: obtain a link where the user pastes a secret so it lands in the app's encrypted variables. It sharply distinguishes itself from set_env/list_env by being the path for values the agent doesn't already hold, and the title reinforces it.

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

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

Gives an explicit trigger ('a value that is not in the project'), explicit exclusions ('Do not ask for what the platform fills in itself — database, storage, sign-in, email variables, app address and signing secrets'), and an explicit prohibition ('Never ask the user to paste a key into the chat'). It also names the follow-up siblings (list_env, redeploy) and the order to call 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?

Adds substantial behavior beyond annotations: the deployment is rebuilt from source, takes as long as a normal deploy, and returns a taskId that must be polled via deployment_status. This aligns with destructiveHint=true and gives the agent the operational context needed.

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 tightly written sentences, front-loaded with the operation and followed by the important async/duration caveat. 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?

Complete for a destructive mutation with no output schema: it explains what the tool does, how long it takes, and how to handle the returned taskId. Nothing critical is omitted for correct invocation.

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

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

Schema coverage is 100%, so the deploymentId parameter is already documented. The description adds useful meaning by specifying that the ID refers to a deployment from deployment_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?

Clearly states the rollback operation and target version, and references deployment_history and deployment_status. It does not explicitly contrast with the closest sibling `redeploy`, so sibling differentiation is good but not complete.

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?

Explains the main usage context: restoring the previous live version or a specific earlier deployment, with the ID sourced from deployment_history. It also explains how to track the async result, though it does not state when to prefer rollback over redeploy or deploy.

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 already declare `openWorldHint=true` and `destructiveHint=false`. The description adds meaningful context beyond that: the scan is fast, runs against the live app, checks specific vulnerability categories, and is asynchronous with a polling requirement.

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

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

The description is short, front-loaded with the action and scope, and every clause adds useful information. It efficiently moves from scan purpose to duration to the required follow-up call.

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 tool with no output schema, the description provides everything an agent needs: what is scanned, how long it takes, that it returns a `scanId`, and which sibling tool to call next.

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 are zero input parameters, so there is nothing for the description to document semantically. The description correctly notes that a `scanId` is returned, which is workflow information rather than an input parameter.

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 ('Start a scan of the running application') and enumerates the vulnerability classes checked. It clearly distinguishes itself from `security_scan_status` by explaining the polling handoff.

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

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

It gives clear usage context and names the follow-up tool (`security_scan_status`) with the `scanId` needed. It does not explicitly state when not to use this tool, but the workflow 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?

The annotations already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by disclosing terminal states (`completed`/`failed`), the finding structure, and the recommended remediation loop.

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 carry the result shape, polling behavior, and remediation workflow with no wasted text. The most actionable guidance is front-loaded and easy to scan.

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

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

For a simple read-only status tool with no output schema, the description explains the relevant return content and the polling condition well enough for an agent to use it correctly. The annotations cover the safety profile, and the description covers the workflow and findings 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?

There is only one parameter and the schema description coverage is 100%, so the schema already explains that `scanId` comes from `security_scan`. The description does not add further meaning about the parameter, so the baseline score of 3 is appropriate.

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

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

The description states that the tool returns scan status and findings, including severity, explanation, and recommendation. This clearly identifies a status/result retrieval operation, though it does not explicitly name the sibling `security_scan` as its counterpart.

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

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

It gives clear operational guidance: poll until completed or failed, fix findings at their root, then scan again. This establishes the intended workflow with `security_scan`, but it does not spell out when not to use this tool or explicitly name the alternative 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 destructiveHint=true; the description reinforces this by clarifying the tool is 'write-only' and that it replaces existing values, plus discloses the platform-reserved variable namespace and the secret-hygiene rationale for set_env_from_file. It stops short of stating whether changes take effect immediately or require a redeploy, which matters given the sibling redeploy tool.

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

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

Three short sentences, each carrying distinct information: action, mutability profile, key restrictions, and alternative routing. The core action is front-loaded 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?

For a one-parameter write tool with no output schema, the description covers the destructive semantics, reserved keys, and the sibling escape hatch. The only material omission is whether a redeploy is needed for new values to take effect.

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

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

With a single, fully schema-documented parameter the baseline is 3; the description earns more by constraining which keys are legal (no DATABASE_URL, PG*, storage, sign-in or email names), a rule the permissive name/value schema does not encode. It does not discuss value typing or size limits, but the schema already fixes values as strings.

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

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

Uses a specific verb pair (store or replace) against a specific resource (environment variables for this application), and explicitly names the sibling alternative set_env_from_file. An agent can distinguish it from list_env, remove_env, and set_env_from_file 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?

Gives explicit exclusions ('Do not pass DATABASE_URL, PG*, storage, sign-in or email variables') with the reason (the platform sets those itself), and routes to the alternative when values come from a local file. Both when-to-use and when-not-to-use are covered.

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

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

Beyond the destructiveHint/openWorldHint annotations, the description discloses real behavioral detail: only listed names are sent, platform-reserved variables (DB, storage, auth, email, app address, signing secrets) are refused with a reason, empty values and placeholders like your-key-here are skipped, and results report names only, never values. That is exactly the context an agent needs before invoking a mutation.

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

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

Front-loaded with the core action and mechanism, then the refusal rules, then the redeploy note. It is a bit long, but each sentence adds operative information (refusals, value confidentiality, next step) rather than 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?

No output schema exists, yet the description explains what the result contains (stored vs skipped, no values) and the required follow-up redeploy, covering the gaps a mutation tool with no output schema would otherwise leave.

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

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

Schema coverage is 100% and each parameter is documented, so the schema carries parameter meaning. The description adds only that 'only the names you list are sent' and that reserved names are refused, which is mild added value over a fully covered 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?

Names the specific action (read named variables from a .env file and store them) and the distinctive mechanism (values go file→Antideploy, never through the conversation), which clearly separates it from set_env and list_env. An agent can route to 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?

Implies the selection condition strongly — use this when values live in a local .env file rather than being passed in chat — and gives the follow-up step (redeploy for the running app to pick changes up). It does not explicitly name set_env as the alternative for in-conversation values, so it stops short of full when/when-not guidance.

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

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

Annotations only say openWorldHint=false and destructiveHint=false, so they convey nothing about the side effects of the toggle. The description discloses a genuinely non-obvious behavior: resuming clears the failure count, and the job auto-pauses after ten consecutive failures. That is exactly the kind of hidden state interaction an agent needs before resuming a job. It stops short of 5 because it doesn't say whether pausing interrupts an in-flight run or whether the reset is reported back.

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

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

One sentence with no padding, but it is mis-front-loaded: the leading content should be what the tool does, with the resume side effect as a trailing caveat. As written, the agent hits an unexplained detail before any statement of purpose.

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

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

The tool is simple (two required params), the schema is fully described, and annotations establish it is a safe, closed-world operation, so the description doesn't need to carry much. Still, for a mutation of job state it omits whether pausing takes effect immediately for a running job, whether the call is idempotent, and what state is returned.

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

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

Schema coverage is 100% and both parameters are documented inline, including that `enabled=false` pauses and `true` resumes, so the baseline is 3. The description adds a little meaning to `enabled=true` (the failure-count reset) but nothing beyond that for `enabled=false` or for the `id` parameter.

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 what the tool does; the purpose is only inferable from the name and title ("Pause or resume a scheduled job"). The single sentence is a side-effect footnote rather than a purpose statement, so an agent reading the description alone gets behavior, not function.

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 pause vs resume, no prerequisites, and no mention of siblings like add_schedule, remove_schedule, or list_schedules. The only guidance-adjacent content is the implicit warning that resuming resets the failure counter, which helps the agent anticipate consequences but doesn't tell it when to call the 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 only give openWorldHint=false and destructiveHint=false; the description adds the real behavioral surface: idempotency ('safe to call twice'), the specific error codes 409 own_storage and 402 storage_limit with retry guidance, the fact that credentials are not returned, and that the bucket is reattached on a later deploy. The path-style addressing note and presigned-PUT capability further describe how the created resource behaves.

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 action and its purpose are front-loaded, and nearly every clause carries operational value (idempotency, error codes, follow-up tool). It is a dense single paragraph that mixes calling guidance with downstream SDK advice (forcePathStyle, presigned PUT), which slightly hurts scannability for a zero-parameter tool.

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

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

For a mutation tool with no output schema and no parameters, the description covers everything an agent needs: prerequisites for calling, side effects on plan allowance, exact failure semantics, what is not returned, and the follow-up call to persist the key. Nothing consequential is left to inference.

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

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

The tool takes zero parameters, so the baseline is 4; the description adds nothing to document here and nothing is missing. Any parameter-level explanation would be noise.

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 ('Create a private S3 bucket for this application now') and immediately frames the intent (build/test uploads against real storage instead of ephemeral disk). It is clearly distinct from the sibling storage_env_to_file, which it names as the follow-up step rather than the alternative.

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

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

Explicit when/when-not: only for projects that store uploads or generated files, skip otherwise, and skip when the project already has its own storage credentials or a named third-party service (Cloudinary, UploadThing) because the answer is 409 own_storage. It also tells the agent not to retry on 402 storage_limit and not to hunt for another route if refused.

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 openWorldHint=false, so the description must supply behavioral context — and it does: the key stays out of the conversation, existing variables are replaced, others preserved, and the file is added to .gitignore. However, nothing is said about failure modes (e.g. what happens if the bucket doesn't exist or the token is missing) or any rate/conflict behavior, so it's solid but not exhaustive.

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's front-loaded with the core write action, then layers on safety and prerequisite notes; almost every clause carries information. Slightly run-on and dense, keeping it just shy of a 5.

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

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

For a two-optional-param tool with no output schema, the description covers what is written, what is returned ("only the names of what was written"), side effects (.gitignore, variable replacement), and prerequisites. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema (file, directory), so the description adds little parameter-level detail beyond implicitly referencing "the project directory" and .env. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description gives a specific verb ("Write") and enumerates the exact resource (bucket name, endpoint, region, access key) and the destination (.env file in the project directory). It clearly differs from sibling tools like set_env and database_env_to_file by targeting the storage bucket's credentials.

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

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

It explicitly names what not to do (don't copy into set_env, don't read the file back to the user), gives prerequisites ("The bucket has to exist first: storage_create makes it"), and states the auth requirement (account token saved by login, and that a project key cannot read the access key). This is a complete routing and prerequisite picture.

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 say destructiveHint=true; the description explains exactly what is destructive — the old subdomain stops working immediately — and warns to confirm with the user and show the full URL. It also discloses deferred effects (running app changes on next deploy) and the side effect of re-analyzing the project when rootDirectory changes, which is real value beyond the annotation flags.

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

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

A single dense sentence with parentheticals, but it is front-loaded with the full list of changeable settings and every clause carries information (destructive warning, deferral semantics, null meaning). Slightly parenthetical-heavy, yet nothing is filler.

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

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

For a three-optional-parameter mutation with full schema coverage, no output schema, and destructiveHint annotation, the description covers the destructive consequences, the timing of effects, and the re-analysis behavior. There is no significant gap an agent would need to fill before calling it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: what null means for rootDirectory (whole project), that subdomain invalidates the old address instantly, and that deployOnPush only matters for GitHub apps. It doesn't clarify the subdomain format beyond the schema's example, but the added semantics clearly exceed the baseline.

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

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

The description names the specific verb (change) and enumerates exactly which settings can be modified (subdomain, deployOnPush, rootDirectory), which cleanly separates it from the read-only `app_settings` sibling by implication. It stops short of explicitly naming the read counterpart or other address-related tools like `check_address`, so sibling differentiation is inferred rather than stated.

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

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

It gives concrete usage context per field: the subdomain change requires asking the user first and showing the full URL, and the rootDirectory change triggers re-analysis with effect deferred to the next deploy. That is clear when-to-use guidance, but no alternatives (e.g. `check_address` for validating a name before setting it) are named.

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