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

Annotations only declare destructiveHint=true, leaving the description to carry behavioral detail. It discloses that archiving stops evaluation, causes callers to fall back to hardcoded defaults, refuses under live traffic, and self-resolves the refusal. This goes well beyond the annotation and gives the agent concrete expectations.

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

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

Three dense sentences, front-loaded with the core action and effect, followed by reversal and refusal behavior. Every clause adds necessary context; there is no filler or repetition of schema 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 destructive operation with no output schema and only a destructiveHint annotation, the description covers the key behavioral facts: effect, reversibility, refusal condition, rationale, and self-resolution. An agent has enough to decide whether and when to call it, with the force parameter 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 coverage is low at 33%; only 'force' has a description. The description explains the flag effect and the refusal, but does not elaborate on 'project' or 'flag' beyond their obvious roles, and it never mentions the 'force' parameter even though that is the parameter most relevant to the refusal behavior. It fails to compensate for the low schema coverage.

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

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

The description states a specific verb ('Archive'), a resource ('flag'), and the exact effect ('soft-hide, evaluation stops serving it'). It distinguishes this from restore_flag by naming the reversal path, and the soft-hide framing separates it from delete_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?

The description gives clear context: it is reversible via restore_flag and explains when the operation will be refused (FLAG_RECENTLY_EVALUATED while live traffic is still evaluating). It does not explicitly enumerate when to use alternatives like delete_flag, but the soft-hide/reversible framing and refusal conditions provide actionable routing guidance.

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

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

Beyond the annotations, the description discloses important side effects: the flag is created in every environment of the project and starts disabled, and Boolean flags automatically receive true/false variations. This helps the agent anticipate cross-environment impact. It does not cover every possible behavioral aspect such as permissions or return payload, but the core creation behavior is transparent.

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

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

The description is three sentences with no filler. It front-loads the primary purpose and then gives only the essential type and variation behavior an agent needs to call the tool correctly.

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 nine parameters and no output schema, the description together with the input schema is largely sufficient: required parameters are in the schema, type-specific rules are explained, and the disabled/every-environment behavior is disclosed. It stops short of describing the response or error scenarios, but those gaps are unlikely to cause incorrect 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 low at 44%, and the description compensates for the most important parameters by explaining the type enum and the conditional requirement for initialVariations on non-Boolean types. However, it leaves several parameters such as name, description, and tags without additional meaning, and the schema itself only partially covers those.

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 states a clear verb and resource: Create a feature flag. The rest of the description adds type-specific detail and creation semantics, distinguishing this creation tool from siblings such as update_flag, delete_flag, and get_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?

The description makes obvious that this tool is for creating a new flag rather than updating or deleting one, and it gives clear conditional guidance about when to pass initialVariations versus relying on automatic Boolean variations. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the context is clear.

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

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

Annotations already declare destructiveHint=true, and the description reinforces this by stating the deletion is permanent and applies across all environments. It adds the concrete error condition FLAG_HAS_DEPENDENTS, which is not present in the annotations. This goes beyond the structured metadata without contradicting it.

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

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

The description is three short, information-dense sentences with no filler. The most critical fact (permanent deletion) is front-loaded, followed by the error condition and the preferred alternative. 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 destructive two-parameter operation, the description conveys the critical behavioral context: permanence, cross-environment scope, the dependency error, and the recommended alternative. The main gap is the undocumented 'project' parameter, but the overall operational context is otherwise sufficiently complete.

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

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

Schema description coverage is only 50%: 'flag' is documented in the schema but 'project' is not. The description does not compensate by explaining what 'project' refers to or how it interacts with the deletion. The only added meaning is the implicit focus on the 'flag' parameter, leaving the project parameter semantics under-specified.

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

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

The description clearly states the action as 'PERMANENTLY delete a flag across all environments,' which is specific about the verb, resource, and scope. It also differentiates itself from archive_flag by noting it should be preferred unless full removal is required. This unambiguously identifies the tool's purpose relative to its 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?

