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

Beyond the annotations, the description discloses single-flight execution, owner/entitlement requirements, the safety boundary of actions it will never take, the review-blocker failure mode, and the semantics of 'ready.' Without an outputSchema, these behavioral clarifications are particularly valuable.

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 definition is intentionally dense rather than verbose, with purpose front-loaded and caveats structured from scope to failure semantics. A bit more structure could make the operational guarantees easier to parse, but no sentence is wasted.

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 mutation tool with no output schema, the description covers permissions, idempotency, failure blockers, and the meaning of 'ready', which is an effective full invocation model. It still does not provide a clear picture of the response shape or how business_id/agent_id are used, so it is strong but not fully complete.

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%, and three required parameters are present, but the description only clarifies semantics of the idempotency key: 'Reuse the same key to read/replay the outcome.' It does not explain what business_id and agent_id identify or how they map to the imported signup reservation, leaving two required parameters underspecified.

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 opens with a specific verb and resource: 'Reconcile database pointers for an existing imported signup phone reservation.' It also distinguishes itself from siblings through explicit negative scope: it never creates agents, buys numbers, changes provider routing, or sends messages, and it distinguishes 'database agreement' from actual activation.

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 positive context: it is for an existing imported signup reservation, owner-only, entitlement-checked, and requires review after failure. It also provides a clear negative scope, but it does not name sibling tools such as retry_activation_notification, so an agent must still infer the exact alternative for other setup/activation flows.

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