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

The description goes well beyond annotations (readOnlyHint:true) by detailing safety parameters (max 90% deployment, 30-min early exit, slippage guard, 2-hour window), instrument selection rationale, fee structure, and risk disclosures. It explicitly clarifies that the tool only analyzes and does not move funds, adding critical behavioral transparency. There is no contradiction with annotations.

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 front-loaded with a bold header and summary, then organized into clear sections. While it is somewhat long (roughly 25 sentences), each paragraph earns its place—instrument rationale, safety parameters, and contraindications—all essential for safe usage. A minor trim of redundant explanation about 'This tool does not move funds' could improve conciseness.

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 the tool's moderate complexity (4 parameters, annotated readOnly, with an output schema as per context signals), the description is thorough: it explains when to use, safety guards, risk disclosure expectations, and the analytical nature. The output schema covers return values, so the description's focus on usage and safety is appropriate and complete for this domain.

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 100%, so the baseline is 3. The description adds significant value by providing context for the riskTolerance enum (explains what moderate means with 0.15% slippage) and details for settlementDeadlineUtc ('30 minutes before'), which is not fully captured in the schema descriptions. However, dryRun's default is already in schema, and amountUsdc's minimum is duplicated.

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 starts with a clear verb+resource combination ('analyzes whether idle settlement float can be productively deployed into a yield-bearing instrument') and distinguishes itself from siblings by specifying its unique function (yield routing analysis, not fund movement). The optional/client-directed-only note further clarifies its role.

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 explicit guidance on when to use this tool (analysis of idle settlement float) and when not to use it, listing four specific conditions (windows <2 hours, amounts <$50,000, unacknowledged risk disclosure, time-critical settlement). It also clarifies what the tool does NOT do (move funds), which differentiates it from sibling tools like 'settlement.execute' or 'mercury.send'.

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