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

With annotations already declaring destructiveHint=true, idempotentHint=false and openWorldHint=true, the description adds genuinely new behavior: the non-idempotent retry semantics and the owner/API-key authorization requirement. It does not explain what 'destructive' means here (whether omitted fields are left untouched or reset, or whether pausing a business affects live numbers), which for a destructive update is the one behavior an agent most needs. No contradiction with 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?

Three dense sentences, no filler, and the field list is front-loaded. The 'Step 3: Pick a voice' prefix is the weakest part — it occupies the highest-attention position with flow context rather than the tool's contract. Parenthetical asides are used efficiently to define `voice` inline.

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 an 11-parameter mutation with no output schema and no annotation explanation of the destructive flag, the description covers purpose, auth prerequisites and retry semantics but omits partial-vs-replace update behavior and return/response expectations. An agent could invoke it correctly in the happy path, but could not predict the consequences of a destructiveHint=true update. Adequate, with a clear gap around update semantics.

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 only 18% across 11 parameters, so the description carries real weight, and it does name most writable fields and clarify that `voice` is 'the receptionist's voice, an id from list_voices' and that `idempotencyKey` is a retry token. It leaves `businessId` to the schema (which documents its default) and does not explain `vertical` values, `status` effects, or the notify payload shapes beyond the field names. It compensates substantially for a thin schema but not completely.

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 and resource ('Update the business') and enumerates the settable fields (name, timezone, vertical, website, voice, owner, status, notify), so an agent knows exactly what the call mutates. It is clearly the mutation counterpart to ringkit_get_business and ringkit_create_business, though it never names them explicitly. The 'Step 3: Pick a voice' lead-in is onboarding context rather than purpose and slightly muddies the opening.

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?

It gives a real prerequisite: 'Owner identity (ownerEmail, ownerPhone), status and notify need an owner; API keys are owners,' which tells the agent when those fields are even usable. The retry guidance ('Reuse an idempotencyKey when retrying; without one, each call executes again') is actionable usage instruction. What is missing is any explicit when-to-use-vs-alternatives routing (e.g., versus invite_owner for owner changes or put_routing for config).

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