tpt_choose_category

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

Annotations already convey readOnlyHint=false and destructiveHint=true, so the description does not need to restate that this is mutating. It does add useful behavioral context by requiring an 'exact option observed' in the current form, which aligns with openWorldHint=true. It does not describe side effects like form navigation or state changes, but annotations cover the basic safety profile.

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, front-loaded sentence with no filler. It communicates the core selection constraint efficiently. It could add more guidance without bloating, but as written it is well-structured and concise.

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 enum and annotation cover a lot: allowed fields, destructive intent, open-world choices. Still, there is no mention of how to obtain the 'observed' options, how this relates to tpt_category_options, or what happens after selection. Given destructiveHint=true, a little more context about the mutation would make the tool safer to invoke.

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 had to carry the load for explaining 'field' and 'value'. It only implies that 'value' is an observed option; it never explains that 'field' selects which form control to update, nor that the value must correspond to the allowed options for that field. The enum on 'field' helps but still does not define semantics for 'value'.

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 uses a specific verb ('Choose') and a specific resource ('option observed in the current TPT form'), so an agent can tell this is a selection action rather than a listing or inspection action. Its main weakness is that the tool name limits it to 'category' while the schema actually supports six different field types, so the description does not fully resolve that mismatch.

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?

'Observed in the current TPT form' clearly implies the value must come from something previously inspected or listed, and it warns against arbitrary values. However, there is no explicit statement about when to use this tool versus siblings like tpt_category_options or tpt_inspect, and no alternative is named.

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