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

Annotations provide only destructiveHint=true with no readOnlyHint, so the description carries most of the behavioral burden. It discloses the backend endpoint but nothing about authentication, deduplication behavior, side effects (owner assignment, custom field creation), or what is returned after creation. A mutation tool with 18 parameters deserves more than a one-line API mapping.

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 very short sentences, front-loaded with the verb and the single required field. Nothing is wasted, though the terseness borders on under-specification rather than true conciseness.

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 an 18-parameter create tool with no output schema and only a destructiveHint annotation, the description is thin. The agent gets the action and the required field but no information about deduplication, response payload, or which optional fields matter most.

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 72% and the description only restates that first_name is required, which the schema already marks as required with its own description. It adds no meaning for the remaining 17 parameters (owner_user_id, organisation_id, custom_fields semantics, etc.) and does not compensate for the coverage gap.

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 contact') and even pins the underlying API call (POST /Contacts), so the agent knows exactly what the tool does. It stops short of any sibling differentiation, though the create/update verb pair makes the distinction mostly self-evident.

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?

There is no when-to-use guidance at all: nothing about when to use this versus insightly_update_contact, whether duplicate contacts are rejected or merged, or what prerequisites (e.g. an existing organisation_id) apply. The parenthetical about first_name is a required-field note, not usage guidance.

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