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

Annotations only carry destructiveHint=true, and the description adds substantial non-obvious behavior: the operation is reversible, it is refused under two named conditions, and archiving causes every caller to fall back to its own hardcoded default. The explanation of why FLAG_RECENTLY_EVALUATED fires and when it self-clears is exactly the kind of context annotations cannot provide.

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

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

Front-loaded with the core action and free of filler; every sentence carries error-handling or workflow information. It is delivered as one dense run-on paragraph, so error codes and the dependents workflow are harder to scan than they could be.

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

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

Output schema exists so return values need no explanation, and the description still covers the mutation's semantics, reversal, both refusal conditions and their resolution, and the prerequisite-tool workflow. Nothing an agent needs to invoke this correctly in the right order is missing.

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

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

Schema coverage is 100%, so both 'project' and 'flag' plus the 'force' override are already documented in the schema. The description corroborates the 'force' rationale (traffic that will never drain) but adds no syntax or format detail beyond it, 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 (archive) and resource (flag) and immediately defines the semantics with 'soft-hide, evaluation stops serving it', which distinguishes it from delete_flag and restore_flag. An agent can tell exactly what state change this performs.

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

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

Gives concrete when-not conditions (FLAG_HAS_DEPENDENTS, FLAG_RECENTLY_EVALUATED) and points to the exact sibling tools to run first (find_stale_flags / list_removal_candidates via blockedBy) and the reversal path (restore_flag). It does not explicitly contrast archive vs delete_flag, which is the one obvious alternative 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 destructiveHint=false, so the description carries the behavioral load and does add real context: the flag is created in every environment of the project and starts disabled, and Boolean flags auto-generate true/false variations. It omits permission/auth requirements and rate-limit behavior, but the environment-wide disabled-by-default trait is a genuinely useful disclosure.

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

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

Three tight sentences, front-loaded with the core action, and each sentence earns its place by conveying type rules or creation scope. No filler or restated 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?

An output schema exists, so return values need no explanation. For a 12-param creation tool the description covers scope and variation semantics well; the main omission is any note on authorization or idempotency behavior, though idempotency_key is documented in the schema.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented, giving a baseline of 3. The description reinforces the type enum and the Boolean-vs-initialVariations relationship, but adds no syntax or format detail beyond what the schema already states.

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 opens with a specific verb+resource ("Create a feature flag"), which is inherently distinguishable from sibling mutators like update_flag, delete_flag, and archive_flag. It stops short of naming any sibling explicitly, but the create semantics are unambiguous.

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

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

There is no when-to-use vs when-not guidance. It never points the agent to update_flag, manage_variation, or set_flag_owner for follow-up work, nor states prerequisites. The type/variation rules are parameter mechanics, not usage routing.

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

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

Annotations already declare destructiveHint=true, so the safety bar is partly covered; the description goes further by disclosing cross-environment blast radius and a concrete failure condition with its error code (FLAG_HAS_DEPENDENTS if used as a prerequisite). It stops short of covering permissions/auth requirements or whether the deletion is reversible/recoverable via restore_flag.

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, no redundancy: the destructive action and scope lead, the failure mode follows, and the alternative is last. 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 two-parameter destructive tool with an output schema present (so return values need no explanation), the description covers scope, irreversibility framing, failure mode, and the preferred alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

Both parameters ('project', 'flag') carry schema descriptions at 100% coverage, so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema already documents, making the baseline 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?

States a specific verb and resource ('delete a flag') plus a critical scope qualifier ('PERMANENTLY ... across all environments'), which sharply differentiates it from archive_flag and restore_flag in the sibling list. 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 names the alternative ('Prefer archive_flag') and states the condition that selects this tool instead ('unless the flag must be fully removed'). Both the when and the when-not are present.

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 cover openWorldHint and destructiveHint=false, but the description adds substantial operational context: asynchronous delivery, need to read list_webhook_deliveries for the result, Admin-token requirement, refusal conditions, and the 404-means-webhooks-disabled signal.

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

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

Front-loads the action semantics, then layers async behavior, failure conditions, and auth. Every clause carries information; no filler despite the density.

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?

An output schema exists so return format needn't be explained, and the description covers auth, refusal states, async outcome polling, and the org-level 404 case. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real value by identifying the source of deliveryId (list_webhook_deliveries) and clarifying that test targets this subscription alone. It reinforces rather than merely repeats 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+resource and disambiguates the two action modes ('test queues one synthetic flag.toggled event to this subscription alone'; 'redeliver ... re-sends a finished delivery'). An agent can tell exactly what each call does and how it differs from siblings like list_webhook_deliveries.

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 maps each action value to its use case and prerequisite (deliveryId from list_webhook_deliveries for redeliver), names the sibling to poll for outcomes, and gives when-not conditions (refused for disabled subscriptions; redeliver refused while delivery is Pending).

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavior: permanent flags (kill switches, ops toggles) are never listed, at most 50 candidates are checked per call with expired flags first, and blockedBy=null means 'unknown, not unblocked'. It also discloses the downstream failure mode (archive_flag fails with FLAG_HAS_DEPENDENTS if a dependent still names the flag), which is exactly the kind of cross-tool behavior an agent needs.

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

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

