Boxerbook

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds genuinely new behavior: the response is exhaustive (records going in, result detail, card, broadcasters, sources), includes forecast signals plus market consensus 'when known', and imposes a citation requirement via 'Cite the url.' It does not mention missing/unknown bouts or error behavior.

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 dense sentence that front-loads the purpose ('One bout in full by Boxerbook bout id') and then lists the payload, closing with the citation instruction. No filler sentences, nothing redundant.

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?

The description, combined with a 100%-covered single-param schema, full annotations, and an output schema, gives an agent everything needed to invoke correctly and to know how to present results. Minor gap: no statement about what happens when the id does not resolve.

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% and the id parameter is already documented as a 'Boxerbook bout id' with its origins. The description restates the same fact ('by Boxerbook bout id') without adding format, range, or failure semantics beyond the schema.

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 resource and scope: 'One bout in full by Boxerbook bout id', then enumerates the contents so an agent knows this is a single-entity lookup rather than a list. It does not name a sibling, so the differentiation from boxing_results or next_fight is inferred rather than stated.

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: call it when you have a bout id and want the complete record. The description hints where ids come from ('from a schedule, results, search or a /bouts/<id>/<slug> url'), but there is no explicit when-to-use/when-not or named alternative for fetching bout data in bulk.

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 read-only, idempotent, closed-world, non-destructive behavior. The description adds genuinely non-obvious behavior: fuzzy name resolution with a best-match result plus a secondary other_matches list, and a citation requirement on the returned url.

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 and single-paragraph, but roughly half of it is a long enumeration of returned fields that is duplicated by the existing output schema, so that clause does not fully earn its place. The genuinely load-bearing sentences are the search-resolution one and the cite-the-url one.

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 an output schema present, the description needn't explain return structure, and it covers the two things an agent could get wrong: ambiguous name matching and attribution. Adding which sibling to prefer for a list-style lookup would make it complete.

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% and already documents the name/slug/id forms, so the baseline is 3. The description earns one more point by explaining the resolution behavior specific to a name value (site search, best match, other_matches list) — semantics the schema cannot express.

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?

