create_choice

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

No annotations exist, so the description must fully disclose behavior. It states the tool returns a 'deploy-ready payload for the sys_choice table', implying it may not directly insert the record. However, the phrase 'Add a new choice value' suggests mutation, creating ambiguity. The description does not disclose side effects, permissions, or whether the operation is reversible.

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, each valuable: first states the action, second clarifies the output, third lists common uses. It is front-loaded and contains no redundant 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?

Given the lack of annotations and output schema, the description should be more complete. It omits important details like error handling, prerequisites (e.g., table must exist), and whether the operation is transactional. The ambiguity about 'deploy-ready payload' leaves the agent uncertain about the tool's effect.

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 all parameters are documented in the schema. The description adds no additional meaning to any parameter, merely listing common uses that indirectly hint at values. This meets the baseline but does not exceed it.

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 verb 'Add' and the resource 'a new choice value to a field's choice list in ServiceNow'. It specifies the platform and gives common use cases, making the tool's purpose unmistakable. It distinguishes itself from sibling creation tools by its specific domain (choice values).

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 lacks explicit guidance on when to use this tool versus alternatives. It only mentions 'common use' but does not provide when-not-to-use scenarios or compare with other tools like update_choice or delete_choice. The agent is left to infer the appropriate context.

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