The purpose and core criteria are front-loaded, which is good, but the body is a dense single paragraph, and a sizeable chunk enumerates result fields (expiresAtUtc, effectiveExpiresAtUtc, expirySource, expired, owner) that the output schema already defines. Those sentences do not earn their place as strongly as the criteria, cap, and dependency-ordering content.

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

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

For a complex triage tool, the description covers the stale predicate, expiry and project-default lifetime rules, permanent-flag exclusion, owner filtering, the 50-candidate cap and ordering, and the prerequisite/dependency constraint that governs follow-up archival. With an output schema handling return values and annotations covering safety, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description restates them at the same level of detail ('not updated in N days', owner 'me'/'none', project key) without adding syntax, format, or edge-case meaning. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The opening sentence names a specific verb and resource ('Find flags that look ready for code cleanup') and then defines the exact predicate that makes a flag stale: N days without update AND either on in every environment or off in every environment, plus the overrides for expired flags. An agent can tell precisely what this tool returns without opening the schema, though it does not explicitly contrast itself with the nearby list_removal_candidates sibling.

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

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

It gives clear operative context: run this to identify cleanup candidates, filter with owner ('me'/'none'), and it warns to verify rollout is complete before removing. It also explains the removal workflow ordering versus archive_flag (dependents first, FLAG_HAS_DEPENDENTS otherwise), which steers correct usage. However, it never states when NOT to use it or names an alternative tool for overlapping needs.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful detail that the view is 'compact' and lists which facets are returned, but says nothing about auth requirements, environment coverage limits, or pagination behavior.

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

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

A single tight sentence that front-loads the scope ('cross-environment view') before enumerating returned fields. No wasted words, though it is a sentence fragment rather than full prose.

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 an output schema present, return values need no elaboration, and the readOnly annotation covers safety. Parameters are fully described in the schema, so the description is nearly complete; only routing guidance versus get_flag 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% (both 'flag' and 'project' documented), so the baseline is 3. The description adds no format or identifier-syntax detail beyond what 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 specific resource (one flag) and a specific scope (cross-environment), with the returned facets named: enabled state, strategy, default variation, prerequisites. This distinguishes it from the single-environment get_flag sibling, though it never names that sibling 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?

The phrase 'cross-environment view of one flag' implies the use case (comparing a single flag's configuration across environments), but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_flag or update_flag_environment_config.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the nuance that owner is null when unowned, which is genuinely useful, but otherwise restates the return shape that the output schema already defines. No error/not-found behavior is disclosed.

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 tight sentence with the resource and return contents front-loaded and no filler. Every clause carries information (what is returned, owner semantics, addressing mode).

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

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

For a simple read-only getter with an output schema covering return values and annotations covering safety, the description supplies everything else an agent needs. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so both parameters (flag, project) are already documented. 'Address by flag key or id' merely repeats the schema's own 'Flag key or id' text and adds no new format or constraint 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 and resource ('Get one feature flag') plus the payload it returns (variations, metadata, owner). The word 'one' implicitly contrasts with list_flags, but no sibling is named explicitly, so differentiation is inferred rather than stated.

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

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

Usage is implied by 'Address by flag key or id' — the agent can infer this is the single-flag lookup rather than a list or mutation. However, there is no explicit when-to-use statement, no mention of when to prefer list_flags or flag_status, and no prerequisites (e.g. needing a valid project key).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that the response covers conditions, id, and metadata, which is mild value, but says nothing about not-found behavior or required permissions.

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, front-loaded with the verb and resource, with the lookup keys trailing. No filler or redundancy.

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

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

For a two-parameter read tool with a full output schema and readOnly annotation, the description covers purpose and lookup keys adequately; return values need not be explained. Only error/not-found handling is unaddressed, a minor gap.

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

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

Schema description coverage is 100% and both parameters are documented ('Project key', 'Segment key or id'). The description's 'by key or id' merely restates the schema's own wording rather than adding new meaning, 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 and resource ('Get one user segment') with singular scope and the lookup keys, which implicitly separates it from list_segments and manage_segment. It does not explicitly name or contrast a sibling, 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?

The description gives no when-to-use guidance, no exclusions, and never mentions the alternative list_segments or manage_segment. An agent must infer from the tool name alone that this is the single-item read path.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful scope detail that it returns the enabled flag plus ordered rules for a single environment, but it does not cover return format or whether ordering is significant beyond what the schema/output schema implies.

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

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

A single front-loaded sentence with no filler, immediately stating the verb, resource, and returned content. 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?

With an output schema present, the description needn't explain return values, and the three required params are covered by the schema. It is complete enough for an agent to call correctly, though it lacks explicit routing context versus targeting siblings.

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 three parameters (project, flag, environment) are documented in the schema, meeting the baseline of 3. The description's phrase 'in one environment' reinforces the environment scoping but adds no format or syntax detail 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 (Get) and resource (a flag's targeting configuration), and clarifies the scope: enabled flag plus ordered rules, in one environment. This clearly distinguishes it from write siblings like update_targeting and manage_targeting_rule.

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 and names no alternatives. It neither says when to prefer update_targeting to modify rules nor states any prerequisites, so the agent must infer the read-only inspection use case from the verb alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the project-scoping constraint and illustrative environment names, but says nothing about pagination despite limit/cursor params, so it adds modest value.

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

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

