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

With no annotations, the description carries the full behavioral burden, and it does so well by enumerating exactly what is returned, including the protected/open distinction and the active-environment flag. It does not state that it is read-only or whether auth is required, but for a zero-parameter listing the side-effect risk is minimal.

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

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

A single front-loaded sentence that packs the essential scope and return fields with no filler. The run-on enumeration of attributes is dense but every element is informative and 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?

With no output schema present, the description compensates by listing the returned fields in detail, which is precisely what an agent needs. For a zero-parameter read-only listing it is essentially complete, missing only explicit authentication requirements.

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

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

The schema has zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter semantics because none exist, and nothing is misrepresented.

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 names the specific resource (every environment of the project) and the exact attributes returned (name, ID, default, protection, key presence, active). The CLI equivalence 'same as `airstrings env`' anchors the intent clearly. It does not explicitly differentiate itself from siblings like airstrings_status or airstrings_variant_status, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the many airstrings_* siblings. Usage is only implied by the listing nature of the tool, so an agent must infer the trigger conditions on its own.

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 no annotations, the description carries the full burden and does a solid job: it discloses the credential fallback order (env vars, then stored login), the 'pending' status with an out-of-band approval step, the need to re-call, and the side effect that an org key creates a project named after the folder. It stops short of stating permission requirements or what a successful response returns.

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

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

Three dense sentences with the core purpose front-loaded and no filler. Every clause carries information, though the middle sentence is somewhat packed and could be split for readability.

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 six-parameter, zero-required tool with no output schema and no annotations, the description covers the credential flow, the interactive approval detour, and project-creation semantics well. The main omission is an indication of what a successful (non-pending) call returns, which the absent output schema would otherwise have supplied.

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 genuinely adds semantics the schema lacks: how api_key interacts with the env-var fallback, and how project suppresses the default naming (folder/repo name) when an org key is used. These are behavioral relationships between parameters, not just restatements.

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

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

The opening sentence gives a specific verb and resource ('Bind a directory to an AirStrings project'), which is far better than a restatement of the name. It does not, however, distinguish itself from the sibling airstrings_login even though both appear to touch the same stored-login/verification flow, leaving potential ambiguity for the agent.

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?

Operational guidance is present (auth precedence chain, the pending/verification_uri_complete approval loop, re-calling afterwards), which tells the agent how to complete the flow. But there is no explicit when-to-use-this-vs-alternatives statement, and given airstrings_login sits in the sibling list with overlapping auth behavior, that gap matters.

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 no annotations, the description carries the full burden, and it discloses the key non-obvious behavior: the call returns a pending status requiring owner approval before re-invocation. It does not say where the org key is stored, whether the first call has side effects before approval, or what happens on denial.

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 compact sentences with no filler; the core action is front-loaded. The second clause is dense and slightly awkward in its compression, 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?

With no annotations and no output schema, the description must convey behavioral context, and it covers the critical two-step approval flow well. Missing details about key storage location and failure modes are minor for a login 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%, so both parameters (org, base_url) are already documented in the schema. The description adds no meaning about the org ID or base URL beyond what the schema states; 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 outcome: 'Log in and store an org key.' An agent can understand the core action. However, it does not differentiate itself from the sibling airstrings_init, which plausibly also establishes credentials, so identification rests on the name alone.

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

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

The description implies a usage sequence by saying to call again after an owner approves verification_uri_complete, which is genuine procedural guidance. It gives no explicit when-to-use versus when-not-to-use, and never routes the agent between this and airstrings_init.

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 no annotations, the description carries the full burden and does well: it declares read-only semantics, states no changes are applied, and names the apply_url handoff point. It also sketches the return content (added/updated/extra keys per locale), though it does not cover failure modes or env-equality edge cases.

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

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

Two tight sentences with no filler; the read-only nature and the no-side-effect guarantee are front-loaded before the handoff 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?

For a preview tool with no annotations or output schema, the description is nearly self-sufficient: it explains that nothing is applied, what the diff contains, and where the human applies it. Only the exact return shape and error behavior remain unspecified.

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

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

