Perplexity Embed

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds substantial non-obvious context on top: index sends source text to Perplexity while search sends only the query, vectors are local per project and never returned, unchanged items are never re-embedded, per-token pricing for both models, and the cascade behavior of deleting chats/projects. This is exactly the behavioral detail annotations cannot convey.

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?

Purpose is front-loaded, then privacy/cost, then per-action behavior, then a help pointer. The prose is dense but nearly every sentence carries information; a touch of compression in the pricing and model-naming clauses keeps it from being a clean 5.

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 12-parameter, four-action tool the description covers the essential surface: what each action does, the confirm requirement for delete, the iteration behavior of index, data-locality and cost implications, and deletion cascades. An output schema exists, so return-value detail is correctly omitted and the description does not need to carry it.

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?

With 100% schema coverage the baseline is 3, but the description goes beyond it by explaining cross-action semantics that the per-field schema text does not: the interaction of 'limit' with 'remaining' across calls, 'confirm true' for delete, and the meaning of omitting 'model'/'encoding'/'dimensions' on delete. This meaningfully reduces the chance of mis-invocation on a 12-parameter multi-action tool.

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 opening states a specific verb and resource: 'Index your saved chats, completed research reports or texts as vectors and search them by meaning.' This clearly frames the tool as a local vector-index/retrieval utility, distinct in kind from the query-oriented siblings. However, it never explicitly differentiates itself from the sibling perplexity_search, so an agent has to infer that distinction from context.

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 real operational guidance: 'call it again until 0' for incremental indexing, 'delete removes vectors (confirm true)', and notes that deleting a chat or project cascades to vectors. It does not, however, name an alternative tool or state when-not to use embedding versus perplexity_search, so the routing guidance is incomplete.

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