xero_update_project

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds meaningful behavioral context beyond those booleans: routing is restricted to a governed project/account authority, the 'effect' parameter is a claimed read/write that Spring verifies, and 'approval_ref' is required when resuming a write. These details alert the agent to the approval workflow and governance restrictions without contradicting any annotation.

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 Args list is useful and each line earns its place, but the opening sentence redundantly restates the tool name and the routing sentence is dense with platform jargon. The description is not overlong, but it lacks a front-loaded, plain-language purpose statement and could be more scannable. Overall structure is adequate but not particularly well-crafted.

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?

The description covers all 7 parameters and mentions the approval and routing workflow, and the presence of an output schema means return values need not be explained. However, it never states what 'updating a project' actually changes in Xero, what fields or behaviors are affected, or how this tool relates to sibling xero_update_* operations. An agent still lacks enough context to confidently determine whether this is the correct operation for a given task.

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?

The input schema has 0% description coverage; every parameter is a bare nullable string. The description fully compensates with an Args list defining each parameter: 'arguments' as a JSON string, 'project_id' as the authenticated Project UUID, 'project_ref' as the exact project correlation reference, 'connector_account_ref' as the project-bound connector account alias, 'idempotency_key' as the stable business-action identity, 'effect' as a read/write claim verified by Spring, and 'approval_ref' as the approved platform task UUID for resuming a write. This is precisely the semantic enrichment the schema lacks.

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 opens with 'Xero connector operation `update_project`', which restates the tool name rather than explaining what updating a project actually does. It adds a routing constraint ('Routes only through the exact project/account governed connector authority') but never states a clear verb+resource action like 'Updates the specified Xero project'. This leaves the agent reliant on the name alone to infer purpose, and it does not meaningfully distinguish from other xero_update_* 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?

There is no guidance on when to use this tool versus alternatives such as xero_create_project, xero_get_project, or the many other xero_update_* operations. The description mentions routing and approval constraints but does not specify the conditions under which this tool should be selected, nor does it point to any sibling alternative. An agent gets no help deciding whether this is the correct operation.

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