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

With no annotations, the description carries the full burden of disclosing behavior. It mentions 'without returning configured secrets', which is a useful security constraint, but it does not explicitly state that the tool is read-only, whether it makes external calls, or what 'stale-data state' means in practice. This leaves the agent without clarity on side effects or data freshness implications.

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 extremely concise, fitting the key information into a single phrase. It front-loads the primary content (portfolio risk utilization) and appends the security qualifier. While not a full sentence, it avoids redundancy and earns its place.

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?

This is a simple tool with one parameter and no output schema, but the description should fill the gap by explaining what the response includes. It lists three data points but doesn't clarify their meaning or structure. Terms like 'execution mode' and 'stale-data state' are left undefined, and there's no mention of response format or error handling.

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% for the single apiKey parameter, which is clearly documented. The description adds no additional parameter semantics, but since the schema already provides full information, a baseline of 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 lists the information included (utilization, execution mode, stale-data state) but lacks a verb stating the action. It implies a 'get' operation from the tool name, but the description itself is a noun phrase, making the purpose somewhat vague. It distinguishes from other portfolio tools by mentioning risk-specific data, but doesn't explicitly say 'retrieve portfolio risk'.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or scenarios where this tool is preferred over sibling tools like portfolio_positions_list or portfolio_activity_list.

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