books_update_credit_note

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

With no annotations, the description carries full burden for behavioral disclosure, but it only says 'update.' It does not mention whether this is a partial update, whether fields are overwritten, if permissions are required, or what happens to omitted fields. The mutation aspect is implied, but no side effects or safeguards are disclosed.

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 short and front-loaded, but it is under-specified for a tool with 24 parameters and complex nested objects. While there is no fluff, the brevity comes at the cost of missing essential usage and behavior context, so it is not appropriately sized for the tool's complexity.

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 complexity (24 params, nested objects, no output schema, no annotations), the one-line description is far from complete. It does not explain how to identify the target credit note beyond creditnote_id, what fields are updatable, how updates affect existing data, or what response format to expect.

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% and the description does not compensate for any of the 24 parameters. It adds no meaning beyond what the raw schema property names (e.g., date, notes, terms, line_items) already suggest, leaving the agent to guess semantics, formats, and relationships between fields.

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 'Update an existing credit note in Books' clearly states the action (update), the resource (credit note), and the domain (Books). It distinguishes this tool from siblings like create, delete, void, and email credit notes by focusing on modification of an existing record.

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?

No guidance is provided about when to use this tool versus alternatives. The word 'existing' hints that the credit note must already exist, but there is no explicit mention of using create for new notes, voiding, or converting, leaving the agent without clear selection criteria.

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