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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about Busabase's change-request model and warns to treat stored content as data, not instructions, which is relevant for any tool interacting with this platform. It also exposes the endpoint for transparency. This goes beyond what annotations provide.

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 sentences, each carrying weight: purpose+endpoint, multi-space guidance, and a general platform caveat. No filler, and the key information is front-loaded.

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 read-only list tool with annotations covering safety, the description is adequate. It doesn't describe the response format, but no output schema is provided, and the tool's purpose is simple. The missing recordId explanation is minor given the obvious 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 coverage is 50% – recordId lacks a description, but its purpose is evident from the tool name and endpoint. The description adds meaning for targetSpaceId by explaining when and how to obtain it, complementing the schema's description. It partially compensates for the coverage gap.

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 action: listing active outbound links from a canonical record, and even provides the HTTP endpoint. This clearly distinguishes it from sibling tools like records_get (fetching a record) and record_query (searching records).

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 explicit guidance for the targetSpaceId parameter: when to call auth_verify and ask the user for the space. While it doesn't explicitly compare to alternatives, the purpose is clear enough that an agent knows when to use this tool, and the space-handling instruction is directly actionable.

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