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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses unique behavioral traits: accountsReceivableOutstanding/Overdue are passed through from Xero and must not be summed across contacts, and status is relayed unfiltered so archived contacts may appear. This helps the agent avoid a real data-integrity mistake and does not contradict the annotations.

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 the core action and then gives two important caveats, each substantive. It is somewhat long and the 'Read-only; nothing is created or changed' sentence is redundant with the readOnlyHint annotation, but the remaining content is dense and worth including.

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 tool with no output schema, the description covers the main invocation hazards: receivables fields need no aggregation, status may be ARCHIVED, and the correct sibling exists for aggregates. It does not spell out the full response shape or this tool's own pagination behavior, but it gives enough for correct use alongside the well-covered schema.

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%, so the baseline is 3: all three parameters already have clear descriptions in the schema. The prose adds context about the organisation and contact status but does not add new parameter-level semantics beyond what the schema provides.

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 ('List') and resource ('contacts (customers and/or suppliers) from Xero'), and scopes it to the current organisation. It is clearly distinguishable from sibling tools like list_xero_accounts or get_xero_outstanding_receivables because it names the resource and primary purpose directly.

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 warns against using this tool to answer 'who owes me the most' and directs the agent to get_xero_outstanding_receivables instead. It also gives context-level guidance: surface the contact's Xero status before suggesting the contact for invoices or updates. This is concrete when-not and alternative routing.

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