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

With only bare boolean annotations, the description adds meaningful behavioral detail: it is async, costs $0.03 per call, durably records opt-outs, and does not auto-execute other actions. This goes well beyond the annotations and tells the agent what side effects to expect.

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?

One dense, front-loaded sentence conveys purpose, scope, side effects, and async behavior, with compact bracketed metadata for cost and continuation. No filler or repetition of schema details.

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 7-parameter async tool with no output schema, the description covers selection and high-level behavior well, but it is incomplete on parameter details and the actual shape of suggested_action. The pointer to get_outcome helps, but an agent still lacks enough information to confidently construct all inputs or parse the result.

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 29%, so the description carries the burden of explaining parameters, but it adds little about smb_id, sender, received_at_iso, or inbound_channel. The intent list and mention of raw_message provide some context, but most parameter semantics are left to inference from names.

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 uses a specific verb and resource ('Classify an inbound message... and get a recommended next action'), enumerates the intent taxonomy, and clarifies that it only recommends an action rather than executing one. This makes it clearly distinct from execution-oriented siblings like send_message or schedule_appointment.

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 context: use this when a raw inbound SMB message needs intent classification and a suggested next action. It stops short of explicitly naming alternatives or when-not-to-use conditions, but the 'async→get_outcome' pointer and 'nothing else is auto-routed or auto-executed' provide practical routing guidance.

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