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

Annotations already declare a read-only, closed-world operation, and the description adds genuinely useful behavior: missing facts sort last and remain null rather than being estimated, rates are decimal fractions, and a checkUrl is returned. What's missing is any note on latency, failure modes (e.g., invalid ISINs), or what the row payload contains.

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?

Front-loaded with the operation and scope, then each subsequent sentence adds a distinct behavioral fact (tie-breaking, null handling, rate format, return value). No sentence repeats structured data or the title.

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?

With no output schema, the description does well to name checkUrl and explain null handling, but it never describes what a ranked row otherwise contains (e.g., the fund name, the metric values, ranks), which an agent needs to interpret the result. The parameter surface is otherwise adequately covered.

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, and it largely does: it maps the four enum metrics to human terms ('ongoing charge, US share, pairwise overlap and holdings count'), explains 'Rows follow the criteria in order' (criteria array semantics), and clarifies the rate format for ongoingCharge. It does not explain the asc/desc direction parameter or the ISIN check-digit requirement, which the schema covers only partially.

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?

States a specific verb and resource ('Sort 2 to 10 funds') with concrete scope constraints and the exact metrics that can drive the ordering. It implicitly distinguishes itself from compare_funds by being an ordering operation rather than a comparison, but never names the sibling or spells out the difference.

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 2–10 fund bound and 'up to three' criteria imply the intended usage context, and 'Sort by' makes the ordering intent clear. However, there is no guidance on when to pick this over compare_funds or search_funds, and no stated prerequisites or exclusions.

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