xero_create_contact

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

Annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) already carry the core safety profile, lowering the burden on the description. The description does add genuine context beyond annotations: writes require an approval_ref to resume, the effect claim is verified by Spring, and idempotency_key serves as a stable business-action identity. However, it never describes the actual Xero-side behavior — what record gets created, what contact data is written, or any side effects — leaving the tool's real-world behavior opaque.

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 compact and well-structured: a header line, one routing constraint, then a clean labeled argument list. The parameter list earns its place given the 0% schema coverage. The only waste is that much of the arg list is generic platform boilerplate that would be identical for any governed connector operation, but it is still presented efficiently and 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?

For a create operation on an external connector with 7 nullable parameters and 0% schema coverage, the description leaves a critical gap: the contents of the 'arguments' JSON. An agent cannot construct a valid contact payload without knowing Xero contact fields (name, email, etc.), nor does it clarify what 'effect' values are expected or when approval is required. The presence of an output schema reduces the need to document return values, but the input-side ambiguity is substantial enough to lower this score.

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%, so the description carries the full burden, and it does provide a one-line gloss for all seven parameters, which partially compensates. However, the most operationally important parameter, 'arguments' — the JSON string that carries the actual Xero contact data — is documented only as 'JSON string of arguments for the connector operation,' which is nearly as unhelpful as no description. The platform-level parameters (project_id, connector_account_ref, etc.) are clarified well, but the business payload an agent actually needs to construct remains unexplained.

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's primary statement, 'Xero connector operation create_contact (platform tool xero.create_contact)', is a tautology that restates the tool name with no added meaning about what creating a Xero contact entails. The only novel information, 'Routes only through the exact project/account governed connector authority', concerns platform routing rather than the tool's actual purpose. An agent learns nothing about what a contact is, what fields it requires, or what success looks like beyond what the name alone conveys.

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 when-to-use or when-not-to-use guidance is provided. The description never contrasts xero_create_contact with sibling alternatives such as xero_update_contact, xero_list_contacts, hubspot_create_contact, or salesforce_create_contact, so an agent cannot distinguish when the Xero connector is the right choice versus a different CRM/accounting system. The routing constraint is a technical precondition, not a usage guideline.

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