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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds genuinely new context: the API key scope needed and the concrete consequence of non-idempotency (duplicate clients). It stops short of saying what is returned or how duplicates are detected/prevented.

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 short sentences, front-loaded with the operation class and with zero filler; each sentence carries a distinct fact (action, auth requirement, duplicate risk).

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 one-parameter write with annotations covering safety and idempotency, the description covers the key operational facts an agent needs (write, auth scope, duplicate risk). Only the return value and duplicate-failure behavior are absent.

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 must carry the param meaning; it only says 'by name', leaving uniqueness, trimming, and format unaddressed. The minLength/maxLength constraints live in the schema, so the description adds little beyond naming the field.

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?

States a specific verb and resource ('Create a client') plus the sole input ('by name'), and the 'WRITE:' prefix separates it at a glance from the get_/list_/search_ client siblings. An agent can identify what it does without opening the schema.

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?

Provides a real prerequisite ('Requires a Read & Write API key') and warns that repeats create duplicates, which implies checking first, but it never names the alternative tool (hubplanner_get_client / hubplanner_list_clients) or states the condition for using it. Usage is inferred rather than directed.

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