remove_eqs_option

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

Beyond the destructiveHint/readOnlyHint annotations, the description discloses non-obvious behavior: cascading deletion of the generator and tests, index renumbering of subsequent options, no implicit save (dirty flag only), and hard failure on an out-of-range index. This is exactly the kind of context annotations cannot convey.

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

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

Four tight sentences, front-loaded with the core action and cascade, followed by the save/error caveats and the return shape. Every sentence carries 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?

With no output schema, the description supplies the return fields (query_path, option_index, removed, option_count) as well as the durable side effects and failure mode. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so query_path and option_index are already documented and the baseline is 3. The statement that later options shift down one index hints at how option_index is interpreted across calls, but it describes post-call state rather than adding format or syntax detail to the parameters themselves.

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 (remove an option from a UEnvQuery asset) and immediately clarifies the cascade: the option's generator and tests go with it, and later options shift down. This is specific enough to separate it from siblings like remove_eqs_generator or remove_eqs_test.

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 tells the agent to call save_asset afterwards because the tool only marks the asset dirty, and it warns that an out-of-range index errors rather than silently no-op'ing. It does not name an alternative for removing just a generator or test, so the when-to-use-vs-siblings guidance is implied rather than stated.

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