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

Annotations only say readOnlyHint=false and openWorldHint=true, which is coarse for a 17-action tool that is mostly reads; the description usefully discloses which sub-actions are LEITURA vs ESCRITA and that writes always act on the session user's own account ('identidade sempre da sessão'). It also discloses a failure return shape ({success:false,error}) for update_username and that results are derived, dated snapshots built from cheap in-prod queries ('sem custo'). It stops short of describing side effects of follow/unfollow or rate/limit behavior beyond the limit param.

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?

Front-loaded correctly with the aggregation statement and the read/write split, but the body is a dense run-on with heavy parenthetical nesting, mixing action semantics, deprecation notes, file-saving instructions and sibling boundaries in long sentences that reward re-reading. It earns most of its length given 17 actions, but a bulleted or grouped structure would carry the same content with less parsing cost.

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?

No output schema exists, and the description does a reasonable job describing returns: 'get' as a full card, 'voz' as a dated derived snapshot under the sapiens.voz/v1 contract, error shape for update_username, and read counts for notifications. For a 17-action, 12-parameter tool it covers what an agent needs to pick and invoke an action, though the exact return shape of follow/unfollow and the favorite-list mutations is not stated.

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 92%, so the baseline is 3, but the description adds real meaning: it maps parameters to sub-actions in prose and, importantly, tells the agent where each id comes from (followingId via sapiens_community participants/search_users, toolId via sapiens_repertorio action=search_tools, listId via action=favorite_lists, notificationId from action=notifications). That cross-tool discovery guidance is not in the schema.

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?

Opens with a specific framing ('o tudo junto do perfil do user /u/<username>, user-tier') and then enumerates exactly what it aggregates: identidade + nível/XP + saldo, badges, golden tools. It also explicitly names the boundaries against siblings (sapiens_gallery, sapiens_repertorio, sapiens_character, sapiens_persona, sapiens_meta), so an agent can distinguish it without opening other schemas.

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?

Guidance is per-action: read vs write sub-actions are grouped and labeled, 'voz' has an explicit trigger ('quando o user pedir minha voz ou meu retrato do Sapiens... chame e salve como sapiens-voz.json'), 'soul' is flagged DEPRECATED with the replacement (sapiens_sintetico action=soul), and id discovery paths are named for followingId, toolId, listId and notificationId. Exclusions are stated (large profile parts live in other tools).

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