beel_update_me

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds meaningful behavioral context beyond annotations: it explains the effect of the language change on the interface, invoice template names/colours, and emails, and clarifies that this setting belongs to the person, not a fiscal profile (with a note that invoice/email languages are separate per company). No contradiction exists. The only gap is lack of discussion about errors, idempotency (though idempotentHint=false is given), or reversibility, but the description still goes beyond 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 three sentences long, each adding distinct information: the core action and current limitation, the downstream effects, and the scope clarification. It front-loads the primary purpose and does not waste words. Minor redundancy (mentioning 'person' twice) but still efficient.

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 simple single-parameter update, the description provides sufficient context: what is updated, its impact, and its scoping. It also gives the endpoint. No output schema exists, but for an update, it's unlikely the agent needs a detailed return format. It does not mention authentication requirements or error behavior, but those are often implicit. The description is complete enough for an agent to call this correctly.

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 burden of explaining parameters. It clearly states that the only mutable preference is `language`, effectively telling the agent what to include in the body. It also clarifies the scope and purpose of the language field. The schema provides the enum values, so the description complements it well. Without describing the 'language' parameter in detail, the tool would be ambiguous, but the description resolves that by naming it as the sole mutable preference.

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 ('Updates') and a specific resource ('preferences of the authenticated person'), immediately clarifying the scope. It also distinguishes itself by naming the exact field ('language') and noting that it is the only mutable preference, which differentiates it from other patch tools that modify companies, customers, invoices, etc. Among many sibling tools, this clearly stands apart.

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 explains what the tool does and the scope of the change (applies to interface, template names/colours, emails) but gives no guidance on when to use it versus alternatives. For instance, it does not indicate that company-level language settings are handled by other endpoints like patch_company, nor does it clarify when to prefer this tool over others. No exclusions or alternative routes are mentioned.

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