Schema description coverage is 100% and both parameters document themselves, including default behavior when omitted. The description only implies the source/target environment roles, so the baseline of 3 is correct.

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-only diff') and resource ('promoting strings from one environment to another'), and enumerates the diff contents (added, updated, extra keys per locale). It also distinguishes itself from the apply path by stating it applies nothing, which separates it from sibling airstrings_variant_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?

Implies the usage context clearly: preview first, then a human applies at apply_url in the dashboard. It does not explicitly name a sibling tool as the alternative apply route, so a 4 rather than a 5, but the when-to-use 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?

With no annotations, the description carries the full burden. It discloses one useful side effect (bundles are signed and delivered to SDKs), but says nothing about whether publishing is destructive or reversible, whether it affects production/CDN caching, or what auth/permissions it needs. For a mutation tool this is a substantial 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?

Two short sentences, front-loaded with the core action ('Publish bundles to the CDN') before the secondary detail. No filler; every sentence earns its place.

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

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

For a mutation/publish tool with no annotations and no output schema, the description is only minimally adequate. It covers the main effect but omits safety/reversibility, prerequisites, and any sense of scope (target environment, CDN, effect on deployed SDKs), leaving an agent to guess.

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 optional 'locales' parameter is fully documented in the schema, including the default-all behavior. The description adds no additional syntax or format meaning, 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 and resource: 'Publish bundles to the CDN', and adds a clarifying clause that bundles are signed and delivered to SDKs. This tells an agent what the tool does, but it offers no differentiation from close siblings like airstrings_push or airstrings_promote_preview, which likely also move/ship content.

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 no when-to-use guidance, no prerequisites, and no alternatives. It never says when to choose publish over push or promote_preview, nor what state must exist before publishing. The only conditional ('if omitted, publishes all') lives in the schema, not the description.

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 no annotations, the description carries the full burden, and it does disclose the critical trait that local CSVs are overwritten by remote state. However, it omits auth requirements (a separate airstrings_login tool exists), whether local-only strings are lost, and whether the operation is reversible or confirmable.

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, with the destructive overwrite warning front-loaded ahead of any procedural detail. Nothing could be removed without losing 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 sync operation with no output schema and no annotations, the description covers what happens to local CSVs but leaves gaps around authentication, partial-section behavior, and how the agent should confirm success or handle the overwrite.

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 optional 'section' parameter is already documented as a scope filter with 'If omitted, pulls all.' The description adds no additional semantics about section naming or format, 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 ('Pull strings from the AirStrings API') plus the destination ('into the local workspace'), which cleanly separates it from the push/publish siblings by direction of data flow. It does not name a sibling explicitly, so it falls just short of the top band.

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

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

The description never says when to use this versus airstrings_push, airstrings_status, or airstrings_strings_ls, nor whether login (airstrings_login) is a prerequisite. Usage must be inferred entirely from the direction of the sync.

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 no annotations provided, the description carries the full burden, and it does disclose real behavior: upsert semantics per key/locale and automatic remote section creation. It omits other mutation-relevant traits such as overwrite/conflict behavior for remote-only keys, authentication requirements (airstrings_login is a sibling), and error or partial-failure handling.

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 earning its place: the action, the write semantics, and the side effect. 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 mutation tool with no annotations and no output schema, the description covers the essential write behavior but not the surrounding contract an agent needs — auth prerequisites, failure modes, or what happens to keys that exist remotely but not locally. Adequate but with clear gaps.

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

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

Schema coverage is 100% and the single optional 'section' parameter is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the parameter beyond what the schema states, though it does confirm the mutation is all-sections by default.

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 ('Push local workspace strings to the AirStrings API') and clarifies the write direction, which implicitly distinguishes it from the opposite-direction sibling airstrings_pull. It never names a sibling or scope boundary explicitly, so differentiation is left to inference.

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

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

