check_allowance_reason_code

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

With no annotations, the description carries the burden of disclosing behavior. It does convey the core behavior: the tool tests whether a supplied code is a recognized allowance reason code. It does not disclose details such as case sensitivity, error behavior, or what 'recognized' means across codelist versions, but these are secondary for a simple predicate.

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. Every word matters, and it is appropriately sized for a one-parameter validation tool.

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 check tool with an output schema, the return value is covered elsewhere. The description is minimally viable, but it omits guidance on how to obtain valid codes and any nuances of what 'recognized' means, leaving some gap that an agent would need to resolve via sibling tools.

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 schema provides only a string named 'code' with no description or enum, and schema description coverage is 0%. The description adds that the parameter should be an allowance reason code and that it is tested for recognition—this is meaningful semantic context beyond the raw schema, though it stops short of giving formats, examples, or valid value sources.

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 ('Check') and resource ('allowance reason code'), and 'recognized' makes clear this is a membership test against a codelist. It is distinguishable from sibling list_allowance_reason_codes and other check_* tools because it names its exact codelist domain.

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 use case is implied by 'Check whether'—an agent can infer it should be used when a single allowance reason code needs validation. However, it never explicitly mentions the alternative list_allowance_reason_codes or states when not to use this tool, so guidance is only implicit.

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