sapiens_reference

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

Despite readOnlyHint already being provided, the description adds substantial behavioral detail: pagination behavior (page/limit, hasMore), the distinction between own images (history/favorites) and public/third-party items, and the exact ID/URL usage rules for downstream tools. This goes well beyond the annotation's safety signal and meaningfully shapes how an agent should treat results.

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 dense and packs a lot of necessary information, but it is presented as one long paragraph rather than structured bullets. Still, most sentences earn their place: the purpose is front-loaded, bucket semantics are explained, and downstream usage rules are included without obvious redundancy.

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 no output schema, the description compensates well by describing normalized item behavior and how to route imageId/url to other tools. It covers all buckets, pagination, mode, source, filtering options, and an alternative tool for public characters, making it sufficiently complete for an agent to invoke the tool correctly.

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 100%, but the description adds value beyond the property descriptions by explaining bucket semantics, default mode behavior ('mine [default, inclui rascunhos]'), pagination defaults, and cross-tool rules such as using imageId only for own images and url for public items. This materially clarifies how to fill parameters correctly.

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 function as the Sapiens global reference popup for browsing media banks and selecting items that become image/video references. It uses specific verbs ('navegar os bancos e pegar') and identifies the resource (reference buckets), and it distinguishes itself from at least one sibling by pointing to sapiens_character action=list_public for public characters.

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 context for when to use the tool: to browse reference buckets in read-only mode, with sub-action 'browse'. It also names an alternative for public characters ('Personagens públicos também têm porta dedicada em sapiens_character action=list_public'), but it does not broadly contrast against other sibling tools like sapiens_stock_video or sapiens_gallery, so it stops short of full alternative routing.

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