A single short sentence with the purpose and scope front-loaded. Zero waste; 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?

An output schema exists, so return values need not be described, and full schema coverage handles params. For a simple read-only list tool this is nearly complete, lacking only the pagination/usage context an agent might want.

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 project, limit, and cursor. The description adds no syntax or format details beyond the schema and only clarifies the concept of an environment via examples; 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 (List) and resource (environments) scoped to a project, with parenthetical examples clarifying what an environment is. It implicitly differentiates from the sibling manage_environment, though it never names or contrasts with it explicitly, keeping it just 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?

The description says what the tool does but gives no when-to-use guidance, no prerequisites, and does not mention or contrast with the sibling manage_environment. Usage is only implied by the verb 'List'.

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 cover read-only safety, and the description goes beyond them by disclosing pagination mechanics ('Paginated via cursor') and the shape of the embedded owner object (including the null-when-unowned case). It does not mention default page size, rate limits, or ordering, but the pagination and payload notes are meaningful additions.

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 purpose and no filler. The owner-shape sentence is arguably closer to return-value documentation than parameter guidance, but it is compact enough to earn its place.

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

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

With an output schema present, the description needn't explain return values, and it nonetheless covers pagination and owner embedding. Combined with full schema coverage and read-only annotations, an agent has everything needed to call the tool; only ordering and default-limit behavior are unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the filter names and adds that search matches key/name substrings, but the field-level syntax (owner accepting 'me'/'none', the type enum, the limit cap) is all left to the schema.

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

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

States a specific verb and resource ('List feature flags in a project') plus the filterable surface, so it's clearly a paginated collection read rather than the singular get_flag. It does not distinguish itself from siblings like find_stale_flags or list_removal_candidates, which also return flag collections.

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 by the enumeration of filters; there is no statement of when to prefer this over get_flag or the specialized flag-listing siblings. An agent can infer the retrieval intent, but no alternative is named or excluded.

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

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

The readOnlyHint annotation already establishes this as a safe read operation, lowering the burden on the description. The description adds the pagination trait, but the cursor-to-next_cursor mechanics largely restate what the schema already documents, and it says nothing about ordering, rate limits, or result shape. It adds some context but not rich behavioral detail.

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

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

Two short sentences, with the core purpose front-loaded and pagination second. It is well-sized and wastes little, though the pagination sentence partly repeats the cursor parameter's schema description.

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?

An output schema exists, so return values need not be explained, and read-only annotations cover the safety profile. The description covers the one behavior an agent must know (pagination). Minor gaps remain around ordering and whether results are filtered, but nothing essential to invoking 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%, so the schema already documents both limit (default 20, max 100) and cursor. The description's cursor note duplicates rather than extends the schema's 'next_cursor from a previous response' text, and it adds no syntax or default details. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb (List) and resource (projects) and scopes it to the Featureflip organization, so an agent can tell it apart from manage_project by the read-only verb. It stops short of naming sibling alternatives or clarifying what distinguishes it from other list_* tools, but the purpose itself is unambiguous.

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

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

It provides concrete usage guidance for iteration (pass cursor from next_cursor to continue), which tells the agent how to page through results. However, there is no when-to-use guidance relative to siblings such as manage_project, and no exclusions or prerequisites are stated. Usage is implied rather than explicitly framed.

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

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

Annotations only declare readOnlyHint=true; the description adds substantive behavior beyond that — the semantic contract of each returned field, the blockedBy dependency signal, and why archive_flag will refuse a still-depended-on flag. This is real context an agent cannot get from the safety hint alone.

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?

Well front-loaded: the purpose and alternative-context come first, then item shape, then the critical removal rule. It is somewhat long and the treatment-field gloss leans on output-schema territory, but no sentence is pure 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?

Given a read-only, paginated list tool with a rich output schema and a non-obvious dependency-removal hazard, the description covers purpose, ordering, error behavior, and pagination. An agent has everything needed to list and safely act on 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%, so the baseline is 3, but the description adds meaning by clarifying the tiered semantics of staleness ("dead" returns only dead flags, "stale" adds stale ones) and noting cursor pagination. This nudges above the schema-only 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 opens with a specific verb+resource ("List the flags the server is confident can be removed from code") and pins the exact item shape (key, reason, status, treatment, blockedBy), clearly distinguishing this removal-oriented list from siblings like list_flags and find_stale_flags.

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

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

It states the operative rule ("Only remove a flag whose blockedBy is empty"), the ordering constraint (dependents first, prerequisites last), and the consequence of violating it, including the cross-tool interaction with archive_flag and its FLAG_HAS_DEPENDENTS error. This is explicit when/when-not guidance tied to a 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds a genuine behavioral fact beyond the annotations and schema: the full key is never returned and is visible only once at creation time. That is meaningful security-relevant context an agent needs before reporting results to a user.

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: the first front-loads what is listed, the second carries the security caveat. No filler, no 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?

An output schema exists, so return values need no prose explanation. Between the scope statement, the field enumeration, and the full-key caveat, nothing an agent needs to call and interpret this tool 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%, so project, environment, limit, and cursor are already documented in the schema. The description adds no extra syntax or format detail about those parameters, 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 (SDK keys), scopes it to "one environment", and enumerates the returned fields (id, name, type, last four characters, active status). It also names the sibling manage_sdk_key, so an agent can distinguish listing from creation 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?

