FighterAPI

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 behavioral information in 'Costs 2 credits,' which is not expressed anywhere in the structured fields; it does not, however, say whether credits are charged on an invalid event_id or an empty card.

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: usage cue first, then the return inventory, then the cost. Every clause carries information an agent would otherwise have to guess.

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?

Only two parameters and an output schema exists, so return shape needn't be described, yet the description still summarizes the payload and adds the credit cost. Nothing material for correctly invoking this read-only fetch 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%: event_id is documented as coming 'from list_events or get_schedule' and league carries its enum plus the mma default. The description adds nothing about either parameter, so the baseline 3 applies – the schema does all the work.

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 concrete verb+resource ('Use for one card') and enumerates exactly what comes back: every fight in order with result, method, round, time, judges' scores and referee. This implicitly separates it from get_fight (single bout), but it never names a sibling, so differentiation is left to inference.

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 for one card' is a usage directive that hints at the whole-card vs single-fight split with get_fight, but no alternative tool is named and no when-not condition or prerequisite is stated. An agent must infer the routing from the sibling names.

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?

Beyond the readOnly/idempotent annotations, the description discloses cost (5 credits), data-availability caveats (UFC-only fields and null elsewhere), a temporal limit on moneylines (2024 onward), and explicit prohibitions on computing stakes or recommending bets. Those are exactly the operational and policy facts an agent cannot infer from the schema.

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 and the cost and policy constraints are short, standalone sentences. The middle enumeration is dense but each item conveys a distinct returned field or caveat, so almost 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?

An output schema exists, so return values need no explanation, yet the description still adds availability caveats, cost, and usage policy. For a paid, policy-sensitive read tool, an agent has everything needed to call it correctly and within bounds.

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 description coverage is 100%, and the descriptions already explain bout_id's origin and league's default and enum. The tool description adds no further parameter-level meaning, which is acceptable at full coverage but not value-adding.

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 opens with a specific verb-and-resource statement ('everything about one fight') and then enumerates the exact contents: result, stat sheets, round lines, ratings, and moneylines. That detail makes it unmistakably the single-fight tool, distinct from get_event or get_fighter_fights.

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 says explicitly to use this for 'everything about one fight' and points the agent to get_event and get_fighter_fights as sources for the required bout_id. It does not name a situation where another tool should be preferred instead, so it stops short of full routing 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 declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: a 5-credit cost, that career rate stats are UFC-only, and that ufc_record mirrors record for the UFC and is null elsewhere. Missing only pagination/response-shape notes, which the output schema covers.

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 use case, then a single dense enumeration in which each clause conveys distinct content (fields, scope caveats, cost). It is long but nearly every clause carries information; the parenthetical about ufc_record is the only mildly awkward insertion.

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 2-parameter read tool with a full output schema, this covers the important gaps: cost, promotion-specific nullability, and UFC-only stat coverage. Only the relationship to sibling tools for id lookup and extended fight history is left unstated.

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 are documented in-schema, including the league enum values and default. The description adds no parameter-level guidance beyond what the schema says (the ufc_record note concerns output, not inputs), so the 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 states a specific resource ('one fighter's profile') and enumerates exactly what the payload contains: biographical fields, record by method, per-15-minute career rates, ratings, and last five fights. That level of detail makes it distinguishable from get_fighter_fights (full fight list) in practice, but it never names a sibling tool, so it stops short of a 5.

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 for one fighter's profile' gives an implied usage context but no when-not guidance, no prerequisites, and no pointer to alternatives such as search_fighters for resolving an id or get_fighter_fights for full history. The reader must infer selection from the enumerated payload.

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 behavior, and the description adds important context: a 5-credit cost, UFC-only takedown data, and compliance constraints around betting and market information. These are meaningful behavioral details beyond the structured 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?

The description is front-loaded with the primary use case, followed by return-field detail, cost, and compliance constraints. Every sentence carries useful information and there is no redundant 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?

Given the presence of an output schema, full annotation coverage, and a fully documented input schema, the description provides enough additional context about scope, cost, and usage restrictions for an agent to call the tool correctly.

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 description coverage is 100%, so the schema already documents fighter_id, limit, offset, and league. The description does not add parameter-specific guidance beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource: retrieving a fighter's full fight history in the promotion. It also enumerates the returned fields, which clearly distinguishes it from sibling tools like get_fighter or get_fight.

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 phrase 'Use for a fighter's full history' gives clear usage context, and the schema points to search_fighters for obtaining fighter_id. However, it does not explicitly name alternatives such as get_fighter or get_fight or state 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful context the annotations do not: the data source ('computed from every fight's stat sheet'), the cost ('Costs 5 credits'), and the qualification default ('default 5' fights). It doesn't state sort direction or tie-breaking, which would be nice for a leaderboard, but the added context is solid.

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?

