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

The description adds useful behavior beyond annotations: it reveals that this is a URL-generation tool rather than a mutating 'create' operation, that OG images render automatically on unfurl, and that api_key handling differs between public endpoints and /mcp/mcp. The annotations already mark readOnly and idempotent, and the description is consistent with them.

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 compact and front-loaded: the first sentence gives the core purpose, the second lists formats, and the third handles api_key nuance. Every line earns its place without redundancy or filler.

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?

The description covers the main behavioral and usage aspects, and the output schema can explain return values. It leaves some ambiguity around how an agent should obtain the api_key when calling via /mcp/mcp, but otherwise the description is complete enough for correct invocation.

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 0%, but the description compensates by enumerating valid format values and explaining api_key optionality/requirements per endpoint. ranking_id is not described, but its role is self-evident from the tool name and required status.

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 and resource: 'Return share-ready URLs + embed snippets for a ranking.' It also lists concrete output formats, making the purpose clear. It does not explicitly differentiate from sibling tools like aimrank_get_data_card, but the focus on share/embed artifacts distinguishes it sufficiently.

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: the output is meant to be pasted into tweets, blogs, Notion pages, or Slack messages. It does not explicitly say when not to use this tool or point to alternatives, but the usage scenario is well implied.

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