The description explicitly says 'Prefer archive_flag unless the flag must be fully removed,' giving direct guidance on when to use this tool versus the archival alternative. It also mentions the failure condition FLAG_HAS_DEPENDENTS, which informs the user about a prerequisite that blocks deletion. This is strong usage guidance.

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

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

The readOnlyHint annotation already covers safety, and the description adds meaningful behavioral detail: a 50-candidate-per-call cap and a concrete limitation that per-rule percentage ramps are not inspected. This gives the agent expectations beyond what the schema or 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?

Two dense sentences front-load the purpose and pack criteria, caveat, and candidate limit without redundancy. No filler, no repetition of schema defaults.

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

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

For a read-only filtered-list tool with two scalar parameters, the description covers the selection rule, a safety caveat, and the candidate cap. Although there is no output schema, the return type (candidate flags) is evident from the stated purpose.

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

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

The description gives 'N days' operational meaning tied to the days parameter crucially, but the required project parameter is left undocumented in both schema and description. With schema description coverage at 50%, the description only partially compensates for the missing parameter semantics.

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

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

States a specific outcome ('flags ready for code cleanup') with exact selection criteria: not updated in N days AND enabled or disabled in every environment. This clearly differentiates it from sibling list/get/status tools and is not a tautology of the title.

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?

Establishes clear usage context for finding cleanup candidates and includes operational guidance such as verifying rollout completeness before removal and noting that percentage ramps are not inspected. It does not explicitly name sibling alternatives or state when not to use the tool, 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 readOnlyHint annotation already establishes the safety profile, and the description adds that this is a compact view spanning environments with specific fields. This is useful but not a deep disclosure of behavior such as aggregation or omission of full targeting details.

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

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

A single, front-loaded sentence that names the scope first and then enumerates the returned fields. Every word earns its place with no repetition or 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?

For a simple two-parameter read-only tool, the description covers the output fields and cross-environment behavior. It does not describe return format or errors, but the low complexity and readOnlyHint annotation make those omissions minor.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it only mentions 'one flag' and 'environments' indirectly. The 'project' parameter is never referenced, and no format or relationship details are given beyond the schema's bare names.

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

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

The description identifies a specific resource ('one flag') and a specific scope ('cross-environment'), and lists the fields shown. It is clear enough to distinguish from list_flags and get_targeting, though it never names a 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?

There is no guidance on when to choose this tool over get_flag, list_flags, or update_flag_environment_config. The phrase 'compact cross-environment view' implies an overview use case, but no exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that by saying 'Get'. It adds that the response includes variations and metadata, but does not describe return format, error behavior, or auth requirements; the annotation covers the read-only nature, so this partial disclosure is acceptable.

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

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

Two short sentences with no filler. The action and scope are front-loaded, and the addressing detail is the only extra information. Every word 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 read-only single-fetch tool with two fully documented parameters and no output schema, the description adequately explains the tool's purpose and what it returns. It could specify the structure of variations/metadata, but that is not essential for correct invocation.

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

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

Schema coverage is 100%, so both parameters (flag, project) are fully described in the schema. The description reinforces that 'flag' can be a key or id, but adds no meaning beyond what the schema already documents.

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 ('Get'), a specific resource ('feature flag'), and the scope ('one ... with variations and metadata'). It clearly distinguishes from list_flags by targeting a single flag and from create/update/delete by being a read operation.

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

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

The description implies this tool is for fetching a single flag by key or id, but it does not explicitly contrast with list_flags or other siblings. There is no explicit 'when to use this versus that' guidance, only an implied use case.

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 response contents (conditions, id, metadata), which is behavior beyond the schema and annotations, providing useful context for what the agent will receive.

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 with no filler. The main action and resource appear first, followed by the return fields and lookup method. Every word 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 simple getter with two well-described parameters, read-only annotation, and no output schema, the description is sufficient. It names the response fields, so an agent knows what to expect without needing additional information.

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 both 'project' and 'segment' already described in the schema. The description's 'by key or id' merely restates the segment param description, adding no new parameter semantics. Baseline 3 applies.

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

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

