Link Unfurl / Preview Card

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

No annotations are provided, so the description carries the full burden. It mentions the tool is 'lighter' than get_metadata and outputs a formatted preview, which gives some behavioral context. However, it lacks details on potential limitations (e.g., rate limits, authentication needs, error handling), leaving gaps in transparency for a tool that interacts with external URLs.

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 description is concise and front-loaded: it starts with the core purpose, lists key components, compares to a sibling tool, and states the use case—all in three efficient sentences. Every sentence adds value without redundancy, making it easy to parse quickly.

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?

Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is fairly complete: it covers purpose, differentiation, and use case. However, it lacks details on output format (e.g., structure of the preview card) and behavioral aspects like error handling, which could be important for an agent invoking this tool.

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 100% for the single parameter 'url', which is well-documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides (e.g., URL format constraints or examples). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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 clearly states the tool's purpose: 'Generate a Slack/Discord-style link preview card for a URL' with specific components listed (title, description, hero image, etc.). It distinguishes itself from sibling 'get_metadata' by emphasizing 'lighter' processing and 'formatted for UI display rather than deep analysis,' making its unique role explicit.

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 provides explicit usage guidance: 'Lighter than `get_metadata` and formatted for UI display rather than deep analysis. Useful when an agent needs to show a user what a URL contains.' This clearly indicates when to use this tool (for UI previews) versus alternatives like 'get_metadata' (for deep analysis), addressing sibling differentiation effectively.

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