corymbus_upsert_account

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

The description explicitly warns '⚠️ Écrit dans le CRM de production', adding important behavioral context about writing to a production system, which the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) do not convey. It also clarifies the create/update branch based on id presence. No contradiction with annotations; the production warning is a valuable addition.

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 one short sentence with a warning symbol, immediately conveying the core function and production warning. It is front-loaded and every word earns its place. No unnecessary fluff.

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 tool with 9 parameters, no output schema, and a production-write side effect, the description is too sparse. It does not explain what fields mean, how extra_fields merges, return values, error possibilities, or any constraints. The production warning is helpful but does not make the tool usable without schema lookup, and the schema only documents two parameters. Significant gaps remain.

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 schema coverage at only 22%, the description should compensate for undocumented parameters. It explains the id parameter's role (omit/create, provide/update), echoing the schema, but gives no semantics for the other seven parameters (name, owner, phone, country, website, description, billing_address). The extra_fields object is mentioned in the schema but not in the description. The description adds minimal value beyond the schema.

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 clearly states the tool creates an account when no id is provided and updates when an id is provided, using a specific verb ('Crée'/'met à jour') and resource ('un compte'). It distinguishes itself from sibling tools by focusing on account upsert, similar to upsert_contact but for a different entity.

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 clear context on when to use the tool: create without id, update with id. It does not explicitly mention alternatives or exclusions, but the context is well-defined for the upsert operation. The sibling list includes read-only tools (list_accounts), but the description doesn't directly say 'use those for reading'—a minor gap.

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