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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, and the description is fully consistent with them. Beyond annotations it adds rich behavioral context: the ~4x/day weekday-only refresh cadence with an explicit 'dead overnight and on weekends, not a continuous 4-hourly cadence' correction, the >72h stale threshold that deliberately tolerates a normal Fri→Mon gap, the shared-pipeline sync guarantee, macro_score being null on pre-2026-08-26 assessments, and the point-in-time snapshot vs live distinction. This is exactly the kind of context structured fields cannot convey.

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 key usage guidance and staleness caveats are front-loaded before the field reference, and the two-perspective framing is clearly sectioned with bolded bullet groups. However, it is long — effectively a mini API reference covering every field. Given the tool's genuine complexity (two perspectives, many subtly distinct fields like macro_score vs risk_appetite_score), most sentences earn their place, but it could be tightened without losing value.

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 high-complexity tool, this is complete. It covers refresh cadence, staleness semantics with the weekend exception, Monday-morning handling, field-by-field meaning, the macro_score/risk_appetite_score distinction, the trend-field rationale, the point-in-time vs live caveat, and the cost tier. An agent has everything needed to call it correctly and interpret results accurately — the output schema handles return structure while the description handles semantics.

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?

With 100% schema coverage on the single history_count parameter, the baseline is 3. The description adds genuine value beyond the schema: it clarifies 'last N prior assessments for each' (matching the schema's per-assessment semantics) and explains that macro_score_trend is 'computed automatically (no history_count needed)' — resolving a likely confusion about whether history must be requested. That marginal but real clarification justifies a 4.

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 specific verb+resource: 'Combined AI market assessment: macro regime + market outlook in a single call.' It explicitly defines the two perspectives returned (REGIME answering 'how much equity risk to take' and OUTLOOK answering 'which direction and sectors to trade'), and later distinguishes itself from get_market_pulse ('not live prices (use get_market_pulse for live)'). An agent cannot confuse this with any of the 18 siblings.

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?

Gives explicit decision guidance per perspective: use REGIME 'for position sizing and asset allocation decisions' and OUTLOOK 'for sector preference and directional bias.' It states when NOT to treat results as current (stale flags, Monday morning caveat), names the live-prices alternative (get_market_pulse), and flags the Pro-tier/cost constraint. This is actionable routing, not just a tagline.

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