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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing what fields come back (protection mode, key presence, active environment) in the absence of an output schema. It stops short of describing ordering or formatting of the list.

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

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

Two sentences, both front-loaded: the first defines the operation and its payload, the second routes to siblings. No filler or restated name/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 tool with no output schema, the description compensates by enumerating the returned fields and covering the sibling-routing decision. An agent has everything needed to call it correctly and interpret the result.

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 no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-param tool is 4. The description correctly avoids inventing arguments.

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

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

States a specific verb and resource ('List every environment of the project') and then enumerates exactly what is returned: name, ID, default flag, protection status, key presence, and active environment. An agent can distinguish it from airstrings_status without opening either schema.

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

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

Gives explicit downstream usage ('Use it to pick environment names for airstrings_promote_preview or airstrings_sdk_config') and names the alternative plus the condition that selects it ('for the overall workspace state and next step, use airstrings_status'). This is textbook when-to-use / when-not-to-use 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 establish the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substance on top: it writes .airstrings/config.json, persists the key in the workspace, documents the full credential precedence chain (api_key > AIRSTRINGS_ORG_API_KEY > AIRSTRINGS_API_KEY > stored login), and describes the interactive pending/verification_uri_complete flow including the requirement to re-call with identical arguments. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the action and the ordering constraint, then the credential chain, then the fallback flow, then the return summary. Dense but every clause carries information; it is a long paragraph rather than a tightly structured list, which costs it the top mark.

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 summarizing the return payload (project, created flag, active environment, all environments and sections). Combined with the credentials, the re-invocation flow, and the sibling alternative, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the fallback order among credential sources, and the interaction rule that an org key creates a project named after the folder unless an existing project is named. It stops short of adding syntax or format detail for dir/base_url beyond the schema.

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

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

States a specific verb and resource ('Bind a directory to an AirStrings project') and immediately scopes it to the case it serves ('in a repo with no .airstrings workspace'). It also names the sibling it is not (airstrings_login), so an agent can distinguish it from every other airstrings_* tool without opening the schema.

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

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

Gives an explicit ordering rule ('call this first ... before any other airstrings_* tool') and an explicit exclusion ('Use airstrings_login instead only to store an org login without binding a directory'). Both the when and the when-not are stated rather than inferred.

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 (readOnlyHint=false, openWorldHint=true), the description discloses the full two-step protocol: first call returns status 'pending' with verification_uri_complete, an org owner approves in-browser, the agent must call login again, and denial/expiry means restarting. That async approval and retry behavior is exactly the context annotations cannot carry.

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

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

Purpose is front-loaded, followed by the exact call sequence and then the usage rule, with no filler. The length is justified by a genuinely multi-step, stateful flow that would be unusable if abbreviated.

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 stateful auth tool with no output schema, the description covers the return states (pending, verification_uri_complete, organization once stored), the failure/retry path, and the persistence side effect. An agent has everything needed to drive both calls 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 org parameter's constraint ('approval rejected for any other org') is already documented in the schema. The description adds persistence context ('store an org key on this machine') but no new meaning about org or base_url beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb+resource ('Log in to an AirStrings organization and store an org key on this machine') and immediately distinguishes itself from siblings by adding 'without binding a directory'. An agent can separate it from airstrings_init without opening either schema.

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

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

Explicitly routes the agent: 'Use it before airstrings_init when several directories will share one login; to set up a single repo, call airstrings_init directly (it logs in when needed).' This is a named alternative plus the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds real value by stating 'Applies nothing', that a human applies the change at apply_url in the dashboard, and that protected environments are out of reach for agents. It stops short of describing diff size limits or the full return shape.

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

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

Three sentences, front-loaded with the read-only nature of the call, then the human-handoff mechanic, then the usage trigger. No filler and every sentence carries distinct information.

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

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

For a 2-optional-parameter tool with no output schema but strong annotations, the description covers what the diff contains and the out-of-band apply path. Minor gaps remain (no mention of pagination or diff size, and apply_url is referenced without saying it comes back in the response).

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including defaults and the 'must differ from source_env' constraint. The description only reinforces the direction of the promotion, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific operation (read-only diff preview of a cross-environment string promotion) and enumerates the result contents (added, updated, extra keys per locale). It is clearly distinguishable from the sibling airstrings_variant_promote, which acts on variants rather than strings.

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 ('Use it after publishing to staging to hand a production release to a human') and an explicit limitation ('agents cannot promote to a protected environment themselves'). It does not name a sibling alternative for the actual promotion, but the when-to-use condition is unambiguous.

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

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

