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

Adds real behavior beyond the annotations (readOnlyHint=false, openWorldHint=true): the free tier and login requirement, server-side scoring, that re-running the quiz creates a NEW profile rather than updating one, that get_quiz is static and Claude applies it conversationally, and that generate costs 450 Sinapses. That cost/state-mutation disclosure is exactly what annotations cannot convey. It omits failure modes (insufficient Sinapses, malformed answer sets) and any rate limits.

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-loads the purpose, then organizes the rest into PRIMÁRIO/SECUNDÁRIO tiers so the free-path actions are scannable first. The final sentence listing all 16 ISO codes is pure duplication of the schema enum and does not earn its place; the dense parenthetical asides also slow parsing.

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?

With no output schema, the description compensates by sketching what each action yields (48 Likert items for get_quiz, type + persona + 4-axis breakdown with confidence + history for my_profile, which arts exist for list_generated). That is enough for a six-action router. Gaps are minor: nothing on the shape of the generate response or on what happens when the profile does not yet exist.

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 80%, so the schema already explains code, answers, vinculoAnswers and nome. The description reinforces the submit_quiz flow ('manda as 48 respostas {questionId,value}') and points to get_quiz as the source of question IDs, which is useful connective tissue. However, it adds no syntax or format meaning beyond the schema, and its enumeration of all 16 codes merely restates the enum.

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 concrete statement of scope (16-persona Jung-based personality test + user profile + archetype art) and then names each of the six actions with a specific verb and resource: get_quiz, submit_quiz, my_profile, list_codes, list_generated, generate. An agent can map an intent to an action without opening the schema. It loses a point because it never distinguishes itself from the sibling sapiens_profile even though 'perfil do user' / my_profile overlaps that tool's territory.

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?

Explicitly tiers usage: 'PRIMÁRIO (de graça, qualquer logado)' for the quiz/profile path versus 'SECUNDÁRIO' for listing and art generation, and gives a sequencing rule ('combina com "gera a arte do meu tipo" depois do quiz'). It states the pre-conditions for submit_quiz (collect all 48 answers from get_quiz first). It never says when NOT to use an action or names an alternative tool among the ~29 siblings.

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