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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds valuable behavioral context: the user must be shown the exact parameters before creation, there is no bulk/apply-all behavior, and a post-create verification step is required. This goes beyond the basic write semantics and helps the agent understand the intended interaction flow.

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?

Three concise sentences, each earning its place: the first states the action and required confirmation, the second clarifies scope (one at a time, no shortcut), and the third gives the mandatory follow-up action. No filler or redundancy.

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 create tool with 8 parameters and no output schema, the description covers the essential workflow: pre-conditions (user confirmation), constraints (one at a time), and post-conditions (call list_cost_centres). It does not explain return values, but the follow-up instruction effectively compensates by telling the agent how to verify the result and continue the workflow.

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 already covers all 8 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaning by identifying which parameters are user-facing and must be confirmed (name, kind, parent, effective date, reason), and by emphasizing that only one centre is created at a time. This is a helpful layer above 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 action ('Create one cost centre for an entity') and specifies the exact fields to be confirmed with the user (name, kind, parent, effective date, reason). It also distinguishes this tool from a bulk or apply-all operation by explicitly saying there is no shortcut, setting it apart from sibling tools like create_profit_centre.

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 gives clear usage context: show the user the exact details before creating, create one at a time, and follow up by calling list_cost_centres again to explain which mapping suggestions can use the new centre. It does not explicitly mention alternatives or when not to use this tool, but the workflow is well-defined.

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