The description scopes usage clearly to a single environment and explains the relationship with manage_sdk_key (the only place the full key appears). It does not spell out when-not to use this tool or mention pagination trade-offs, but the context is unambiguous for a list operation.

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

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

The readOnlyHint annotation already declares this a safe read, so the description carries a lower burden. It adds the domain relationship (segments feed targeting rules via userSegmentId), which is useful context, but says nothing about pagination or result size beyond what the schema's limit/cursor already imply.

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 zero filler; the purpose (what is listed and where) is front-loaded before the secondary 'why it matters' clause. 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 readOnlyHint annotations and a present output schema, the return values and safety profile are already covered, so the description does not need to explain them. It is complete for a simple three-parameter list tool, with only the absence of alternative-routing guidance keeping it from a 5.

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

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

Schema description coverage is 100%, so limit, cursor, and project are already fully documented in the schema, giving a baseline of 3. The description adds a small amount of meaning by framing segments as reusable and project-scoped, reinforcing the required project parameter, but adds no parameter syntax details.

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

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

States a specific verb (List), resource (reusable user segments), and scope (in a project), which distinguishes it from get_segment and manage_segment by the list-vs-single-vs-mutate verb. The second sentence adds conceptual context about how segments connect to targeting rules, though it never names the siblings 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?

No explicit when-to-use or when-not-to-use guidance; usage is only implied by the word 'List' and the note that segments are referenced from targeting rules. An agent can infer this is a discovery/enumeration call, but nothing tells it to prefer this over get_segment or when listing is appropriate.

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 readOnlyHint annotation, it discloses the auth requirement (Admin token), the meaning of the status values including the ambiguous 'Pending' case (awaiting, backing off, in flight), how to interpret failures via lastResponseStatusCode/lastError, and an org-level 404 troubleshooting rule. This is substantive behavioral context an agent cannot get from annotations or schema.

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

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

Four short, dense sentences with no filler: scope/ordering first, then status semantics, then pagination, then auth and the 404 diagnostic. 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?

An output schema exists, so return-field documentation is not required here; the description still covers the operational essentials (ordering, pagination, auth, failure interpretation, 404 troubleshooting). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a little by confirming cursor-based pagination flow and framing id as scoping to a single subscription. It adds no new syntax or format detail for limit or cursor beyond the schema, so it stays near 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?

