xero_update_tracking_category

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds useful governance context: it routes 'only through the exact project/account governed connector authority' and states that `effect` is a claimed read or write which 'Spring verifies it'. This reinforces the annotation profile. However, it never explains what actually gets destroyed or changed under the update, and with destructiveHint=true that is a meaningful omission.

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 one-line lead, a single routing constraint, and a tight seven-bullet argument list. Each bullet is short and earns its place. It is not bloated; the main weakness is domain vacuity rather than excess length.

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?

Despite an output schema existing, this is a write/destructive connector tool (destructiveHint=true, idempotentHint=true) whose actual domain payload (`arguments`) is never specified. An agent cannot correctly compose an update_tracking_category call because the legitimate tracking-category fields are absent. The governance wrapper is explained well, but the actual connector operation's input and side effects are missing, making the description incomplete for correct invocation.

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 description carries the full burden since schema description coverage is 0%, and it does define each of the 7 parameters with one-line meanings (project_id, project_ref, connector_account_ref, idempotency_key, effect, approval_ref). However, the decisive `arguments` parameter — the actual JSON payload that would contain the tracking category update — is documented only as 'JSON string of arguments for the connector operation', adding no meaning about what must be in it. Domain semantics remain entirely opaque.

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 a near-tautology: 'Xero connector operation update_tracking_category', which restates the tool name without saying what updating a tracking category means, what fields can be changed, or what the operation affects. It adds only that this is a routed platform wrapper, so an agent cannot distinguish it from siblings like xero_create_tracking_category or xero_update_tracking_options without opening schemas.

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 guidance exists on when to use this tool versus alternatives such as xero_update_tracking_options, xero_create_tracking_category, or xero_list_tracking_categories. The only usage hint is implicit: approval_ref is needed 'when resuming a write', which implies writes need approval, but no explicit when/when-not criteria are stated.

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