Annotations already flag destructive=true, openWorld=true and idempotent=false, and the description adds material context beyond them: every call creates a new bundle revision that replaces the live one, there is no automatic rollback (manual undo via republishing old values), production environments are refused, and signing occurs before CDN upload. This is exactly the behavioral detail an agent needs before mutating live traffic.

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 tightly packed sentences, front-loaded with the what, then prerequisites, then the undo/rollback story, then the production restriction and return payload. No sentence is redundant; each carries a distinct operational fact.

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?

Covers what the tool does, prerequisites, irreversibility and rollback, environment restrictions, and even the return payload (per-locale status and published_at) despite there being no output schema. 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% for the single 'locales' parameter, so the schema already explains the comma-separated format and the omit-to-publish-all behavior. The description adds nothing about the parameter, which is acceptable but not value-adding; 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 precise verb and resource ('Make the active environment's current server strings live') and enumerates the mechanism: builds per-locale bundles, Ed25519-signs them, uploads to the CDN. It also implicitly separates this from airstrings_push and airstrings_promote_preview by describing what publishing actually does.

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 ('run airstrings_push first for local edits'), how to undo ('set the old values and publish again'), and when this tool is the wrong choice ('Refused on a protected environment (production): publish to staging, then use airstrings_promote_preview and hand the apply_url to a human'). Names the alternative sibling and the condition that selects it.

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

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

Annotations flag destructiveHint=true and readOnlyHint=false, but the description goes further by naming exactly what is destroyed (unpushed local edits in the target CSVs) and clarifying that the operation is read-only on the server despite the destructive local effect. It also discloses the return payload (string, section, file counts), which the annotations do not.

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 destructive warning before the routing guidance, and every sentence carries distinct load: mutation semantics, safety caveat, alternative tool, and return values. 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 single-parameter, destructive local-write tool with no output schema, the description covers the safety profile, the alternative tools, and the return value shape. Nothing an agent needs to call it 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 description coverage is 100% and the single 'section' parameter is fully documented in the schema ('Only overwrite this section's CSV. Omit to pull every section.'). The description adds nothing beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource (download the active environment's strings into the local workspace) and defines scope precisely (overwriting local CSVs with the server state). It is immediately distinguishable from airstrings_push (upload) and airstrings_strings_ls (inspect without touching).

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 two alternatives and the conditions that select them: run airstrings_push first to preserve local edits, and use airstrings_strings_ls to inspect without modifying. Also frames the primary use case ('start from the server's state').

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 clarifies the destructiveHint by specifying server-only keys are left alone and nothing is deleted, discloses the protected-environment refusal, names the return payload (upserted and error counts, sections, failed keys), and notes changes are invisible until airstrings_publish. That is rich operational context an agent cannot get from the structured fields.

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

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

Front-loaded with the core action, then layered with write semantics, environment constraint, return shape, and sibling routing. Every sentence carries distinct decision-relevant information; there is no filler.

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

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

Despite having no output schema, the description enumerates the return fields, covers the destructive/mutation behavior, the protected-env refusal, and the publish dependency. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100% and the single section parameter is fully documented in the schema itself ('Only push this section's CSV'). The description does not add syntax or format detail for the parameter beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb (upload/upsert) and resource (local workspace CSVs to the active environment) and immediately defines the write semantics (overwrite server values, create missing sections). It distinguishes itself from siblings by name, contrasting with airstrings_strings_set, airstrings_publish, and airstrings_promote.

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

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

Gives explicit when-to-use ('after many airstrings_strings_set edits') and when-not ('for one key, strings_set with push=true is enough'). It also states the alternative path for protected environments ('push to staging, then a human promotes'), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add what they cannot: that no API key or secret is returned, that the output is safe to show the user, commit, and embed, and that the cross-environment key behavior means no production key is needed. These are substantive behavioral traits an agent could not infer from 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?

Two dense but front-loaded sentences; the safety/secret framing leads and the use case plus key-behavior note follow. It is efficient, though the long parenthetical enumerations of returned fields make it heavier than strictly necessary.

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

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

There is no output schema, so the description carries the return-value burden and does so by listing the concrete fields and artifacts returned (IDs, public keys, protection, per-platform initializers). Combined with the safety and auth notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the single 'env' parameter is already fully documented, including its default to production. The description references 'one environment' but adds no syntax or resolution detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource: returning public, non-secret SDK setup values for one environment, and it enumerates exactly what comes back (org/project/env IDs, Ed25519 public keys, protection state, initializers per platform). This distinguishes it from siblings such as airstrings_env_list or airstrings_init without needing to open their schemas.

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

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

It gives a clear use condition: 'Use it when wiring the AirStrings SDK into an app.' It also preempts a common auth question by explaining that any project API key works and a staging key returns production's config. It stops short of naming an explicit alternative tool or a when-not-to-use case, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: keys are returned masked and are removed via the revoke command, and the tool emits a single next-step recommendation. It does not mention auth prerequisites or freshness of the status snapshot, which keeps it short of 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 purpose, then the returned fields, then usage. It is a dense single paragraph, but every clause maps to a concrete behavior or routing decision; only the key-masking aside borders on incidental detail.

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

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

There is no output schema, so the description carries the burden of describing the return payload, and it does so field by field. For a zero-parameter, read-only diagnostic tool with routing guidance, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly implies a parameterless read-and-report call.

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

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

States a specific resource (workspace status) and enumerates exactly what it reports: project, active environment, key scope, per-environment protection, stored (masked) keys, and a suggested next step. It also explicitly distinguishes itself from the sibling airstrings_env_list.

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 trigger conditions ('call it first when unsure what to do next or why a write was refused') and an explicit alternative for a narrower need ('for just the environment list, use airstrings_env_list'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it reads local files rather than the API and therefore reflects unpushed edits, which materially affects how an agent interprets the results.

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

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

Two tight sentences, zero waste. The behavioral distinction (local files, not API) is front-loaded before the routing advice, so the most important disambiguation comes first.

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 compensates by naming the exact returned fields and the local vs. server data source. Combined with complete param coverage and rich annotations, an agent has everything needed to invoke and interpret the tool.

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

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

Schema coverage is 100% and the single optional 'section' parameter is fully documented in the schema, including omit-to-list-all behavior. The description adds no further syntax or format detail, 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 (List) and resource (strings in local workspace CSVs) and enumerates the returned fields (key, section, format, value per locale). It also draws the boundary against sibling tools by clarifying it reads files only, never the API, so an agent can distinguish it from server-side reads.

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

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

Explicitly states the use context ('shows unpushed edits') and routes to the alternative: 'run airstrings_pull first to see what the server currently holds.' The condition selecting this tool vs. airstrings_pull 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?

Goes well beyond the annotations by disclosing the local-vs-remote split, the protected-environment refusal, irreversibility, the return payload ('what was removed and whether it was pushed'), and the deferred effect on running apps until airstrings_publish. The annotations declare destructive/idempotent, and the description fills in the consequences and guardrails.

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 tight sentences, front-loaded with the action and scope, followed by the push behavior, irreversibility warning, and return value. No filler or repetition.

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

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

With no output schema, the description still covers the return value, the mutation's reversibility, the local/remote distinction, and the downstream publish dependency. An agent has everything needed to call this safely.

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 real meaning: the push flag's environment-level effect and its protected-env restriction, and that omitting locale removes the whole key. It does not restate syntax the schema already provides.

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 precise verb and resource with scope: 'Remove a string key, or one locale of it, from the local workspace CSV.' It also implicitly distinguishes itself from airstrings_strings_set by contrasting removal with re-setting, and from airstrings_push by describing the push=true flag.

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

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

Gives clear conditions: local-only by default, push=true also deletes in the active environment, refused on a protected environment, and deletion can only be undone by setting the string again. It stops short of naming the sibling tool (airstrings_strings_set) to use for restoration or airstrings_publish for propagation.

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: discloses merge semantics (overwrites given locales, keeps others), that writes are local unless push=true, that a protected environment refuses the push and rolls back the local change, and what is returned. The destructiveHint=true annotation is consistent with 'Overwrites'.

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, then behavior, then routing guidance, with no filler. The long middle sentence packs several clauses but each carries distinct operational information.

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

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

For a mutation tool with no output schema, the description covers write scope, push/publish lifecycle, rollback behavior, and the return shape, leaving no material gap 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 baseline is 3, but the description adds real value: the CSV path layout, the sectionless fallback file, and section creation on push. These clarify how section and push interact beyond the field-level text.

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

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

States a specific verb and resource ('Add or update one string key') and pins the exact target file, distinguishing it from siblings like airstrings_strings_rm and airstrings_push. An agent can select 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?

Explicitly scopes usage ('Use this for a few keys; after editing many keys, run airstrings_push once instead') and notes that apps see changes only after airstrings_publish, naming the relevant 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 flag destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: the base string is overwritten, the action cannot be undone except by manually resetting old values, bundles are automatically republished, and it is refused on protected environments. This is exactly the operational consequence detail an agent needs before a destructive call.

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

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

Five tight sentences, front-loaded with the primary effect, then irreversibility, then the environment restriction, then return value and routing. Every sentence carries distinct decision-relevant information with 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?

Despite having no output schema, the description states what is returned (the experiment and per-locale publish results). Combined with the irreversibility warning, protected-environment restriction, and sibling routing, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, including the note that 'variant' is not 'control'. The description reinforces the meaning of 'key' and 'variant' in prose but adds no syntax, format, or constraint beyond the schema, so the baseline 3 applies.

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

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

Opening sentence names a specific verb (end/promote) and resource (A/B experiment for one string key) and states the precise effect: variant values become the base string, old values overwritten, bundles republished. It is clearly distinguishable from airstrings_variant_stop, which it explicitly contrasts.

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 timing guidance ('use it once a winner is clear') plus a named alternative with the condition that selects it ('to end the test without changing the base string, use airstrings_variant_stop'). It also states when the tool will be refused (protected/production environment) and what to do instead.

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

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

Goes well beyond the annotations: it discloses that the whole experiment is replaced (destructive scope), that it is written as a new draft, that every variant must be resupplied because the key's base string is the implicit control, and the two preconditions that cause refusal. The idempotent-by-replacement semantics are also explained, complementing idempotentHint=true rather than merely restating 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?

Three dense sentences front-load the operation and replace semantics, then preconditions, then the follow-up tool chain. No sentence is filler and nothing needed for correct invocation is repeated.

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, nested-object mutation tool with no output schema, the definition supplies preconditions, destruction scope, follow-up calls, and even notes that it returns the stored experiment. An agent has everything required to call it safely without additional discovery.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents key, variants (locale/value pairs, never 'control') and allocation weights. The description adds a genuine cross-parameter constraint — 'pass every variant each time' — that explains why the variants object must be complete on every call, which is not obvious from the schema alone.

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 pair and resource ('create or replace the A/B experiment') with tight scoping to a text-format string key in the active environment. It is clearly distinguishable from siblings like airstrings_strings_set and airstrings_variant_start without opening any schema.

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

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

Explicitly routes the agent: use airstrings_variant_status to read first, airstrings_variant_start then airstrings_publish to activate, and airstrings_variant_stop before re-running. It also states two hard refusal conditions (experiment running, protected environment), which is exactly the when-not guidance the rubric rewards.

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

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

Annotations declare the write/idempotency profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description goes well beyond them: it discloses the non-idempotent downstream effect (live after publish), the draft-only constraint, the validation requirement that every variant cover every locale, the environment refusal behavior, and the return value. Substantial added context.

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

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

Four sentences, each carrying distinct load: purpose, timing, preconditions, environment behavior, and return value. Front-loaded with the action, no filler or repetition.

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

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

Even without an output schema, the description states what is returned (the updated experiment) and covers the prerequisites, env restrictions and lifecycle effects an agent needs to invoke it correctly. Nothing material is missing for a one-parameter tool.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents 'key'. The description adds only the framing 'one string key so its variants are served', which does not meaningfully extend the schema semantics. 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 (start) and resource (draft A/B experiment for one string key) and clearly distinguishes itself from siblings airstrings_variant_set, airstrings_variant_stop and airstrings_variant_promote. An agent can tell exactly which lifecycle operation this is 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?

Explicit prerequisites (only a draft can start, invoked after airstrings_variant_set), a stated condition for failure (protected/production environments are refused), and a concrete alternative action (start it in a writable environment instead). Timing guidance ('takes effect after the next airstrings_publish') is also given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful context beyond annotations: it describes the error condition when no experiment exists and enumerates the return fields, though it does not mention auth or rate limits.

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

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

Two sentences, front-loaded with the core action and scope, followed by usage guidance. Every sentence earns its place with no redundancy.

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

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

For a simple read tool with one parameter, rich annotations, and no output schema, the description covers purpose, usage context, error behavior, and the shape of returned data. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the single 'key' parameter is fully documented in the schema. The description only restates the key scope ('one string key'), adding no syntax or format detail beyond the schema. 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 verb (Read) and resource (the A/B experiment for one string key in the active environment), and enumerates the returned fields (status, allocation, variant values). This clearly distinguishes it from sibling tools like airstrings_status and airstrings_variant_set.

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 when to use it (before airstrings_variant_set to keep existing variants, or before start/stop/promote to check state) and names the relevant alternative tools. Nothing is left to inference.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds real behavioral context beyond them: the change is deferred until the next airstrings_publish, the stop is irreversible (cannot restart), it can still be promoted afterwards, and it is refused on protected environments.

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, zero filler, and the primary effect (what stopping does to users) is front-loaded ahead of the state-transition caveats and the alternative-tool routing.

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, stating 'Returns the updated experiment' is useful, and the irreversible state transition plus the protected-environment refusal cover the failure modes an agent needs before invoking this.

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?

One parameter with 100% schema description coverage, so the schema already explains 'key'. The description only restates scope ('one string key') without adding format, validation or example detail, 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?

Specific verb (stop) plus resource (a running A/B experiment) plus scope (one string key). It is clearly distinguishable from siblings airstrings_variant_set, airstrings_variant_promote and airstrings_variant_start, all of which are named or implied.

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 routing guidance: use airstrings_variant_promote to keep a winning variant, airstrings_variant_set creates a new draft if you need one, and it is refused on protected environments. The when-not condition (protected env) and the alternatives are both stated.

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