Purpose is front-loaded ('Use for career leaderboards...') and the long parenthetical list earns its space because the enum identifiers are abbreviations that would otherwise be hard to interpret. It is dense and somewhat run-on, but every clause carries information; trimming the glosses would hurt comprehension.

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, return-value explanation is unnecessary, and annotations cover safety. The description covers the metric set, the filter dimensions, defaults, and credit cost. Remaining gaps are minor — sort order/ranking direction and how ties or small-sample fighters are handled.

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 goes further by decoding each opaque enum token (e.g., 'sig_absorbed_per_15 (significant strikes absorbed per 15 min)', 'finish_rate (wins by KO/TKO or submission, as a share of wins)') — context the schema enum does not provide. It also reinforces the min_fights default. It adds little about limit/since/weight_class beyond what the schema states.

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 opens with a specific verb + resource combination ('career leaderboards computed from every fight's stat sheet') and immediately enumerates the eleven leaderboard metrics. This is clearly distinguishable from siblings like get_ratings, get_fighter, or get_fighter_fights, which return entities or per-fight data rather than aggregated career rankings.

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 for career leaderboards...' gives clear usage context, and the stat enumeration makes the intended scenarios obvious. It does not explicitly exclude alternatives (e.g., 'for a single fighter's stats use get_fighter'), so the when-not guidance is absent, but the use case is unambiguous.

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?

Beyond annotations (readOnly/idempotent), it discloses credit cost (10), snapshot cadence (daily from October 2026, hourly in the four days before), and deduplication behavior that keeps every move and its time. It also states the compliance boundary on what may be done with prices, which annotations cannot convey.

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, purpose and sampling cadence first, cost and compliance second. Every clause carries information an agent would otherwise have to guess.

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?

Output schema exists, so return shape need not be described; annotations cover safety; all four params are schema-documented. The description adds the cost, sampling policy and compliance limits that structured fields do not carry.

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 league, bout_id, provider and all_snapshots. The description only indirectly touches all_snapshots by explaining snapshot density and default deduplication; it adds no semantics for provider or league 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?

States a specific verb and resource ('see how a fight's line moved') plus the exact data granularity (snapshots of each posted moneyline from first capture to fight day). This clearly separates it from get_odds, which by name covers current pricing rather than historical movement.

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 clear context for use ('before the bell', historical movement) and hard exclusions drawn as compliance guardrails: never compute stake/payout/profit, recommend a bet, or send the user to a sportsbook. It does not explicitly name get_odds as the alternative for current lines, leaving that inference to the agent.

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, and the description goes well beyond them: data coverage boundaries (opening/closing only from June 2020), expected book depth (median 5-7, sometimes one since mid-2024), per-call credit costs, and an explicit policy prohibition on staking, payout math, bet recommendations or sportsbook referrals.

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 dense sentences, front-loaded with what the tool returns before coverage caveats, cost, and the safety constraint. No sentence is filler; the credit costs and data-limits sentence both carry decision-relevant 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 shape needn't be spelled out, yet the description still names the key fields. Coverage windows, book depth, cost, and the no-betting-advice guardrail leave nothing an agent needs in order to call this correctly.

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 adds real meaning: it frames bout_id and event_id as mutually exclusive access scopes and attaches distinct credit costs to each. League's enum behavior is 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 verb and resource: betting lines with opening, closing and current moneyline for both fighters, plus implied probabilities and the total-rounds line. The scope ('each posted sportsbook's') cleanly separates it from get_line_movement and get_fight, which an agent can distinguish 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?

Explicitly routes between the two access modes: bout_id for one fight (5 credits) or event_id for a whole card (10 credits), and states when data is unavailable (pre-June 2020). It does not name get_line_movement as the alternative for movement-over-time questions, which is the one routing gap.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds meaningful context beyond them: the credit cost ('Costs 2 credits'), the ranking method, sort order, and the default active window.

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 with the purpose front-loaded ('Use for our fighter ratings'), followed by method, scope, ordering, filter, and cost. No 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?

