Ranked sources AI search returns (Perplexity Search API)

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond that: requires a paid PERPLEXITY_API_KEY, returns ranked results with title/URL/snippet/date, has no answer generation, and is cheaper and repeatable. No contradiction with annotations.

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 with no filler: the first states the core purpose, the second differentiates from the sibling and gives the strategic use case, and the third states the authentication requirement. Every sentence earns its place and 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?

Given the rich schema with 100% parameter coverage, clear annotations, and the description's addition of API key requirement, return shape, cost profile, and repeatability use case, an agent has everything needed to select and invoke this tool correctly. No output schema exists, but the description lists the returned fields (title, URL, snippet, date), which is sufficient.

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%, so the schema already explains all 8 parameters thoroughly. The description's parameter-related mentions ('up to 10 questions', 'your domain') repeat what the schema already states via maxItems and the domain parameter description. It does not add new parameter-level meaning, so baseline 3 is appropriate.

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 verb and resource: 'Ask Perplexity's Search API which pages it retrieves as sources' for up to 10 questions, and whether a given domain is among them. It names the sibling ai_citation_check and explicitly differentiates itself by returning only ranked results with no answer generation.

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: it is for source-only, repeatable checks, tracking share of sources over time, and seeing which competitors AI search pulls from. It explicitly contrasts with ai_citation_check and states what this tool does NOT do ('no answer generation'), giving the agent a clear selection criterion.

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