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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses substantive behavior the annotations cannot: the four-plus-four question split, the 'lower of the two' scoring rule, and exactly what is returned in each mode. Return format and pagination concerns are absent, but for a pure computation tool that gap is minor.

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?

Four sentences, front-loaded with the core action, then methodology, then the two return shapes. Every sentence carries information an agent needs; nothing is boilerplate or restated from the title.

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?

There is no output schema, so the description must carry the return contract, and it does: questionnaire plus choices when empty, and profile, score, rationale, model allocation, illustrative return and volatility when scored. Combined with the single well-documented parameter, an agent has everything needed to call it correctly in either mode.

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% and each of the eight sub-answers carries a fully annotated 1-5 scale, so the schema does the heavy lifting. The description adds the aggregate framing ('eight answers scored from 1 to 5') and the omit-to-get-questionnaire behavior, but the latter is already stated in the answers property description. 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 opens with a specific verb and resource: 'Score the eight-question risk questionnaire and map the client to a model portfolio.' It also names the two inputs it combines (capacity and willingness) and the output (model portfolio), which makes the tool's identity unmistakable. It stops short of naming a sibling it differs from, so it lands at 4 rather than 5.

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 clear conditional usage: call with no answers to retrieve the questionnaire, call with eight answers to score. That is a genuine when-to-use rule for both modes. It does not address how this differs from adjacent planning tools such as portfolio_review or retirement_plan, so 4 is the right ceiling.

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