Opens with a specific verb+resource ('One boxer's card by name, slug or Boxerbook id') and enumerates the returned content, so an agent knows exactly what it gets. It never explicitly distinguishes itself from the very close sibling search_boxers, leaving that boundary to be inferred from 'returns the best match / other_matches'.

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?

Gives concrete in-tool guidance: a name is resolved via site search, and other_matches must be checked when the name is common — plus an obligation to cite the url. It stops short of naming alternatives (search_boxers, next_fight, rankings) or stating when not to use this tool.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value: newest-first ordering, the calendar-day window semantics with default 2, and an explicit instruction to cite each bout's URL. It does not discuss pagination or how many results to expect.

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?

Scope, ordering, return fields, usage examples, and the citation requirement are all front-loaded with no filler. The opening sentence is long and clause-heavy, which slightly hurts scanability, but no sentence 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?

With an output schema present and rich annotations, the description need only explain scope and behavior, which it does. It covers the default time window, ordering, and key result fields. The main gap is that it never explains how the optional country or division parameters narrow results.

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 schema already documents all three parameters, including the days default and min/max and the country/division formats. The description reinforces the days semantics with '1 = today, 2 = last night and today' but says nothing about country or division filtering. 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 resource ('completed professional bouts'), a precise scope ('last N days ... up to 14'), ordering ('newest first'), and the fields returned. The word 'completed' distinguishes it from the forward-looking boxing_schedule sibling, so an agent can route between them without opening a schema.

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?

Gives concrete use-case examples ('who won last night', 'results this weekend') and makes clear this is for past results, which implicitly excludes boxing_schedule and next_fight. It stops short of naming the alternative tool or stating when not to use it, so it is clear but not exhaustive.

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/non-destructive, and the description adds genuine non-obvious behavior: the when=today case retains last night's cards that started under 6 hours ago, and forecast/market data is only present 'when known'. The citation instruction ('Cite the url of each card or bout') also discloses a usage requirement not visible in structured fields.

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-loads the resource and scope, then a compact field list, then usage triggers, then the caveat and citation rule. Slightly dense with the inline field enumeration, but every clause carries information.

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?

An output schema exists, so return values need no explanation, and the description still covers grouping, optional market data, and the citation obligation. Nothing critical to correct invocation is missing for a three-optional-parameter read tool.

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, but the description earns a bump by quantifying the 'today' carry-over window (cards that started under 6 hours ago), which the schema's vague 'cards still running from last night' does not specify. Country and division semantics are left entirely to the schema.

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 resource and scope ('Upcoming professional boxing cards worldwide, grouped by card') and enumerates what each card contains (date, start_utc, venue, promoter, broadcasters, bouts with records, division, rounds, title, forecast). The 'upcoming' framing cleanly separates it from boxing_results and next_fight without ambiguity.

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?

Provides explicit user-question triggers ('who is fighting tonight / this weekend', 'what boxing is on'), which map usage to intent well. It stops short of naming alternatives (e.g., boxing_results for past cards, next_fight for a single fighter), so the routing is clear but not exhaustive.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavior beyond those annotations by stating the unknown-id error behavior and that the result is Markdown text with metadata.

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 the return scope, then adds only the key operating rules: pass id unchanged, unknown ids error, cite the url. There is no wasted text.

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?

An output schema exists, annotations cover safety and idempotency, and the schema fully documents the single parameter. The description completes the picture with document scope, error behavior, output format, and citation guidance.

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%, and the schema already documents the accepted id forms. The description adds the useful constraint to pass the id unchanged, but it does not add substantial parameter meaning beyond the schema.

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 states a specific retrieval operation and lists exactly what document types it returns: boxer card, bout details, card with bouts, or division rankings. It also distinguishes the tool from search by requiring an id returned by search.

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?

It clearly says to use an id returned by search and to pass that id unchanged, and it documents the unknown-id error case. It does not explicitly compare against sibling tools such as boxer, bout, or rankings, so it stops short of full alternative routing.

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 cover the safe read-only, idempotent profile, and the description adds useful behavioral context: returned fields, conditional forecast/market data, null semantics, and a citation instruction. It does not mention auth, rate limits, or error behavior, but that is reasonable given the annotation coverage.

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 definition is front-loaded with the core purpose and packs the returned fields, null case, fallback behavior, and citation instruction without filler. Every clause earns its place.

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 one fully documented parameter, an output schema, and safety annotations, the description supplies the remaining context an agent needs: what is returned, when next_fight is null, and to cite the URL. Nothing essential is missing for correct invocation.

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 query parameter is already documented in the schema as a boxer name, slug, or Boxerbook id. The description repeats that same accepted input forms without adding syntax, format, or validation details beyond the schema.

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 resource and scope: a boxer's next scheduled bout, resolved by name, slug, or id. It clearly distinguishes the next bout from past results via the null fallback to last_result.

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?

It gives clear usage context for upcoming fights and explains the no-upcoming-bout case via next_fight being null and last_result being the latest bout. It does not explicitly name alternative sibling tools such as boxing_schedule or boxing_results, so it falls short of full when-to-use guidance.

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 cover readOnly/idempotent/non-destructive/closed-world, so the description's job is lighter. It usefully adds that results are capped at 15, include records, and carry a citation requirement ('Cite the url'), which is real behavioral context beyond 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?

Two tight sentences, front-loaded with the core action (top 15 of a division) and the source choice. No filler; every phrase contributes actionable detail.

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 an output schema present, the description needn't explain return values, and it covers the essentials an agent needs: scope (top 15), source selection, division format, and citation behavior. Nothing critical is missing for correct invocation.

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% and both parameters (division, publisher with enum) are already documented in the schema. The description mostly restates accepted formats and the default rather than adding syntax or edge-case guidance, so 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+resource: returns 'the top 15 of a division' with the rating source enumerated. It clearly distinguishes this from result/schedule siblings like boxing_results or boxing_schedule by describing a ranked list, and even names the two selectable ranking systems.

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?

Explains how to choose between the Boxerbook default and a publisher list, and how to specify a division (code or name). It gives clear usage context but does not explicitly contrast with sibling tools or state when NOT to use it.

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, non-destructive, closed-world, so the safety profile is covered. The description adds behavior annotations cannot express: unmatched queries return an empty list, each hit carries an id for fetch plus a title and canonical url, and id-shaped queries are resolved directly rather than searched.

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 core action and then layered with query forms, hit shape, and citation instruction; nearly every clause carries information. It is a dense single paragraph and slightly run-on, but no sentence is filler.

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?

The output schema covers return values, so the description only needs to hint at hit shape (id, title, url) and citation guidance, which it does. For a one-parameter search tool it tells the agent everything needed to call it correctly and what to do with the result.

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% and already documents the single query parameter, but the description goes further by giving accepted query syntax — two surnames separated by "vs", division names, and id prefixes like bout:123. That syntax guidance is the main thing an agent could not infer from a maxLength-200 string field.

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 the whole catalog with one query") and then enumerates the entity types covered: boxers by name, bouts by two surnames, cards, divisions, and direct id lookups. This lets an agent distinguish it from narrower siblings like search_boxers or rankings without opening any schema.

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?

Gives concrete usage context — connectors that can only call search and fetch should start here — and shows the query forms that select each mode ("Inoue vs Nakatani", "heavyweight rankings"). It does not explicitly say when to prefer the dedicated sibling tools (search_boxers, rankings, bout) over this one, which keeps it short of a 5.

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/non-destructive, so the description correctly spends its words elsewhere: the 20-result cap, best-match-first ordering, the returned field list, and an explicit citation obligation ("Cite the url"). It does not address zero-result behavior or whether the cap implies no pagination, but the added context is well beyond what the annotations supply.

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?

Two sentences, zero filler, with the core action and result shape front-loaded and the chaining instruction second. Every clause carries information an agent needs: cap, ordering, return fields, next step, citation rule.

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 one-parameter search tool with an output schema and full annotation coverage, this is essentially complete; the returned fields are even enumerated. The only minor omission is what to do when nothing matches (empty result vs. suggest alternative spelling), which an agent might otherwise need to infer.

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% and the schema already documents q as "a name or part of it" with length bounds. The description adds real semantic value by framing q as a fuzzy/ambiguous-match input ("best match first", "spelling unsure"), which tells the agent how to interpret ranked results rather than expecting an exact match.

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 ("Find boxers by name"), plus scope details: max 20 results, best-match ordering, and the exact fields returned (id, slug, name, country, division, record). This clearly separates it from siblings like boxer (single lookup) and next_fight, which the description explicitly routes to.

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 this when a name is ambiguous or its spelling unsure" gives an explicit triggering condition, and the follow-up "then call boxer or next_fight with the id" defines the downstream workflow. It does not explicitly state the negative case (e.g., if you already know the slug, skip search and call boxer directly), so it stops short of full when/when-not coverage.

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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the empty-list-means-not-on-record-yet case, the UTC start time, and the instruction to cite the url. It just doesn't cover pagination or the shape of the record.

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 what is returned, then the selector, then the empty-result and citation rules. No filler and nothing buried.

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?

An output schema exists and the description still sketches the returned fields and the empty case, so return semantics are well covered for a two-parameter lookup. The only gap is the unaddressed case of supplying both ids or neither, relevant given zero required parameters.

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 meaning the schema does not: the two ids are alternative selectors (give one or the other, trading bout-level for card-level scope), which is not expressed in the schema since both are optional.

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 the verb and the exact resource returned (broadcasters: platform, region, link) and scopes it to a bout or a whole card plus the card's UTC start time. That is enough to separate it from `bout` and `boxing_schedule`, though it doesn't name those siblings 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?

"Give bout_id or event_id" tells the agent how to select the scope (single bout vs. whole card), which implicitly signals when to use it. There is no explicit statement of when to prefer a sibling tool, nor what happens if both ids or neither are supplied.

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