capital_auction

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

With no annotations provided, the description carries the full disclosure burden and does so richly. It explains key behaviors: scoring via analyze_stock, the 0.5 confidence veto, diversification-driven fit calculation, thesis-based utility discounts, and the fact that it only suggests and never executes. This gives an agent a strong mental model of what the tool does and its 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?

The description is dense and relatively long, but every sentence adds substantive detail about the algorithm, data sources, or constraints. It front-loads the main purpose before diving into mechanics. It could be tightened, but the complexity of the tool justifies most of the length.

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?

For a complex tool with no annotations and no output schema, the description is remarkably complete. It covers the ranking logic, input sourcing, candidate scoring, confidence threshold, diversification preference, thesis handling, and safety limitation. The only notable omissions are explicit return format and full parameter details, but the behavioral core is thoroughly specified.

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 0%, so the description must compensate. It clearly explains cash_eur as the new cash to allocate and implies path refers to the local export used for bucket values, but base_currency is never mentioned and candidate_tickers is only indirectly tied to 'candidate stocks.' The description partially clarifies the parameters but leaves meaningful gaps for a 4-parameter tool.

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 clearly states the tool's specific action: ranking every use of new cash and allocating cash_eur to the highest marginal utility winners. It also distinguishes the tool by noting it is suggestion-only and never sends an order, which separates it from execution-oriented sibling tools. This is a specific verb+resource statement with clear scope.

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?

The description provides substantial context about the tool's internal logic and constraints, implying it is for cash allocation suggestions driven by marginal utility. However, it does not explicitly state when to use this tool versus alternatives like allocate_cash or rank_candidates, and the only exclusion is indirect: 'never sends an order.' This is implied usage guidance rather than explicit routing.

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