The description states a specific verb ('Get'), a specific resource ('one user segment'), and the return contents ('conditions, id, and metadata'). It clearly distinguishes from list_segments (plural vs singular) and get_flag (different resource).

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

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

The description implies usage when a single segment is needed by key or id, and the sibling list makes the alternative (list_segments) obvious. However, it does not explicitly state when not to use it or name the alternative, so it stops short of full routing guidance.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, lowering the bar. The description adds that the result is current and includes the enabled flag plus ordered rules, but does not disclose error behavior, permissions, or how order is determined. That is adequate but leaves some behavioral gaps.

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 conveys the object, scope, and return contents without filler. Every phrase adds value, and the parenthetical clarifies what 'targeting configuration' means.

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 three self-named parameters and no output schema, the description is mostly complete: it states what the tool returns and the environment scope. The main shortfall is not explaining project/flag identifier semantics, but sibling list tools and property names make this recoverable.

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

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

Schema description coverage is 0%, so the description must compensate for the three string parameters. It only contextualizes 'environment' via 'in one environment'; 'project' and 'flag' receive no additional meaning beyond their property names, leaving the agent to infer identifiers and required formats.

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 action ('Get'), a specific resource ('a flag's current targeting configuration'), and the result content ('enabled flag + ordered rules') in one environment. This clearly differentiates it from siblings like get_flag and update_targeting.

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: use this when you need the current targeting configuration for a specific flag in a specific environment. It does not explicitly name alternatives or exclusions, but the purpose is narrow and unambiguous enough for an agent to select it appropriately.

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 include readOnlyHint: true, so the agent already knows this is a read-only operation; the description adds project scoping and example environment names. It does not disclose pagination behavior or the return structure, but for a simple read-only list this is a moderate gap rather than a serious one.

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

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

The description is a single efficient sentence with no filler, front-loading the action and object while using the parenthetical example to clarify the concept. Every part 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 read-only list tool with one required parameter, the core purpose and scope are clearly stated and the annotation covers safety. However, the absence of an output schema and any mention of pagination or returned fields leaves the agent uncertain about the result shape, so the description is adequate but not fully complete.

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

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

Schema description coverage is only 33%, covering only the 'project' parameter, while 'limit' and 'cursor' are undocumented. The description provides no additional meaning for these parameters and only loosely maps 'of a project' to the required project key, leaving the agent to guess at pagination semantics.

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

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

The description states a specific action ('List'), a clear resource ('environments'), and a scoping qualifier ('of a project'), with concrete examples (development, staging, production). It is immediately distinguishable from sibling tools, which cover projects, flags, and segments, so an agent can identify this tool without ambiguity.

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

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

The description implies the tool is intended for retrieving environments tied to a project, which gives a reasonable usage context. However, it does not explicitly state when to prefer this over alternatives or mention any exclusions or prerequisites other than the project scope.

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, covering the safety profile. The description adds valuable context by specifying the filtering dimensions (search, tag, type, archived) and pagination via cursor, which are not fully covered by annotations. It does not contradict annotations and discloses the operational details of the listing 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?

The description is a single, tightly packed sentence that leads with the core purpose and immediately lists the key filters and pagination mechanism. There is no redundancy or filler; every word adds value. The structure is efficient and easy to parse.

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 listing tool with 7 parameters and no output schema, the description covers the main filtering and pagination aspects. It does not describe the return format or default ordering, which might be important for an agent, but given the tool's simplicity and the presence of filters, the description is reasonably complete. The missing return details are 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 low (29%), with only project and archived described in the schema. The description compensates by explaining the purpose of search (substring match), tag, type, and archived, and introduces cursor for pagination. However, it does not explicitly clarify the limit parameter's role, though pagination implies it. Overall, the description adds significant meaning beyond the schema.

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

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

The description clearly states the action (list), the resource (feature flags), and the scope (in a project). It enumerates the available filters and mentions pagination, which distinguishes it from sibling tools like get_flag (single flag retrieval) and list_projects (different resource). The verb and resource are specific and unambiguous.

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

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

The description explains how to use the tool (filters, pagination) but does not explicitly state when to choose this over alternatives like get_flag for a single flag or other list tools. The sibling list implies a distinction, but the description leaves the selection logic to the agent's inference rather than providing explicit routing guidance.

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

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

The annotation readOnlyHint=true already establishes that this is a safe, non-mutating operation. The description adds the pagination behavior (cursor-based continuation), which is useful context beyond the annotation. However, it does not mention any rate limits, authorization requirements, or response format details, which are not required for a simple read-only listing but would add richness.

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

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

Two compact sentences deliver the essential purpose and the key pagination behavior with zero filler. The primary action is front-loaded, and the pagination note is immediately actionable.

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

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

For a low-complexity, read-only, paginated list tool with two fully documented optional parameters and no output schema, the description covers everything an agent needs to call it correctly. The annotation covers the safety profile, and the schema covers the parameter details.

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%: limit is described as 'Page size (default 20)' and cursor as 'next_cursor from a previous response' in the schema itself. The description adds little beyond what the schema already provides, though it does reinforce the pagination relationship between the cursor and a prior response. This meets the baseline for full schema coverage.

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

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

States a specific verb and resource ('List projects in the Featureflip organization') and is clearly distinct from all siblings, which target flags, environments, and segments rather than projects. An agent can immediately understand what this tool does and how it differs from other list_* tools.

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

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

Provides explicit pagination usage: 'pass cursor from next_cursor to continue.' This tells the agent how to fetch additional pages. It does not state when to use this over alternatives, but none of the siblings list projects, so there is no real alternative to exclude.

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 useful context about segments being reusable and referenced via userSegmentId, but it does not disclose pagination behavior, result shape, or ordering. This is acceptable given the read-only annotation but not especially rich.

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

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

Two sentences with no filler. The core action is front-loaded, and the second sentence earns its place by explaining how segments are referenced, which is useful context for an agent deciding whether to resolve segment IDs.

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

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

The description is adequate for a simple read-only list operation and identifies the required project context. However, with no output schema and only 33% parameter coverage, it does not explain what fields each segment contains or how pagination via limit/cursor behaves, leaving moderate gaps.

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

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

Schema description coverage is only 33%, with project described but limit and cursor left undocumented. The description reinforces the project scope but does not explain how limit and cursor control pagination or output size, so it fails to compensate for the schema gaps.

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'), a specific resource ('reusable user segments'), and scope ('in a project'), and adds the useful detail that segments are referenced from targeting rules via userSegmentId. This clearly differentiates it from siblings like get_segment (single segment) and list_flags (flags, not segments).

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 conveys that this is the tool for listing reusable segments within a project, which gives implied context for when to use it. However, it does not explicitly contrast it with get_segment or mention any exclusions, so the guidance is inferred rather than stated.

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

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

With destructiveHint=true already signaling mutation risk, the description adds the VARIATION_HAS_DEPENDENTS failure mode and the dependency condition. It also discloses the need to obtain variationId via get_flag, which goes slightly beyond 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?

At three sentences, the description is compact and front-loads the core action mapping. The opening sentence is somewhat redundant with the title, but the actionable conditional and failure-mode sentences earn their place.

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

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

The description covers the action-dependent parameter requirements and a key failure mode, which is the main complexity of the tool. It does not describe the response shape or the semantics of optional fields like name/description, but the critical invocation knowledge is present.

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

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

Schema coverage is only 38%, but the description mostly re-encodes what the schema already says for key, value, and variationId. It adds the useful 'get ids via get_flag' pointer but leaves name and description parameters unexplained, so it only partially compensates for the low schema coverage.

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

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

The description states the tool manages a flag's variations and enumerates the three concrete actions (add/update/remove). It also differentiates from sibling tools by specifying action-specific requirements, making it unambiguous versus get_flag or update_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?

The description provides a clear context: use this tool to mutate variations, with action=add/update/remove. It points to get_flag as the source for variationId, which is an explicit prerequisite/alternative, though it does not state formal when-not-to-use exclusions.

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

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

The description communicates that the flag transitions from an archived state back to a restored one, which is useful behavioral context. The destructiveHint=false annotation already covers the safety profile, though side effects and idempotency are not discussed.

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

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

The description is one short sentence with no filler, but it mostly restates the title and adds little new information. It is concise rather than genuinely informative.

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 two-parameter tool, the description is too minimal: it omits parameter semantics, fails to address how project/flag identifiers should be supplied, and gives no guidance on expected behavior or alternatives. An agent can make a reasonable guess but would benefit from richer context.

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

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

Schema description coverage is 0%, and the description does not clarify what 'project' and 'flag' represent or what formats/identifiers are expected. 'flag' is mentioned generically, but 'project' is entirely unaddressed.

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

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

The description states a clear action ('Restore') and a clear object ('previously archived flag'), so an agent can tell this is an un-archive operation. It does not explicitly contrast with archive_flag, but the inverse relationship is strongly implied.

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

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

The phrase 'previously archived' implies the intended use case and distinguishes restoration from archive/delete operations. However, it does not explicitly name alternatives, state prerequisites, or explain when not to use it.

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

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

The destructiveHint annotation is complemented by the description's explicit statement that the action 'affects live evaluation immediately' and the caution to double-check the environment. This adds valuable behavioral context beyond the annotation, explaining the real-world impact and the need for care.

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 concise sentences that front-load the action and scope, followed by a relevant safety warning. There is no filler, redundancy, or unnecessary detail; every word contributes to the tool's usability.

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 4-parameter tool with a destructive annotation and no output schema, the description covers the core action, scope, immediate impact, and provides a caution. It does not discuss return values or prerequisites, but those are less critical here. The description is reasonably complete for the 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 only 50%, with project and enabled lacking parameter descriptions. The description adds some meaning by implying that 'enabled' is a boolean and that environment selects a single environment, but it does not explain the project parameter or the expected format for flag key/id. It partially compensates for the schema gap but not fully.

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

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

The description clearly states a specific action ('Enable or disable') on a specific resource ('flag') with a definite scope ('ONE environment'). This distinguishes it from broader sibling tools like update_flag or update_flag_environment_config, and the added impact note about live evaluation further pinpoints its purpose.

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

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

The description implies usage context through the single-environment scope and the warning to double-check the environment, but it does not explicitly compare against sibling tools like update_flag_environment_config or flag_status, nor does it state when to use this versus an alternative. Guidance is present but only implicit.

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

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

The destructiveHint annotation already communicates mutation, and the description adds useful context by scoping the mutation to metadata and naming immutable fields. However, it does not explain destructive consequences, whether updates overwrite or merge, or any permission requirements. With annotations present, this is adequate but not rich.

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

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

Two sentences with no filler. The action and affected fields are front-loaded, immutability constraints are stated immediately after, and routing to alternatives is deferred to the end. 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 metadata mutation tool with destructiveHint, no output schema, and low schema coverage, the description is minimally viable but not complete. It does not state whether at least one update field is required, how tags are applied, or what the response contains, leaving the agent to guess on 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 only 17%, so the description must compensate, but it merely lists four editable field names and says key/type are immutable. It does not clarify meanings such as clientSideVisible, the structure of tags, or the role of the required project parameter. This is insufficient given the low schema coverage.

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

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

The description states a specific verb ('Update') and resource ('flag metadata'), enumerates exactly which fields are affected (name/description/tags/clientSideVisible), and explicitly distinguishes itself from behavior-changing siblings. This leaves no ambiguity about what the tool does.

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

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

It explicitly routes behavior changes to toggle_flag/update_targeting, and states that key and type are immutable, which implicitly warns against trying to modify them. This gives the agent clear selection criteria versus sibling tools.

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

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

Annotations already declare destructiveHint: true, so the safety bar is covered. The description adds valuable behavioral details: defaultVariationId is 'required by the API', only SingleVariation is currently supported at environment level, and prerequisites have an 'omit to leave untouched / pass list to replace wholesale' semantic. No contradiction with annotations.

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

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

The description is a single efficient sentence that front-loads the purpose, then packs the field semantics into a parenthetical list. Nothing is redundant, though the density slightly hurts readability. It 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 destructive operation with six parameters and no output schema, the description covers the key fields but leaves gaps: it doesn't state what happens if strategy is omitted (presumably unchanged, but not stated), nor does it clarify how project/flag/environment should be identified (key vs ID). An agent may need to consult sibling tools or schemas for these details.

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 low (33%), so the description must compensate. It does explain defaultVariationId (served on fallthrough, required), strategy (enum values and current limitation), and prerequisites (omit vs replace). However, it provides no meaning for project, flag, or environment identifiers, which are equally necessary to invoke the tool.

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 scope: 'Update a flag's per-environment serving config'. It enumerates the exact fields affected (defaultVariationId, strategy, prerequisites) and explicitly routes percentage rollouts to update_targeting, making it easy to distinguish from that sibling and from the broader update_flag tool.

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

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

The description explicitly tells the agent when not to use this tool: 'Percentage rollouts are configured on targeting rules via update_targeting.' This is a clear alternative. It doesn't mention when to use this vs update_flag, but the 'per-environment' scope and the listed fields provide enough contextual guidance.

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

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

The destructiveHint annotation already flags danger, and the description adds meaningful behavioral detail: it is a full PUT, omitted rules are removed, and rules are evaluated in order. This goes beyond the annotation and sets proper expectations for a write operation.

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 deliver the core action, the destructive consequence, evaluation order, and a safety tip. Every sentence earns its place, and the key 'REPLACE' and 'rules not included are removed' messaging 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 replacement tool, the description covers the essential risks, ordering, and the recommended precondition. It does not detail return values or error cases, but with no output schema and a straightforward rules-replacement model, the description is sufficiently complete; a small gap remains around how to construct valid rule objects.

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

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

Schema description coverage is 0% for top-level parameters, yet the description only elaborates on the behavioral meaning of 'rules' rather than defining the format or purpose of project, flag, environment, or rules as parameters. It does not compensate enough for the missing 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?

The description states a specific verb ('REPLACE'), a clear resource ('all targeting rules of a flag in one environment'), and the full-PUT semantics that distinguish it from get_targeting. The phrase 'rules not included are removed' leaves no ambiguity about scope.

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

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

The description clearly indicates when to use this tool (full replacement) and explicitly instructs the user to fetch current rules via get_targeting first. It does not explicitly state when not to use it or what alternative to choose for partial updates, so it falls short of a 5.

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

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

Beyond destructiveHint=false, the description reveals that a flag is actually created, that the tool returns only the snippet and does not modify code, and that the flag starts disabled in all environments. This is valuable behavioral context for an agent. It doesn't cover idempotency or conflict behavior, but there is no contradiction with annotations.

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

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

Three short sentences front-load the core behavior, then state the snippet-only constraint and the initial disabled state with the enablement path. No filler or redundant restatement.

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 7-param tool with no output schema, the description covers the essential call outcome (create flag, get snippet), the manual edit step, and the disabled initial state with enablement path. It omits snippet format and conflict/idempotency behavior, but the schema plus annotations cover enough for confident invocation.

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

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

The description doesn't explain any parameters; the schema carries most of the meaning, with descriptions for key, name, project, language, and description, leaving tags and idempotency_key undocumented. At 71% coverage, the description doesn't compensate for the missing two but the schema is largely sufficient.

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 concrete action ('Create a Boolean feature flag') and a differentiating deliverable ('SDK code snippet'), and clarifies the flag's disabled initial state. This clearly separates it from sibling create_flag even without naming it.

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

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

It gives the context for use — wrapping a new code path — and explicitly says the agent must apply the snippet itself, plus points to toggle_flag for later enablement. It doesn't enumerate exclusions versus create_flag, but the context is clear enough.

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