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

Annotations only supply destructiveHint=true, i.e. that this is a mutating call; the description adds the mutual-requirement rule and the underlying POST /v2/contacts endpoint, which is mild context. It says nothing about whether re-creating the same contact duplicates data, what permissions are needed, or what happens on failure.

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?

Two sentences, purpose first, binding constraint second, endpoint trivia last; nothing wasted and the most decision-relevant information is front-loaded.

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?

Covers the identity requirement and the write nature of the call, but for a 19-parameter creation tool with no output schema it omits what is returned (no created-contact ID hint) and whether the remaining fields are all optional, leaving gaps the agent must infer.

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% with descriptive per-field text, so baseline is 3, but the description adds a real cross-parameter constraint (organisation_name XOR first_name+last_name) that the schema cannot express since it declares zero required fields and no oneOf.

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?

States a specific verb and resource ('Create a client or supplier contact') and names the two contact flavours, which cleanly separates it from freeagent_update_contact and freeagent_get_contact among the siblings.

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?

Offers one invocation rule ('Give either organisation_name, or first_name and last_name') which is genuinely useful, but gives no when-to-use context, no prerequisites (e.g. auth/company scoping), and no exclusions relative to update_contact or list_contacts.

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