suppress_feature

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

With no annotations, the description carries the full burden and does well: it discloses side effects (rebuild and remeasure), what is preserved (the feature and its dimensions), and dependency propagation ('features that depend on it follow both ways'). It does not mention permissions or reversibility limits, but the key behavioral traits are covered.

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 clauses, front-loaded with the core action and its inverse, then the differentiating behavior. No filler; every sentence earns its place.

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

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

No output schema and no annotations, so the description must stand alone; it covers the mutation's side effects and dependency behavior well. Minor gap: it doesn't clarify the name parameter's expected value or what a successful suppression returns.

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. It explains the suppress flag well ('bring it back with suppress=False', default true) but says nothing explicit about the name parameter beyond it referring to 'a feature'. Baseline is dragged up slightly by the good suppress explanation but the name gap keeps it at 3.

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

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

States a specific verb (suppress) and resource (feature), including the inverse operation via suppress=False. It explicitly contrasts with delete_feature, so an agent can distinguish it from a close sibling 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?

Names the alternative (delete_feature) and the condition that selects this tool instead ('keeps the feature and its dimensions, so it suits trying a variant'). It also notes that dependents follow both ways, giving the agent enough to decide between suppress and delete.

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