No when-to-use guidance, no prerequisites, and no routing to alternatives such as airstrings_publish, airstrings_pull, or the variant tools. The only usage signal is the schema-level note that the section parameter can narrow the push, which the schema already carries.

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 no annotations, the description carries the full burden and does substantial work: it declares no API key or secret is returned, that the public keys are verification keys rather than credentials, and that output is safe to expose/commit. It stops short of explicitly stating the operation is read-only or how invalid env values behave, keeping it just below a 5.

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

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

Two sentences, front-loaded with the tool's nature and non-safety immediately, then the return payload. Dense but each clause earns its place; the second sentence is long but not padded.

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

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

There is no output schema, so the description must explain return values — and it does, listing every field and the per-platform initializers. Combined with the safety framing, it is complete enough for an agent to call this 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?

Schema coverage is 100% for the single `env` parameter and the description adds little beyond it, only reinforcing the one-environment scope and the production default already documented in the schema. Baseline 3 is correct 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 resource (public, non-secret SDK setup values for one environment) and enumerates exactly what comes back: org/project/env IDs, Ed25519 public keys, protection state, and ready-to-paste initializers per platform. No sibling tool overlaps this scope, so an agent can select it 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?

It gives clear context for use — safe to show the user, commit and embed — and a useful precondition (any project API key works; a staging key returns production's config, so no production key is needed). It does not name an alternative or a when-not-to-use case, but no sibling competes for this job.

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 no annotations, the description carries the full burden and does so well: it makes clear this is a read/report operation, discloses that keys are returned masked, and notes that `airstrings apikey revoke` is the removal path. It does not state auth/permission requirements, which for a status command is a minor 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?

A single sentence that is front-loaded with the core purpose ('Workspace status') and then enumerates the payload in a predictable order. It is dense and slightly run-on with parenthetical clauses, but every clause earns its place by describing returned 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?

There is no output schema, so the description must describe the return shape, and it does: project, active environment, key scope, per-environment protection, masked keys, and the suggested next step. This is nearly complete for a zero-parameter read tool, though it omits any notion of error or empty-workspace states.

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 and the input schema is an empty object, so there is nothing to disambiguate; the baseline for zero parameters is 4. The description correctly adds no spurious parameter discussion.

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 with a clear verb-like intent ('Workspace status') and enumerates exactly what it reports, so an agent can tell this is a read-only workspace inspection tool. It does not, however, explicitly distinguish itself from the similarly named sibling airstrings_variant_status, which an agent might reasonably confuse it with.

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?

'Same as `airstrings status`' gives implied usage via the CLI analogy, and the mention of 'the one next step for this state' hints at diagnostic usage. But there is no explicit when-to-use vs alternatives guidance, particularly against variant_status or env_list, so the routing 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?

No annotations, so the description carries the full burden. It usefully discloses the data source (local CSV files rather than the API), which is the key behavioral trait, but says nothing about side effects, ordering, or return volume for a tool that scans files.

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 waste, and the scope/source constraint is front-loaded where an agent will read it 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?

For a single-optional-parameter read tool with no annotations and no output schema, the description explains where the data comes from but not what a result looks like or how failures (missing workspace, no CSV files) surface. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the 'section' filter is already documented as optional with its default behavior. The description adds no syntax, matching rules, or error behavior 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 (List) and resource (strings) plus the scope (local workspace), and disambiguates the data source (local CSV files, not the API). An agent can tell this is the read/list counterpart to push/pull/set/rm, though no sibling is named explicitly.

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

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

Usage is only implied: the 'local, not API' phrasing hints this is for inspecting local state rather than fetching remote data. It never states when to prefer this over airstrings_pull or what happens when the workspace is empty/uninitialized.

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 no annotations, the description carries the full burden, and it usefully discloses the dual local/remote behavior and that push acts immediately. However, it never states that removal is destructive or irreversible, whether it requires authentication, or what happens if the key does not exist — significant gaps for a delete operation with zero annotation coverage.

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, with the default behavior and the opt-in flag front-loaded. Every clause earns its place.

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

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

For a four-parameter destructive mutation with no annotations and no output schema, the description covers the core behavior but omits error handling, idempotency, and auth requirements. Adequate as a minimum viable definition, 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 description coverage is 100%, so all four parameters are already documented in the schema, making 3 the baseline. The description reinforces push semantics and the local default but adds no syntax or format detail for key, locale, or section beyond what the schema already says.

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 (remove) and resource (a string in the local workspace CSV), and the local-vs-API clause distinguishes it from a plain sync tool like airstrings_push. It does not name any sibling explicitly, so it falls just short of the top band.

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

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

Gives a clear default ('local by default') and an explicit condition for the alternative behavior ('set push=true to also mirror the removal to the API immediately'). No exclusion guidance such as when to prefer airstrings_push or strings_set instead, so it stops short of 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?

With no annotations, the description carries the full burden: it does disclose write targets, the local-first default, and the push escape hatch. However, it never says whether 'update' replaces or merges existing locale values, what permissions/auth are needed, or what happens on write failure, leaving meaningful mutation semantics 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?

Two compact sentences, zero filler, and the primary action and its destination are front-loaded before the optional push behavior.

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 5-parameter mutation tool with no annotations and no output schema, the description covers the essential write behavior but omits merge-vs-replace semantics, auth prerequisites, and error behavior an agent would need to invoke it confidently. It is adequate but 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 description coverage is 100%, so the schema already documents all five parameters including the section fallback and push behavior. The description restates the push flag and file destinations without adding new format or syntax detail beyond what the schema provides, which is the expected 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 states a specific verb+resource pair (add or update a string in the local workspace CSV) and even names the destination files, so an agent immediately knows this is the write path for individual strings. It doesn't explicitly contrast itself with siblings like airstrings_strings_rm or airstrings_push, which keeps it short of a 5.

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

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

It gives a clear conditional for a real decision point: local write by default, with push=true adding an immediate API sync. It does not name alternatives (e.g., airstrings_push for bulk syncing) or state when not to use it, 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?

With no annotations, the description carries the full burden. It usefully discloses the environment guardrail (refusal in protected production) and hedges that it 'does not promise success', which hints at possible no-op or asynchronous behavior. But it omits permissions/auth requirements, reversibility, and what happens to the non-winning variants.

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

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

Three short sentences, front-loaded with the action, then the failure condition, then the caveat. No filler and no repetition of 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?

A mutation tool with no annotations and no output schema needs the description to carry more than it does. It covers the key operational hazard (protected production refusal) but is silent on auth needs, reversibility, and the fate of competing variants.

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 both key and variant are already documented in the schema. The description adds the notion that the variant becomes the 'winning value', which gives mild conceptual context but no new syntax or format detail. 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?

States a specific verb and resource: promote one variant of a string's experiment to become the published value. That is clear enough to distinguish from siblings like airstrings_variant_set or airstrings_variant_start, though it never names the closely related airstrings_promote_preview.

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 concrete condition for failure and a corrective action: if the active environment is protected production the server will refuse, so promote in a writable environment instead. It lacks explicit routing to the sibling alternatives (promote_preview, publish), 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?

With no annotations, the description carries the full burden, and it does disclose the important destructive trait: 'Replaces the whole experiment,' so an agent knows this is an overwrite, not a merge. It does not mention required permissions, whether the experiment must be stopped first, error behavior for unknown keys, or what is returned.

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, with the create-or-replace action front-loaded and the destructive scope stated immediately after. No filler or redundant restatement of the tool name.

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 nested-object mutation tool with no annotations and no output schema, the description covers the data shapes and the replace semantics but omits lifecycle prerequisites, permission needs, and failure behavior. It is adequate to attempt a call but leaves meaningful operational questions unanswered.

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 nested parameters are already documented in the schema with examples, so the baseline is 3. The description restates the same mappings (variant name to integer weight; variant name to locale=value pairs) without adding format details, defaults, or validation rules 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 phrase ('Create or replace') and resource ('the A/B experiment for a string key'), plus the scope ('in the active environment'), which separates it from lifecycle siblings like variant_start, variant_stop, and variant_promote. However, it never names or contrasts with those siblings, so the differentiation is implied 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?

The description says what the tool does but gives no when-to-use or when-not-to-use guidance, and no routing to alternatives such as airstrings_variant_start, airstrings_variant_stop, or airstrings_variant_promote. An agent must infer from sibling names alone whether it should set up, start, or promote an experiment.

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 no annotations, the description carries the full burden, and it does disclose a non-obvious failure mode (refusal in protected production) and outcome uncertainty ('does not promise success'). It still omits idempotency behavior, required permissions, and what a successful invocation yields, so it is not fully complete.

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 doing work: purpose first, then the environment failure/goto, then the outcome caveat. No filler, though 'Does not promise success' is slightly cryptic phrasing for what it conveys.

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 mutation with no annotations and no output schema, the description covers purpose, a key failure condition, and success non-guarantee. Missing return/confirmation behavior keeps it from being fully self-sufficient, but nothing critical for invocation is absent.

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 schema description coverage is 100%, so the schema already documents 'key'. The description adds the intent (the key identifies the experiment being started) but no format, constraint, or validation detail beyond the schema; 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 ('Start the A/B experiment for a string key') plus the effect ('so its variants are served'), which makes the action distinguishable from stop/set/promote/status siblings. It stops short of explicitly naming a sibling it is not, so it lands at 4 rather than 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 clear negative condition ('if the active environment is protected production, the server will refuse') and an alternative course of action ('start the experiment in a writable environment instead'). That is real when/when-not guidance, though it routes by environment rather than by sibling 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the return content (status, allocation, variants) and that it reads the 'active environment', which is useful context, but it says nothing about permissions/auth needs or what happens when no experiment exists for the key.

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 tight sentence, front-loaded with the verb, with the return fields called out in a parenthetical rather than a separate sentence. No wasted words.

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 no annotations, the description partly compensates by naming the returned fields (status, allocation, variants) and the environment scope. For a single-parameter read tool this is close to sufficient, though the empty/no-experiment case and return shape remain unspecified.

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

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

Schema description coverage is 100% with a single 'key' parameter already documented as 'the string key whose experiment to read'. The description adds little beyond confirming the key targets a string and that resolution happens in the active environment, 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 ('Get'), a specific resource ('current A/B experiment for a string key'), and a scope ('active environment'). It is clearly variant-experiment-specific, implicitly distinguishing it from the general airstrings_status and the mutation siblings (variant_set/start/stop), though it never names them explicitly.

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

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

Usage is implied by the read verb and the phrase 'current ... in the active environment', but there is no explicit when-to-use, when-not-to-use, or routing against airstrings_status or airstrings_strings_ls. An agent must infer that this is the read counterpart to the variant mutation tools.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the post-stop serving behavior ('Serving reverts to the base string'), which is the most important outcome. It does not say whether experiment data/metrics are destroyed, whether the stop is reversible or restartable, or what error occurs if no experiment is running.

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

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

Two short sentences with zero filler. The action is front-loaded and the consequence follows immediately, which is exactly the right ordering for an agent scanning tool choices.

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 one-parameter mutation with no annotations and no output schema, the description covers what the tool does and its observable effect. The remaining gap is error/permission behavior and the fate of experiment data, which is minor given the tool's simplicity but would be worth one more clause.

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, so the schema already documents 'key' as 'The string key whose experiment to stop.' The description's phrase 'for a string key' adds no meaning beyond that, making the baseline of 3 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 the A/B experiment for a string key.' This is the clear inverse of sibling tools like airstrings_variant_start and airstrings_variant_promote, though no sibling is named explicitly. An agent can identify the operation without opening the schema.

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

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

Usage is implied by the verb: use this to end an experiment rather than start or promote one. However, there is no explicit when-to-use statement, no mention of prerequisites (e.g., an experiment must be running), and no named alternatives among the many variant_* siblings. The routing is inferable but not stated.

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