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

Annotations only provide a destructiveHint, so the description carries the main burden and does so well: it discloses WRITE behavior, lack of duplicate checking, non-idempotency with duplicate creation on repeat calls, no notification being sent, and the underlying POST endpoint. These are exactly the behavioral traits an agent needs before invoking a write tool.

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 front-loaded with 'WRITE: create ONE new contact' and packs duplicate behavior, notification behavior, idempotency, and endpoint into a compact paragraph. Every sentence earns its place and there is no redundant or filler text.

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 mutation tool with a rich 13-parameter schema and minimal annotations, the description covers behavior, duplicate risk, idempotency, and endpoint well. The main gap is that there is no output schema and the description does not mention what the tool returns, such as the created contact or its ID, which an agent might need for follow-up calls.

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 100%, and all 13 parameters are documented in the schema. The description only implies that the contact can be a customer and/or supplier, which maps to flags already explained in the schema, but adds no syntax, format, or constraint details beyond what is provided. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource: create ONE new contact (customer and/or supplier) in the company's Billy account. It distinguishes the tool from siblings by noting that it does not check for duplicates and points to billy_list_contacts as the alternative. An agent can identify exactly what this tool does without opening the schema.

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?

It explicitly instructs to call billy_list_contacts first to avoid duplicates, states that nothing is sent to the contact, and warns that a repeat call creates a second contact. This gives clear when-to-use and prerequisite guidance, including a named sibling alternative.

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