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

Annotations cover readOnlyHint=false, idempotentHint=true, openWorldHint=false, destructiveHint=false. The description adds real value beyond these: it discloses the scheduling capability gap per platform, states idempotency semantics ('calling twice returns the same smb_id'), lists the 12 supported platforms, and flags cost ('free') and rate limiting ('[limited]'). This is exactly the kind of behavioral context annotations can't express.

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?

Front-loaded with purpose, but the sentence about schedule_appointment completing only on Cal.com is dense and syntactically awkward ('only completes on Cal.com bound to our one connected account — the other 11 always fail schedule_appointment honestly, uncharged'). The trailing bracket tags ([free, requires key] [limited]) are cryptic stubs rather than integrated information. Information density is high but structure suffers.

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 8-param import tool with no output schema, the description covers platform support, idempotency, cost, rate limits, auth requirement, and downstream-consumer semantics. The main gap is it does not describe the returned smb_id shape or any error semantics when the URL is on an unsupported platform — relevant since there's no output schema to fall back on.

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 88%, so the schema carries the bulk of parameter documentation. The description adds little parameter-level detail beyond the schema except the platform-count constraint on booking_url. Baseline 3 is appropriate when the schema does the heavy lifting and the description does not compensate further.

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?

Clear specific verb+resource: 'Turn a public booking URL into a callable smb_id'. Names the consumer tools (send_message, capture_lead), which distinguishes it from siblings. Lacks a direct contrast to check_booking_link, which is the nearest sibling, but the operation is unmistakably distinct.

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?

Strong routing guidance: states the smb_id is used by send_message and capture_lead, and warns that schedule_appointment only works on a Cal.com account bound to the service (the other 11 platforms fail). That's actionable when/when-not. No explicit mention of check_booking_link as an alternative for pre-flight validation, which would have made it a 5.

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