An output schema exists, so return values need not be described. The description covers method, defaults, filtering, ordering, and cost — enough to call correctly. The only gap is the league parameter, which is documented only in the schema and unmentioned here.

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 baseline is 3, but the description adds value the schema lacks: the default for active_since ('default last year') is stated as behavior, and the weight-class filter and highest-first ordering are clarified. The league enum (mma/pfl/bellator) is not addressed in the description, keeping it from a 5.

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 (fighter ratings / Elo) with the exact methodology and scope ('built from the promotion's own results, the UFC since 2000, highest first'). This clearly distinguishes it from siblings like get_fighter, get_leaders, and search_fighters.

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?

Opens with 'Use for our fighter ratings' and gives the default window ('active since a given year, default last year'), which orients usage well. It does not name alternatives or say when NOT to use it (e.g., versus get_leaders), leaving that to inference.

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 read-only, idempotent, closed-world safety profile, so the description's added value is the cost disclosure (2 credits) and the compliance guardrails, both of which the agent cannot infer from structured fields. It does not say what the response looks like when no book has posted a line, which is the main remaining behavioral gap.

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, front-loaded with the use case, then the cost, then the guardrail. Every clause carries information the agent needs; 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?

An output schema exists so return values need no explanation, and the description covers the cost, defaults and compliance constraints. Completeness is slightly undercut by not specifying behavior when no moneyline is available for a bout or the N-days window crosses a league boundary.

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 description coverage is 100% – both parameters, including the 1-180 bounds and the mma/pfl/bellator enum, are fully documented in the schema. The description's restatement of the 'default 30' for days adds no syntax or constraint beyond what the schema already states, so 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?

A specific verb-and-resource statement: every scheduled bout in the next N days with the current moneyline from any book. It reads clearly as a forward-looking schedule+price read, distinct from siblings like get_event (single event), get_odds (pricing focus) and get_fighter_fights (historical).

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?

Explicitly scopes usage to 'upcoming fights' and sets a hard behavioral boundary on what must not be done with the prices (no stake/payout math, no bet recommendations, no sportsbook referrals). It stops short of naming a sibling alternative for looking up a single event or historical odds, so routing to alternatives is left implicit.

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 genuinely non-obvious behavior: results are ordered newest first, and each call "costs 1 credit" — a billing constraint the agent cannot learn from any structured field.

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 short sentences, front-loaded with the primary use case, then return shape, then filters, then cost. No filler and nothing buried — the credit cost is placed last where it reads as a caveat rather than a headline.

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 prose beyond the brief field summary given. All five parameters are documented in the schema, the safety profile is in annotations, and cost plus sort order are stated — nothing an agent needs to call this correctly 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 description coverage is 100%, so limit, league, offset, season and status are all documented in the schema itself. The description only echoes season and status and adds no syntax or interaction detail beyond what the schema states ("Year, e.g. 2025"), so the 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 gives a specific verb and resource ("lists events") and enumerates what comes back (venue, status, number of fights, main event), which is concrete enough to picture the response. "Use to find cards" plus the sibling set (get_event, get_schedule) leaves a small ambiguity about discovery vs. single-record retrieval, but the plural list framing disambiguates well enough.

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 find cards" implies the browse/discovery use case and the filter note tells the agent it can narrow by year and completion status. However, no alternative is named — nothing says when to prefer get_event or get_schedule over this tool — so the agent must infer routing from the sibling names.

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 non-open-world behavior. The description adds useful context beyond annotations: accent-insensitive matching, the result fields returned, and a credit cost of 1. It does not discuss pagination or limit behavior, but the schema covers that.

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 compact sentences, front-loaded with the primary use case and followed by return details and cost. Every sentence adds practical information with no repetition or 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?

For a simple read-only search tool with a full output schema and annotations, the description supplies the remaining practical context: lookup purpose, accent tolerance, returned fields, and credit cost. No critical agent-facing information 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 description coverage is 100%, so the schema already documents all four parameters. The description adds only marginal meaning, such as noting that accents are optional, but does not elaborate on query format, league filtering, or weight-class behavior 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 verb and resource ('find a fighter's id by name or nickname') and clarifies the tool's role relative to siblings like get_fighter by focusing on lookup rather than full profile retrieval. The result fields are also named, making the tool's output purpose clear.

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?

Explicitly says to use it to find a fighter's id by name or nickname, which gives clear context for when to call it. It does not explicitly name alternatives or exclusions (e.g., 'use get_fighter once you have the id'), so it stops 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.