review_decisions

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

With no annotations, the description carries the full behavioral burden, and it does so well: it discloses the free pricing provider, the refusal behavior under 10 decisions, and the conditional opportunity section. It does not cover failure modes or data limitations, but the key guardrail and conditional behavior are clearly stated.

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 compact and front-loads the core purpose with 'Shadow portfolio'. Each sentence adds distinct information: the comparison method, the reported metrics and minimum sample guardrail, and the conditional opportunity section. It is slightly dense but every clause contributes.

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 usefully summarizes the outputs: mean decision alpha, hit rate, and an opportunity section. It also explains the precondition on candidate-logged decisions. It misses explicit guidance on empty results or price provider failures, but the core calling context is clear.

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?

Although schema coverage is 0%, the description defines min_days by saying decisions older than min_days are reviewed, which gives the parameter meaningful semantics beyond the bare schema field. It does not specify bounds or edge cases, but for a single integer with a default this is sufficient.

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 states a specific operation: compare logged decisions against their recorded alternatives at today's prices, and report decision alpha and hit rate. The 'Shadow portfolio' framing clearly distinguishes it from generic review or quality tools in the sibling list, even though no sibling is named explicitly.

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?

Usage context is implied rather than explicit: it applies to logged decisions older than min_days and requires at least 10 decisions before drawing conclusions. No alternatives or exclusions are mentioned, so an agent must infer when to choose this over siblings like backtest_plan or decision_quality.

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