compare_rank

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

No annotations are supplied, so the description carries the full behavioral burden and does not meet it. It does not say whether results are sorted by descending similarity, what the similarity score looks like or its range, whether the limit truncates the candidate list before or after ranking, or how file/address resolution errors are surfaced.

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?

A single front-loaded sentence with no filler; the purpose is stated immediately. The brevity is efficient but tips into under-specification given the complexity of the input shape.

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?

This is a nested-object tool with two composite inputs, up to 200 candidates, no annotations, and no output schema. The description says nothing about the ranking output or scoring semantics, which is the primary value an agent needs, so it is thin relative to the tool's complexity.

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?

Top-level schema coverage is 0%, but the description does supply the key semantic mapping the schema lacks: `target` is the reference and `candidates` are the functions being ranked against it. Nested fields like hex/path/symbol/address are self-documented in the schema, but `limit` gets no explanation of default or ordering effects, which is a remaining gap.

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 (rank), the resources involved (candidate functions against a reference), and the metric (canonical instruction-shape similarity). An agent can tell this is a similarity-scoring tool rather than a byte-level diff, but the description never names the close siblings compare_functions or diff_function to sharpen the distinction.

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?

No guidance on when to reach for this over compare_functions, diff_function, or rom_compare, and no prerequisites such as whether candidates must share an architecture with the target. The agent must infer usage purely from the name and the one-line purpose.

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