xero_create_item

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

Annotations already mark this as readOnly=false, destructiveHint=true, and idempotentHint=true. The description adds useful governance context: routing through a governed connector authority, a claimed read/write effect that Spring verifies, an idempotency key for stable business action identity, and approval_ref as a resume-token for writes. This goes beyond the annotations without contradicting them.

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 uses a clear argument list, which helps scanability. But it leads with a near-tautological line and a routing statement rather than a purpose statement. It contains no fluff, yet it sacrifices functional clarity for brevity.

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?

This is a governance-wrapped connector tool with seven parameters, all optional in schema, no meaningful domain payload guidance, and a complex approval/idempotency model. The description does not explain how to construct the arguments JSON, how to obtain project_id/project_ref/connector_account_ref, or how the approval flow is initiated. An agent trying to actually create a Xero item would likely remain uncertain about what to pass.

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?

With 0% schema description coverage, the description must compensate for all parameter meaning. It names every parameter and gives a one-line gloss, which is basic but useful. However, the most important parameter, 'arguments', is left opaque as 'JSON string of arguments for the connector operation' with no indication of what the create_item arguments should contain.

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 says 'Xero connector operation `create_item`' which essentially restates the tool name and platform mapping without explaining what create_item does or what a Xero item is. It does not state a clear verb+resource relationship beyond the name itself, and it does not distinguish itself from sibling tools like xero_create_invoice or xero_create_contact.

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?

The description provides no guidance on when to use this tool versus alternatives. It mentions routing and governance constraints but never states 'use this when you need to create a Xero item' or notes any exclusions or sibling comparisons. The 'when resuming a write' clause hints at an approval flow but does not explain when that applies.

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