Octagon Cards

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds meaningful behavior beyond that: a hard cap of eight results, the breadth of what may be compared, a caveat that related editions are not exact-card sales, and that partial/unavailable statuses can be returned. Return shape and pagination are not described, but a status vocabulary is disclosed.

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?

Four compact sentences with the core action and result cap front-loaded, followed by scope caveats. No redundant restatement of the title or annotations. Slightly terse given the absence of an output schema, but nothing is wasted.

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 single-parameter read tool with no output schema, the description covers what is returned (comparables with match reasons and differences), the result cap, the comparison breadth, and the status states. A caller could invoke it correctly without further information. Minor gap: no indication of how match reason/difference fields are structured.

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 one parameter at 100% schema coverage, the schema already documents cardId and pins it to the exact version returned by search_ufc_cards. The description reinforces 'identified UFC card version' but adds no format or validation detail beyond the schema. Baseline 3 applies.

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 names a specific verb and resource ('Read up to eight selected comparable sales for an identified UFC card version') and scopes what the comparables may contain (other parallels, releases, fighters). It clearly signals this returns approximate comparables rather than exact-card sales. It does not name or contrast with the sibling get_ufc_card_evidence, so it stops short of full differentiation.

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?

Usage is implied: the caller needs an already-identified exact card version and wants comparison sales. There is no explicit when-to-use/when-not guidance and no mention of when to prefer get_ufc_card_evidence or search_ufc_cards instead. The 'related editions are not exact-card sales' line is a useful scoping caveat but not a routing rule.

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

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

Annotations already establish readOnly, idempotent, non-destructive and open-world, so the description's job is to add semantics rather than safety. It does exactly that: currency is USD, the estimate pools raw and graded sales, and it is explicitly not a physical-copy or grader-specific appraisal — a real limitation an agent could otherwise misreport. It also discloses the returned surface (dates, known sale sources, a truncation flag, an Octagon link) and that missing estimates stay missing.

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 purpose is front-loaded in the first clause, and every following sentence adds a distinct fact — unit, aggregation model, what is returned, and the null-estimate case. There is no filler or restatement of the name or 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 responsibly enumerates the return fields and the truncation flag, which is the key completeness requirement here. Minor gaps remain: it does not describe behavior for an invalid or unknown cardId, nor clarify pagination beyond the schema's salesLimit cap.

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 both cardId and salesLimit are already documented in the schema, including the 'not a complete market history' caveat. The description reinforces that cardId must identify the exact version and adds the USD unit, but adds little specific to salesLimit. Baseline 3 applies when the schema carries the parameter burden.

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 uses a specific verb and resource: 'Read the saved estimate and recent recorded sales for one exact UFC card version.' The scope ('one exact version', 'catalogue cardId') is precise enough to separate it from search_ufc_cards and get_ufc_card_comparables, though it never names those siblings or states the contrast explicitly.

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?

Usage is only implied: an agent gathers that this is the call to make when it already holds a cardId and needs the stored estimate. There is no explicit when-to-use or when-not guidance, and no pointer to the comparables sibling for the case where the saved estimate is absent. The line 'Missing estimates remain missing' does usefully set expectations about a null result.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavior beyond them: the return shape (edition IDs and links) and the cardinality warning that "a query can match several editions." It does not discuss result ordering or ranking, which keeps it below a 5.

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?

Three short sentences, front-loaded with the capability, then the return/routing value, then the exclusions. Every clause carries information and nothing is repeated from the schema.

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?

There is no output schema, but the description compensates by describing what comes back (edition IDs and links) and by warning that one query may yield multiple editions. For a two-parameter search tool with full schema coverage and complete annotations, nothing an agent needs before calling is missing.

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 both parameters are documented in the schema (including the limit range and a full example query). The description enumerates query facets (parallel, print run, card number), which adds mild meaning, but largely restates what the schema example already conveys. Baseline 3 is appropriate.

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 ("Search Octagon's UFC catalogue") and enumerates the searchable facets — fighter, year, release, card number, parallel, print run. It also sets scope boundaries ("Does not identify uploaded photos or search other sports"), so an agent can distinguish this catalogue-search tool from the value-lookup and evidence 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?

"Returns matching edition IDs and links for card identification before a value lookup" gives clear ordering guidance: run this first, then use a value/comparables tool. The negative clause rules out photo identification and other sports. It stops short of naming get_ufc_card_comparables or get_ufc_card_evidence explicitly, so it is clear context rather than full alternative routing.

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