States a specific verb and resource ('List one subscription's delivery attempts') plus ordering ('most recent first'), which cleanly separates it from the sibling list_webhooks (which lists subscriptions, not deliveries). An agent can pick this tool 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 clear context for when this is the right call — per-subscription delivery history — and adds operational guidance (Admin token required; a 404 across webhook calls means webhooks are disabled for the org). It never names an alternative such as list_webhooks or deliver_webhook, so the routing guidance is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: the Admin token auth requirement, cursor-based pagination, the 'never secret values' security guarantee, the empty-filter-means-all semantics, and how to interpret a 404. These are exactly the operational traits an agent needs and none are in the annotations.

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

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

Front-loaded with the core action and returned fields, and every clause (auth, pagination, 404 handling, secret redaction) carries information. The single dense run-on sentence with multiple parentheticals is slightly heavy, costing it the top score.

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

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

An output schema already covers return values, so the description correctly focuses on the things structured data doesn't convey: auth requirements, pagination mechanics, the 404/not-enabled condition, and the meaning of empty filter lists. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so both limit and cursor are already documented, making 3 the baseline. The description adds a small amount by confirming cursor pagination ties the two parameters together, but it introduces no new syntax or defaults beyond the schema's own 'next_cursor from a previous response'.

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 ('List the organization's outbound webhook subscriptions') and enumerates the returned fields (url, filters, enabled state, failure count, signing secret ids) plus the availableEventTypes payload. This clearly separates it from list_webhook_deliveries (delivery history) and manage_webhook (CRUD), though no sibling is named explicitly, which keeps it just below a 5.

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

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

Gives prerequisites (Admin token required) and a diagnostic rule (a 404 on every webhook call means webhooks are not enabled), which implies usage context. However, it never states when to reach for this versus list_webhook_deliveries or manage_webhook, so routing guidance 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?

With destructiveHint=true already declared, the description adds real context: the key is immutable after creation, the operation is a partial update rather than a replace, deletion is out of scope, and a new environment is inert until an SDK key is created. It does not mention permission/auth requirements, so it falls 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?

Four short sentences, each carrying distinct information, with the create/update contract front-loaded and constraints and next-step routing appended. 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?

An output schema exists so return values need no explanation, and the description covers mode selection, prerequisites, immutability, and the SDK-key dependency. The only soft spot is that 'changes only the fields you pass' implies a changes object while the schema exposes flat top-level properties.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond per-field docs by stating the cross-parameter coupling for each action and calling out that update only touches supplied fields, which tells the agent it may omit name/color/sortOrder. It does not clarify format expectations (e.g. hex color, sortOrder semantics) beyond the schema.

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

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

The first sentence names a specific verb+resource (create/change an environment in a project) and enumerates exactly which attributes are mutable (name, color, sort order). It is immediately distinguishable from siblings like list_environments or manage_sdk_key.

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 prerequisite per mode ('action=create needs key + name; action=update needs environment'), notes update is partial ('changes only the fields you pass'), and routes the agent to manage_sdk_key for the follow-up step. It also excludes an option the agent might otherwise try ('cannot be deleted from here').

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

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

The destructiveHint=true annotation is potentially over-broad for an update that 'only changes fields you pass,' but the description adds genuinely useful behavior beyond the annotation: key immutability, partial-update semantics, and that description: "" clears the field. This disclosure materially helps an agent avoid unintended overwrites, though it doesn't mention permissions or reversibility.

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 dense sentences with zero filler, front-loaded with the create-vs-update split before the finer semantics. Every clause carries actionable information.

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

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

An output schema exists, so return values need not be explained, and the description covers both action modes, their required params, and key immutability. It stops short of stating permission requirements or what happens to unspecified fields on update in edge cases.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's role and required-for-create/update status. The description's parameter notes (key immutable, "" clears description) largely mirror the schema text, adding only the partial-update framing.

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 (create/update a project) and immediately splits the two modes via the action enum values. It also bounds scope up front with 'Projects cannot be deleted from here,' which lets an agent distinguish it from a hypothetical delete/archive sibling. No sibling name is cited, but the create/update framing is unambiguous.

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

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

Gives explicit preconditions for each mode: action=create needs key + name, action=update needs project and only the passed fields change. It also rules out one capability (no deletion here). What's missing is routing to alternatives (e.g., list_projects for reads, or where deletion actually happens).

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?

Discloses key behavioral traits annotations don't: create returns the full key ONCE (critical irreversibility), revoke takes effect immediately and causes apps to lose flag updates, and rename only changes passed fields. These are exactly the mutation consequences an agent must know.

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 scope, each action paired with its consequence, ending with the rotation workflow. 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?

Covers create/rename/revoke behavior and rotation thoroughly; output schema exists so return values needn't be explained. Minor gap: doesn't mention listing keys to obtain sdkKey, though the schema notes list_sdk_keys.

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?

Adds meaning by tying params to actions (name+type for create, sdkKey for rename/revoke) and explaining type semantics. With 100% schema coverage this is somewhat redundant, but the action-param coupling adds value beyond schema descriptions.

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 ('Manage an environment's SDK keys') and itemizes each action (create/rename/revoke) with its effect. Clearly distinguished from list_sdk_keys (read) among siblings.

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

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

Explicitly maps each action to required params and gives a rotation recipe ('create a new key, deploy it, then revoke the old one'), telling the agent when to combine actions rather than revoke directly.

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

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

With only destructiveHint=true provided, the description carries real weight: it explains conditional writes via ifMatch (412 on concurrent modification, re-read and re-apply), that ifMatch is rejected on create/delete, that conditions replaces the entire list, and that an empty description string clears the field. These are non-obvious API behaviors beyond what annotations declare.

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?

Dense but every clause earns its place: action requirements first, then the concurrency/etag rule, then the negative constraint on ifMatch. No filler and the most decision-relevant content is front-loaded.

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

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

Output schema exists so return values need not be described. For an 8-parameter mutation tool with destructiveHint, the description covers the mutation surface, per-action parameter requirements, destructive replacement semantics, and optimistic-concurrency error handling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: which parameters are required per action value, and the create/update/delete-specific rejection of ifMatch. It also reinforces the replace-whole-list semantics of conditions.

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

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

Opens with a specific verb+resource ('Manage reusable user segments') and immediately distinguishes it from siblings by noting segments are referenced by userSegmentId by targeting rules. The title and description together make clear this is the write/mutation counterpart to list_segments/get_segment.

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 per-action requirements (create needs key+name; update needs segment+changes; delete needs segment) and routes the agent to get_segment for the etag used by ifMatch. It stops short of saying when to prefer this tool over alternatives in a workflow sense, but the action-level routing is clear and actionable.

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

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

Annotations supply only destructiveHint=true; the description carries the rest and does so meaningfully — update is a partial patch ('changes only the fields you pass'), conditionGroups is a full replace rather than a merge, and clearing a field is impossible here. That merge-vs-replace distinction is exactly the kind of behavioral detail annotations cannot convey. It stops short of permissions/auth or failure behavior, so not 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?

A single dense paragraph, but front-loaded with the core purpose and then ordered by action, so it is scannable. Every clause carries a constraint or an alternative; little waste, though the action-specific clauses could be broken into a list for faster lookup.

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

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

For a destructive mutation tool with a rich nested schema and an output schema, the description covers the mutation semantics, per-action requirements, and the escape hatch to a sibling tool. Return values are rightly omitted since an output schema exists. Only permission/error behavior remains unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter conditionality the schema does not: which params are required per action, that ruleIds must contain every existing rule id exactly once in evaluation order, and that conditionGroups overwrites groups. This is real semantic value beyond the per-field descriptions.

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 ('Edit a single targeting rule') and immediately scopes it against the sibling that replaces everything ('instead of replacing them all with update_targeting'). An agent can distinguish this from update_targeting and get_targeting 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 per-action routing: what each action value needs (rule, ruleId, ruleIds) and even when to fall back to a different tool (clearing rolloutPercentage or userSegmentId requires update_targeting). It also names get_targeting as the source of rule ids, so the agent knows the prerequisite call.

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

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

Beyond the destructiveHint=true annotation, the description discloses a concrete failure mode: removal fails with VARIATION_HAS_DEPENDENTS when other flags depend on it. That is useful operational context an agent could not infer from annotations or schema. It does not cover permission or rate-limit behavior, but destructive semantics are already signalled by the annotation.

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

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

Three compact sentences with zero filler. The core operation is stated first, then per-action parameter needs, then the notable failure mode — a well front-loaded structure.

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 an output schema present, return values need not be described, and the description covers action semantics and the dependency-failure case adequately. It omits what 'update' can modify versus the immutable key and how dependent flags should be handled, which are minor gaps for an 8-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 coverage is 100% and the action property already documents 'add needs key + value; update and remove need variationId', so the description's conditional mapping is largely redundant with structured data. The only added value is the pointer to get_flag as the source of variationId, which is marginal. 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 names a specific resource (a flag's variations) and enumerates the three operations the tool spans, matching the title. It is clearly distinguishable from siblings like create_flag, get_flag, or update_flag_environment_config. The generic verb 'manage' with a multi-action enum keeps it from 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 action-conditional guidance ('action=add requires key + value; action=update/remove require variationId') and routes the agent to get_flag to obtain ids, which is genuine cross-tool usage guidance. It stops short of explicit when-not-to-use or alternatives to this tool for variation editing.

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

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

Beyond the destructiveHint annotation, it discloses critical behavior: the secret is NEVER shown again and must be relayed verbatim, update changes only passed fields and empty lists widen filters back to 'all', an Admin token is required, project-restricted service tokens must list in-scope projects, and a 404 on every call means webhooks are disabled for the org. This is exactly the non-obvious 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?

It is a single dense paragraph front-loaded with action requirements, and every sentence carries actionable information. It is slightly run-on and could be bulleted per action, but there is no filler or redundancy.

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

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

For a 10-parameter multi-action mutation tool with an output schema, the description covers auth requirements, secret-return handling, action-specific prerequisites, edge cases (last active secret, 404/disabled org), and cross-tool references. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description still adds meaning: environment keys use '<project>/<environment>' format with an example, eventTypes originate from list_webhooks → availableEventTypes, and update's partial-update/empty-list-widens-to-all semantics are not in the schema. It repeats some schema content (empty = all) but the additions are genuine.

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

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

The title and description state the exact verb+resource for each of the five actions (create/update/delete/rotate_secret/retire_secret) and their required inputs, so an agent can tell immediately what the tool does. It is clearly distinguishable from siblings like list_webhooks and deliver_webhook.

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 per-action routing rules (create needs name+url; everything else needs id) and explicitly distinguishes the two secret actions: rotate_secret adds a new active secret while the old keeps signing, retire_secret removes one and is refused for the last active secret. It also points to list_webhooks for availableEventTypes and secretId, naming the alternative source.

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 destructiveHint=false, so the description carries most of the behavioral burden. It does not say whether targeting/config is preserved on restore, whether the call is idempotent, what error occurs if the flag is not archived, or what permissions are required.

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

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

A single short sentence with no filler, front-loaded with the action. It is efficient but nearly identical to the title, so brevity comes at the cost of substance rather than through tight editing of rich 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?

An output schema exists so return values need not be described, but for a state-mutating tool with only a destructiveHint annotation the description omits the effects of restoration, error conditions, and prerequisites. That leaves the agent under-informed about calling 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% (flag: 'Flag key or id'; project: 'Project key'), so the schema already documents both parameters. The description adds no meaning beyond the schema, which puts it at the baseline 3.

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

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

The description states a specific verb (restore) and resource (a previously archived flag), making the inverse relation to archive_flag inferable. However it adds nothing beyond the title and does not explicitly name the sibling it complements or the state transition it performs.

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

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

There is no guidance on when to use this versus archive_flag, delete_flag, or get_flag, nor any stated prerequisite such as the flag actually being archived. Usage must be inferred entirely from the name.

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

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

Goes well beyond the idempotentHint/destructiveHint annotations by disclosing that the setting is advisory only (evaluation never changes), that preview reports impact without mutation, and that setting can be refused with FEATURE_NOT_ENABLED when the plan lacks it while removal never is. These are exactly the behavioral traits an agent needs.

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

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

Front-loaded with the core action, then preview behavior, then error semantics, then a pointer to the current value. Dense but every sentence carries distinct, load-bearing 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?

For a 3-param mutation tool with an output schema, the description is near-complete: it covers the effect, preview, error condition, and where to read the current value. It slightly under-describes the preview output shape, though the output schema covers return values.

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 already documents days, null, and preview, so the baseline is 3. The description still adds semantic value: null means removal, and preview means counting flags that would newly be or stop being past expiry without changing anything, which clarifies intent beyond the schema wording.

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 ('Set how many days a temporary flag with no expiry date of its own lives before it counts as expired') and explicitly covers the inverse operation ('pass days: null to remove the default'). An agent can distinguish this from set_flag_expiry and set_flag_permanent 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?

Gives clear operational guidance: preview first to see the impact before committing, and notes removal is always allowed while setting may be refused. It does not name sibling tools or an explicit 'when not to use', so it stops short of a 5.

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

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

Goes well beyond the idempotentHint/destructiveHint annotations: expiry is advisory and never changes evaluation, find_stale_flags surfaces it once passed, and three named refusal codes (EXPIRY_IN_PAST, FEATURE_NOT_ENABLED, PERMANENT_FLAG_HAS_EXPIRY) are documented. Clearing-always-allowed is a genuinely useful behavioral guarantee.

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 core action and the null-clearing alternative, then layers semantics and error conditions in a tight sequence. Dense but every sentence carries operational information; nothing is padding.

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

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

With an output schema present, return values need no explanation, and the description covers formats, failure modes, and the interaction with set_flag_permanent. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, but the description adds meaning: a bare date resolves to end-of-day UTC (matching the dashboard), while a full ISO-8601 timestamp is stored exactly. This disambiguates the two accepted formats beyond the schema's terser note.

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+resource ('Set the date a flag is expected to be removed by'), plus the clearing variant via null. It is clearly distinguishable from siblings like set_flag_permanent and set_default_flag_lifetime because it names the exact field (expiresAtUtc) and scope (this 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?

Explains the two modes (set vs. clear with null) and routing conditions, including that a permanent flag must first be made temporary with set_flag_permanent. It does not explicitly say when to prefer this over set_default_flag_lifetime, but the context is clear enough for correct selection.

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

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

The annotations only declare idempotentHint and destructiveHint=false. The description adds important, non-obvious behavior: who receives cleanup notices, that evaluation is unaffected, the specific error codes, and the plan-gating rule. That goes well beyond what annotations provide.

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

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

It is front-loaded: the main action and the clear behavior come first, then value constraints, then errors. The information is dense but mostly earns its place. Slightly more could be compressed, but it's efficient.

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

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

For a 3-parameter mutation tool with an output schema, the description covers ownership semantics, constraints, errors, and plan gating. It doesn't explain the return value, but an output schema exists. It is nearly complete, missing only explicit guidance on alternatives.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning to the owner value: it accepts an email, 'me', or null, and 'me' requires a personal access token. It also clarifies that evaluation is separate. It doesn't explain the project or flag keys, but those are already clear from the schema.

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

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

The description opens with a specific verb and resource: 'Name the person responsible for a flag, or pass owner: null to leave it unowned.' This distinguishes it clearly from siblings like update_flag or toggle_flag, which affect different aspects of a 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?

It explains the clear-vs-set behavior and the two acceptable owner value forms, and it states the refusal conditions (OWNER_NOT_MEMBER, PLAN_FEATURE_UNAVAILABLE). It also notes that clearing is always allowed. However, it doesn't point to an alternative tool for cases where the goal is bulk cleanup or planning, so it doesn't fully cover alternatives.

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

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

Annotations only declare idempotentHint and destructiveHint, so the description carries the real behavioral burden and does so well: permanent flags are excluded from removal candidates and find_stale_flags, evaluation never changes, and the specific refusal codes (PERMANENT_FLAG_HAS_EXPIRY, FEATURE_NOT_ENABLED, archived flag) are enumerated. It also notes that making a flag temporary is always allowed, defining the asymmetric failure modes.

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

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

Two dense sentences, front-loaded with the positive case and the permanent:false escape hatch before the failure conditions. Every clause (exclusion from find_stale_flags, refusal codes, always-allowed revert) adds distinct, actionable 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?

With an output schema already present, the description need not explain return values, and it instead covers the preconditions, error conditions, and downstream effects an agent needs. For a 3-param mutation with clear annotations, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the effect of permanent: false (reverts to temporary) and the cross-parameter interaction with set_flag_expiry's expiresAtUtc: null. It adds semantic value without needing to restate key types already in the schema.

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

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

States a specific verb and resource (mark a flag permanent/temporary) and immediately scopes what "permanent" means: a kill switch, ops toggle or entitlement gate. It is distinguishable from adjacent siblings like set_flag_expiry, which it explicitly references for the expiry-clearing prerequisite.

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

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

Gives clear context for when to use it (flags meant to stay) and explicitly routes the dependency to set_flag_expiry with expiresAtUtc: null when an expiry blocks the change. It lacks an explicit 'when not to use vs alternatives' framing, so it stops short of a 5.

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

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

The annotation already declares destructiveHint=true, so the description need only add context. It does so by stating the change affects live evaluation immediately, which is a valuable behavioral trait beyond the annotation and reinforces why the warning matters.

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-loading the core action and appending the critical warning. Every sentence earns its place 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?

For a mutation tool with annotations and an output schema, the description covers the action and its immediate live-evaluation impact. It lacks a note on prerequisites or whether changes are reversible, but the destructive annotation and output schema fill much of that gap.

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

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

Schema description coverage is 100%, so the schema documents all four parameters fully. The description adds only the single-environment constraint, which is minor against the schema baseline of 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?

The description states a specific verb (enable/disable) and resource (flag in one environment), and flags the scope as a single environment. It is clearly distinguishable from siblings like update_flag or update_flag_environment_config.

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

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

It implies usage for toggling a flag in an environment but gives no explicit when-to-use vs. alternatives such as update_flag or update_flag_environment_config. The caution to double-check the environment is a usage note, not a comparison.

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 supply destructiveHint=true; the description carries the real behavioral load, disclosing partial-update semantics ('changes only the fields you pass'), the empty-string clear convention, field immutability, and optimistic-concurrency behavior (refused write / etag from get_flag). This is well beyond what the annotation states.

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 dense sentences, each doing distinct work: field list, merge/clear semantics, immutability, alternative tools, then concurrency control. No filler and the mutable-field list is front-loaded.

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

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

For a destructive partial-update tool with an output schema already documenting returns, the description covers everything needed to call it correctly: scope, merge behavior, immutability constraints, concurrency guard, and sibling alternatives.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema lacks: merge semantics ('changes only the fields you pass and keeps the rest') and the description:"" clearing convention. The ifMatch semantics largely restate the schema's own 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 (update) plus resource (flag metadata) and enumerates exactly which fields are mutable (name/description/tags/clientSideVisible). It also explicitly separates itself from sibling tools that change behavior (toggle_flag, update_targeting), so an agent can route correctly without opening 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?

Gives explicit when-to-use-this vs when-to-use-something-else: behavior changes go to toggle_flag / update_targeting, and key/type are declared immutable. The conditional ifMatch guidance ('pass ... to refuse the write if the flag changed') tells the agent when to include a parameter.

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

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

Annotations already declare destructiveHint=true, so the mutation profile is known. The description adds the useful constraint that only SingleVariation is supported at this level, but does not say whether changes take effect immediately for live traffic, whether prerequisites are replaced or merged (that lives only in the schema), or what permissions are needed. Value-add beyond annotations is modest.

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

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

A single dense sentence that front-loads the operation and its field list, with the alternative-tool note at the end. The nested parentheticals are slightly heavy but every clause carries 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?

An output schema exists, so return values need no explanation, and the required parameter plus the strategy limitation are covered. What's missing is the blast radius — whether the update is immediate, partial, or wholesale for prerequisites — which matters for a destructive-flagged mutation.

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 six parameters are already documented, including the prerequisite replace-vs-omit semantics and the fallthrough meaning of defaultVariationId. The description largely restates those schema notes rather than adding new meaning, 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 precise verb and resource — 'Update a flag's per-environment serving config' — and enumerates the exact settings affected (defaultVariationId, strategy, prerequisites). This is clearly distinguishable from siblings like update_flag (flag-level) and update_targeting (rule-level).

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 percentage rollout work away from this tool: 'Percentage rollouts are configured on targeting rules via update_targeting.' That is a concrete alternative with a condition. It doesn't cover when to prefer this over update_flag or toggle_flag, so not a full 5.

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

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

Annotations only declare destructiveHint=true, but the description discloses the crucial destructive semantics (rules omitted from the payload are deleted), rule evaluation order, and the optimistic-concurrency contract including the 412 refusal behavior. These are exactly the traits an agent needs and that annotations cannot express.

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 with zero filler, and the most consequential fact — full replacement with deletion of omitted rules — is front-loaded in the first sentence.

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, concurrency-sensitive mutation the description covers destruction scope, ordering, prerequisite read, and conflict handling; with an output schema present it correctly omits return-shape detail. Nothing essential for correct invocation 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%, so baseline is 3; the schema already documents ifMatch's 412 behavior and the 'rules left out are deleted' semantics. The description reiterates rather than extends the per-parameter documentation, adding only the ordering note.

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 (REPLACE) with the resource (all targeting rules of a flag) and the scope (one environment), and the parenthetical clarifies the full-PUT semantics. This distinguishes it cleanly from get_targeting and manage_targeting_rule without needing to open 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 prescribes the read-before-write workflow: call get_targeting first, then pass the etag as ifMatch. The condition that selects the alternative (single-rule edits via manage_targeting_rule) is only implied by the 'REPLACE all' framing rather than named, which keeps it just short of a 5.

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

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

Annotations only supply destructiveHint=false, so the description carries most of the burden and does well: it discloses that the tool does not edit code ('apply the edit yourself') and that the new flag defaults to DISABLED in every environment. It omits retry/auth behavior and the significance of the idempotency_key parameter, but the state and scope disclosures are genuinely useful.

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 primary action and result, followed by the non-obvious constraint (snippet only) and the lifecycle default. Every sentence adds distinct 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?

An output schema exists, so the snippet return value needn't be described. Combined with full schema coverage, the description's coverage of scope (no code edit), default state (disabled everywhere), and next step (toggle_flag) makes it complete for this tool's complexity.

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 7 well-documented parameters, so the schema does the heavy lifting. The description adds no parameter-level meaning such as expected key format or language implications, making 3 the correct 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 (create a Boolean feature flag) plus the distinctive side effect (return an SDK snippet for guarding a code path). It implicitly differentiates itself from the plain create_flag sibling by noting the snippet return, but never names that sibling or contrasts the two 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?

It gives clear context for when this tool fits — wrapping a new code path — and names the natural follow-up tool (toggle_flag) with the condition 'when ready.' It stops short of stating when to prefer the sibling create_flag instead, so the routing guidance is incomplete rather than explicit.

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