Create Tax Code

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

Beyond annotations (idempotentHint=false), the description adds meaningful behavioral details: calling it again creates another record, errors return an HTTP status payload with common codes (401, 403, 404), and fields are nested under 'tax_code' in the request payload. It also discloses the successful HTTP 201 response. These details enrich the annotation-provided non-idempotency and write characteristics.

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 moderately long but every sentence contributes: purpose, payload nesting, return value, non-idempotency, error behavior, required params, and API reference. It is front-loaded with the main action and does not waste words, though it could be slightly tighter by omitting the redundant 'Required parameters' line already covered by the schema.

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 there is no output schema, the description appropriately mentions the return value (HTTP 201 with new id) and error payloads. It covers the essential aspects of a create operation: target, required parameters, response, and failure modes. It is sufficiently complete for an 8-parameter tool with full schema documentation.

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 the baseline is 3. The description adds value by clarifying that all record fields should be passed as top-level arguments even though they are nested in the request payload, which prevents confusion. It also highlights the required parameters (company_id, code) that might otherwise be buried in the schema.

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 tool 'Creates a Tax Code for a given Company' with a specific verb and resource. It also distinguishes from siblings by noting 'calling it again creates another record,' which contrasts with update or sync tools. The mention of returning the new id (HTTP 201) further clarifies the create action.

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 provides clear context: it is for creating new tax codes, specifies required parameters (company_id, code), and explains that fields should be passed as top-level arguments. However, it does not explicitly mention when not to use it or name alternatives like 'use update_tax_code to modify existing tax codes,' so it stops short of a 5.

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