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

Annotations already cover read-only, idempotent and non-destructive, but the description adds material context beyond them: a PREMIUM license gate, the matching algorithm and AP interpolation convention, and critically the error contract (never raises a protocol error, returns an {"error": ...} object with a fix hint) plus the retry-safety implication. That error-shape disclosure is exactly the kind of behavioral detail annotations cannot express.

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 purpose and protocol, then example, then usage guidance, then error contract — a sensible ordering. The inline example is long but the tool has no output schema documentation burden elsewhere and it disambiguates the array-of-objects params, so it largely earns its space. Minor deduction for the awkward 'PREMIUM (license).' sentence fragment interrupting the opening line.

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 scoring tool with six parameters, nested-free schema, full schema descriptions and an output schema, nothing an agent needs is missing: input shape, algorithm, metric definitions, error behavior, retry safety, and the sibling to run first are all present.

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 earns an extra point by giving a concrete worked input showing the actual shape of predictions entries (box/label/score with a 0.9 confidence) and the ground_truth entries, and by tying iou_threshold to the matching behavior rather than only to a range. It does not cover box_format or the yolo image_width/height requirement, which the schema handles.

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 ('Score detections against ground truth') and immediately pins down the protocol (greedy matching, IoU threshold, highest-confidence first) plus the reported metrics (per-class precision/recall/F1, VOC-2010 all-points AP). No sibling tool does evaluation, and the description explicitly carves out nms as a separate prior step, so the boundary is unambiguous.

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?

'Use to compare two models on the same held-out set' gives a positive selection criterion, and 'Not for cleaning up a single model's overlapping output first - run nms before this' gives an explicit exclusion naming the sibling to use instead. This is the when/when-not/alternative pattern at full strength.

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