UFCalendar Fight API

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

The description adds critical behavioral context beyond the annotations: the signing secret is returned only once and must be stored before the reply is discarded, and there is a hard limit of 3 active endpoints per account. These are non-obvious side effects and constraints that the agent needs to know. No contradiction with the annotations was found.

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 three concise sentences with no filler. The core purpose is front-loaded, followed by the one-time-secret warning and the account limit. Every sentence 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?

For a two-parameter tool with a fully documented schema and no output schema, the description covers the essential invocation requirements: what the endpoint is for, the event types, the one-time secret response, and the account limit. This is sufficient for an agent to call the tool correctly and understand its key consequences.

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?

The input schema already documents both parameters with 100% coverage. The description restates the https requirement and lists event types, but it does not substantially extend the meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation 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: 'Register an https endpoint to receive signed webhooks', and enumerates the event types. This makes the tool's purpose concrete and clearly distinguishes it from sibling tools like delete_webhook_endpoint, list_webhook_endpoints, and rotate_webhook_secret.

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 description clearly implies when to use this tool: when the agent needs to receive webhooks for a set of events. It also provides useful context via the account-level limit of 3 active endpoints. It does not explicitly name alternatives or exclusion conditions, but the purpose and constraints are clear enough.

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 mark destructiveHint true. The description adds valuable behavioral detail: deliveries stop and delivery history is dropped, making the full destructive impact explicit. No contradiction with 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 sentences with no redundant wording. The key facts—permanence, scope, and consequences—are front-loaded and every sentence 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?

For a single-parameter, no-output-schema tool with destructive annotation, the description is complete: it states what is removed, what stops, and what is dropped. No critical gaps remain.

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 endpoint_id parameter already has a clear description referencing list_webhook_endpoints. The tool description does not add additional parameter-level meaning, 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 verb ('permanently remove') and resource ('webhook endpoint') with clear scope ('from the calling account'). It clearly distinguishes from siblings like create_webhook_endpoint, list_webhook_endpoints, and rotate_webhook_secret.

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 description provides clear context: use this when you need to permanently remove a webhook endpoint, and the endpoint_id comes from list_webhook_endpoints. It does not explicitly name alternative tools or exclusions, but the intent is unambiguous given the sibling tool 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds meaningful behavior beyond that: it specifies the returned fields and the noteworthy behavior that including a country code still returns the worldwide row.

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 short sentences deliver the core purpose and the parameter behavior with no filler. The most important information, what the tool returns, is front-loaded.

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 low parameter count, simple schema, and annotations covering safety/idempotency, the description is complete for a read-only lookup. With no output schema, it appropriately states what the caller will receive and how filtering behaves.

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 augments the country parameter by explaining that it narrows results while retaining the worldwide row, which is not evident from the schema alone. The org parameter is already well described by its enum and label.

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: it retrieves broadcast rights for a promotion, and names exactly what is returned (provider, kind, link). It clearly differentiates itself from the unrelated sibling tools and the title matches the description.

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 description explains the primary use case and gives concrete guidance on how to narrow results via the country parameter. It doesn't explicitly mention alternatives or when not to use it, but no sibling tool overlaps with broadcast rights, so this is sufficient.

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 destructiveHint=false, so the description does not need to restate safety. It adds valuable behavioral context: the result is a complete cross-promotion snapshot and includes the date the board was published.

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, well-structured sentence delivers the resource, scope, and returned attributes without waste. The key fact ('current champions') is front-loaded.

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 zero-parameter read-only tool with no output schema, the description explains what is returned (champions), the coverage (all promotions), and key fields (division, snapshot date). Nothing essential is missing for correct invocation and interpretation.

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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific meaning, but none is needed; it correctly implies a parameterless call that returns the full champion list.

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?

Names a specific verb ('get'), a clear resource ('current champions'), and the scope: every champion across all promotions covered by the API. It also mentions the included attributes (division, snapshot date), making the tool's purpose unambiguous and distinct from siblings like get_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?

The description makes it clear this tool is for retrieving current champions across all covered promotions. It does not explicitly list when-not-to-use or name alternative tools, but the scope is specific enough that an agent can decide when this tool is appropriate.

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 the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond annotations: results are only included 'when the card has been fought', and it specifies what the response contains. This is important because no output schema exists.

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 that names the operation, identification method, and complete returned content without any fluff. Every clause contributes meaning.

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, read-only fetch with no output schema, this description is sufficient: it tells the agent how to identify the event and what to expect in the response, including the conditional results. The annotations cover safety, and no critical invocation detail 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?

The schema has 100% description coverage for the sole parameter 'event', explaining it as 'Event slug (preferred) or numeric id.' The tool description repeats 'by slug or id' in prose but adds no new syntax, constraints, or examples beyond the schema. 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?

The description states a specific verb, 'Fetch', and a specific resource, 'one event', then enumerates the payload: complete bout order, both corners, venue, broadcast listings, and results. This clearly differentiates it from siblings like list_events (multiple events) and get_fight (individual fight) by emphasizing the full-card scope.

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 description clearly implies this tool is for retrieving a single event's full card by slug or id. However, it does not explicitly name alternatives or state when not to use it, such as preferring list_events for browsing or get_fight for a single bout. The context is clear, but exclusion conditions are absent.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral context: results are newest-first and the log covers changes like bouts added, opponents swapped, and fighter profiles merged.

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 a single, well-structured sentence with no filler. The core concept is front-loaded ('audit trail'), and the em-dash list efficiently communicates scope without over-specifying.

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 tool is simple: one required parameter, read-only behavior, and rich annotations. The description provides enough context for selection and invocation, though it omits details about the response shape and any pagination or history-retention limits.

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 schema already explains that 'event' accepts an event slug or numeric id. The description adds no additional parameter-level meaning, so the baseline score of 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 verb and resource: retrieving an event's audit trail/change log. It distinguishes itself from siblings like get_event_card by focusing on historical changes rather than current state, and even enumerates example change types.

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 'audit trail' implies when to use the tool, but there is no explicit statement of when to prefer it over alternatives such as get_event_card. The usage context is clear but left 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 readOnly, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds limited behavioral context by explaining what each include block returns, but it does not mention auth requirements, rate limits, or default response shape. No contradiction with 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?

A single front-loaded sentence states the core operation first and then lists the optional include blocks without repetition or fluff. 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?

For a low-complexity read tool with rich annotations, the description covers the main decision an agent must make: whether to request extra blocks. It does not describe the default response structure or error behavior, but those are not critical for a get-by-id call with no output schema.

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 meaning beyond the enum names by defining stats as per-fight totals, rounds as round-by-round statistics, and scorecards as official judges' cards. The fight_id is also contextualized as a numeric id from an event card in 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 opens with 'Fetch one bout by id', a specific verb+resource that distinguishes this from sibling tools like get_fighter, get_event_card, and list_events. It also clarifies that the optional include parameter controls data blocks rather than changing the resource being fetched.

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 implies the tool is for retrieving a single bout when an id is known, and it explains when to use each include value (stats for totals, rounds for round-by-round, scorecards for judges' cards). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select 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 readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds that history includes a multi-promotion career timeline, but it does not disclose other behaviors like pagination or rate limits. Since annotations cover the primary traits, a 3 is appropriate.

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 a single sentence that efficiently packages purpose and parameter guidance. It is slightly dense but every clause adds value; no fluff or redundancy.

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 specifies what is returned (bio, record, statistics, portraits) and how to extend the response with includes. It doesn't mention error handling or pagination limits beyond the history_limit parameter, but for a simple read-only tool it is reasonably 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?

The schema fully documents all three parameters, but the description adds meaningful context by explaining what each include option returns (e.g., history gives a full multi-promotion timeline). This goes beyond the schema's generic 'Extra blocks' description.

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 ('Fetch') and resource ('one fighter'), and lists the data returned (bio, record, career statistics, portraits). It clearly distinguishes from sibling tools like get_fight and search_fighters by implying direct access via slug or id.

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 description implies usage when you have a known fighter slug or id, which separates it from search tools. It also provides guidance on the include parameter to tailor the response, but it does not explicitly exclude alternatives like search_fighters or mention 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 cover readOnly, idempotent, and non-destructive behavior, so the description's additional behavioral details—'newest first' ordering and the restriction to commission records—add useful context beyond the schema. It does not discuss pagination behavior or auth, but given the annotations carry the safety profile, this is adequate.

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 a single well-ordered sentence that front-loads the core purpose and then lists the output fields. Every clause earns its place and there is no redundant restating of the 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?

For a tool with no output schema and only partial parameter descriptions, the description covers the return content and ordering reasonably well. However, it omits how cursor-based pagination works and does not clarify the relationship between limit and cursor, leaving an agent to infer pagination from the schema alone.

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 only 33%, with only judge_id documented. The description adds little to parameter meaning: it confirms the tool is for one judge but provides no explanation of limit or cursor semantics, which are the pagination controls an agent would need to invoke correctly.

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 clearly identifies a specific resource—official scorecards turned in by one judge—and specifies the contained fields (per-round points, card totals, decision type, point deductions). It also adds a scoping qualifier ('Commission records only') that helps distinguish it from other listing tools among the 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?

The description gives no explicit guidance about when to use this tool versus alternatives like get_event_card or list_judges. It implies the usage through the resource description but does not state when to prefer it or what conditions make it the right choice.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating no credential is required and enumerating the specific content (quotas, limits, trial terms), but it does not go further into response format or data source details.

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 concise sentences with no filler. The main action and content list are front-loaded, and the practical use-case statement ('answers what does this cost without a credential') adds value without redundancy.

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 parameterless, read-only, idempotent tool, the description fully covers what the agent needs to know: what the tool lists, the quota-related content, and that no credential is required. No output schema exists, but the described return content is simple enough 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?

The tool has zero parameters, so the schema is already complete and there is no parameter ambiguity. The description further clarifies that no credential is needed, which effectively communicates the absence of auth-related inputs.

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 ('List') and a specific resource (UFCalendar Fight API plans), and details exactly what is returned: monthly request quotas, per-minute limits, and no-card trial terms. It also distinguishes this from costing/credential-related use cases, making it clear among siblings like get_usage.

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 description gives a clear use case: answer 'what does this cost' without a credential. It implies this tool is appropriate when no authentication is available and the agent needs plan/quotas information, though it does not explicitly name alternative 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: 'refreshed hourly' indicates data freshness, and 'peak rating and fights rated' suggests content composition. This goes beyond annotations without contradicting them, earning a strong score.

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 a single, efficient sentence. It front-loads the core purpose, then adds relevant details via an em-dash. There is no fluff or redundancy. Every word contributes to understanding the tool's function.

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 tool with two parameters, the description provides sufficient context to call it correctly: it names the board, the single-promotion scope, and hints at content. It does not describe the return format, but with no output schema, some ambiguity remains. However, the combination of schema (enums, constraints) and description is adequate for most agent scenarios.

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 50% (only org has a minimal description). The tool description adds context for the org parameter by saying 'for one promotion', but it does not explain the limit parameter at all. Given the low-to-moderate coverage, the description should compensate, but it does not address the optional limit or its purpose. The description adds marginal value over the schema for org but leaves limit undocumented.

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 clearly states the resource (Power Index board), the scope (for one promotion), and gives specifics (our own rating engine, refreshed hourly, peak rating, fights rated). It is a specific verb+resource, but it does not explicitly differentiate from sibling tools like get_rankings or get_event_card. The purpose is clear but not contrasted.

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 is given on when to use this tool versus alternatives. The description does not mention sibling tools or conditions for selection. The only contextual hint is 'for one promotion', which implies the org parameter is required, but no exclusion criteria or alternatives are noted. This leaves the agent to infer usage.

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 destructiveHint, covering safety. The description adds valuable behavioral context: the corner-stamping mechanism ensures probabilities are never matched to the wrong fight, and the explicit note that output is informational, not betting advice, sets expectations. This goes beyond the annotations without contradicting them.

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 with no filler. The first sentence front-loads the core purpose and a key behavioral guarantee; the second adds a necessary disclaimer. Every word earns its place, and the structure is immediately scannable.

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 parameterless tool with no output schema, the description covers purpose, a behavioral nuance, and a usage caveat. The only minor omission is a description of the output format (e.g., list of fights with probabilities), but the name and title strongly imply the return content. Given the simplicity, this is adequate.

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?

The tool has zero parameters, and schema description coverage is 100% (vacuously). The baseline for no parameters is 4, and the description adds no parameter-specific information because none is needed. No gaps exist here.

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 clearly states the tool provides 'UFCalendar model win probabilities for upcoming UFC bouts,' with a specific verb and resource. The corner-stamped detail further clarifies the output's association with the correct fight pair. It is distinct from all siblings, as no other tool mentions predictions or win probabilities.

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 is given on when to use this tool versus alternatives. The disclaimer 'Informational model output, not betting advice' is a caution, not a usage rule. There is no mention of prerequisites, exclusions, or comparison with similar tools like get_power_index or get_rankings.

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 destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral context: point-in-time reading, rank 0 champion semantics, and division narrowing. No contradiction with 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 tightly written sentences with no filler. The most important scoping information — official board, one promotion, point-in-time — is front-loaded, and the champion/division details earn their 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?

The description covers the main semantic nuances: date is point-in-time, rank 0 is champion, division narrows the board. With no output schema, a bit more detail on the response shape or board default would improve completeness, but the tool is simple enough that the current description is largely sufficient.

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 baseline is 3. The description adds meaning beyond the schema by explaining date as point-in-time state and division as a narrowing filter. This goes beyond the schema's field-level descriptions.

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: the official rankings board for one promotion, point-in-time, and defines rank 0 as champion. This clearly distinguishes the tool from get_champions and other list-style tools, though it does not explicitly name the sibling alternative.

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 practical guidance on how to use the date ('read the board as it stood that day') and division ('pass a division to narrow it'), but it does not state when to prefer this tool over get_champions or other ranking-adjacent tools. Usage context is implied rather than explicit.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context about the specific data returned (monthly usage, limits, reset), which goes beyond the annotations but does not disclose additional behavioral traits such as authentication or rate limiting. It is adequate but not extensive.

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 a single, well-structured sentence that immediately states what the tool returns. It is concise, front-loaded, and contains no filler or redundancy.

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 tool with no parameters and no output schema, the description is sufficient. It clearly enumerates the key data points (requests used, plan limit, per-minute limit, reset time). The absence of details on response format is acceptable given the simplicity and the lack of an output schema. It is complete enough for an agent to understand the tool's purpose and call it 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?

The tool has zero parameters, so the description does not need to elaborate on parameter semantics. With no parameters, the baseline is 4, and the description is consistent with that. It doesn't add extra parameter info because none exists.

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 clearly states the tool's function: it returns usage metrics for the calling account (requests used, plan limit, per-minute limit, and reset time). This is specific and distinguishes it from the many other get_* tools, none of which cover usage.

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 description implies this is for checking API usage, but it does not explicitly state when to use it or mention any alternatives. Since there are no sibling tools with similar functionality, the lack of exclusion is not a major issue, but there is no direct guidance on the intended context.

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 destructiveHint, so the tool's safety profile is clear. The description adds no further behavioral context such as response envelope, error behavior, or authentication requirements. It is consistent with annotations but doesn't go beyond them.

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 a single, purpose-dense sentence with the core verb and resource front-loaded, followed by a compact list of returned fields. No filler or redundancy.

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 single-parameter getter, the description provides the returned fields and identifies the lookup key. It lacks information about error responses or not-found behavior, but given the absence of an output schema, the field list gives a reasonable picture; annotations cover the read-only nature. This is adequate for a straightforward fetch.

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 describes venue_id as a numeric id. The description restates the id-based lookup but adds no format, range, or example beyond the schema, so it adds no extra meaning.

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 ('Fetch'), resource ('one venue'), and key selector ('by id'), and enumerates the returned fields. This clearly distinguishes it from sibling tools like list_events or get_fight; an agent can infer its purpose without opening the 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?

The description implies usage when a specific venue id is known and full venue details are needed, but it does not explicitly mention when not to use it or alternatives. There is no exclusion or comparison with sibling list tools, though the id-based lookup is fairly self-explanatory.

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 this as a read-only, idempotent, non-destructive operation. The description adds useful behavioral detail beyond the annotations by stating that it returns the URLs for authentication and which methods it explains.

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 well-structured sentence that front-loads the tool's purpose, details the two covered authentication methods, and states the expected return value. No wasted words.

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 zero-parameter, informational tool, the description is complete: it tells the agent what will be explained, which authentication methods are covered, and what the tool returns. No output schema exists, but the simple return content is sufficiently described.

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?

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to clarify. The 0-parameter baseline of 4 applies because no parameter semantics are needed.

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 ('Explain how to authenticate') and clearly identifies the target resource ('UFCalendar Fight API from this MCP server'). It also distinguishes itself from all sibling data- and webhook-related tools by being the authentication-help tool.

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 description makes the context clear: use this when you need to know how to authenticate, and it even enumerates the two supported methods. There are no sibling tools offering a similar alternative, so explicit when-not-to-use guidance is not necessary.

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 flag this as a read-only, idempotent, non-destructive call, so the description doesn't need to restate that. It adds real behavioral detail: default date scope (upcoming), default ordering (soonest first), archive mode via order=desc, and cursor pagination. This goes well beyond the annotation hints without contradicting them.

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 sentences, each carrying distinct information: purpose, default behavior/order toggle, and pagination. No filler or repetition of the 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 seven optional parameters and no output schema, the description covers the main operational decisions an agent needs: defaults, filtering dimensions, ordering, and pagination. It doesn't describe the response object shape, but the schema's cursor description already points to meta.pagination.next_cursor, and the readOnly/idempotent annotations handle the safety profile.

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 86% and the baseline for that is 3. The description adds operational meaning by grouping parameters (promotion, status, date range), explaining that order=desc flips from upcoming to archive, and confirming cursor as the pagination mechanism – value not explicit in each parameter's description.

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 precise operation: listing fight cards, and specifies the key filter dimensions (promotion, status, date range). It clearly reads as a collection/list operation, distinguishing it from single-card tools like get_event_card 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?

It gives concrete how-to context: a bare call for upcoming schedule, order=desc for archive, and cursor pagination. However, it never says when to choose this tool over alternatives such as get_event_card, and provides no explicit exclusions or conditional 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns career aggregates, which is useful behavioral context beyond the annotations. However, it does not mention pagination, ordering, or response shape, though the schema covers cursor/limit parameters.

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 two concise sentences. The first sentence front-loads the core purpose and output aggregates, and the second covers filtering. There is no filler or redundant detail, and every clause adds 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?

For a simple read-only listing tool, the description covers the main return content (career aggregates) and filtering. However, it omits mention of pagination through limit/cursor, and without an output schema, an agent might not know the exact response structure (whether it's a flat list or wrapped). The description is adequate but not fully 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 description coverage is only 20%, so the description must compensate. It does so by mapping three key filters to parameters: name (q), promotion (org), and minimum fights (min_fights). It uses the domain term 'promotion' to clarify the org enum. However, the pagination parameters limit and cursor are not mentioned in the description, leaving them 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?

The description clearly states this is 'The judge directory' with specific career aggregates (cards turned in, rounds scored, 10-8s, split cards, lone dissents). This distinguishes it from the sibling get_judge_scorecards, which focuses on individual scorecards, and from general search tools. The resource and scope are specific enough for an agent to select it correctly.

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 description implies usage by describing the directory and filters ('Filter by name, promotion or a minimum number of fights'), but it does not explicitly state when to use this tool versus alternatives like get_judge_scorecards or search. There are no when-not-to-use instructions or named alternatives, so the guidance is only 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 establish that this is read-only, idempotent, and non-destructive. The description adds useful context beyond that by specifying the scope ('the promotions the UFCalendar Fight API covers') and the exact capability flags returned (stats, rounds, rankings, broadcasts, predictions, scorecards), which helps agents understand the response without an output 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 description is a single front-loaded sentence that names the action, the resource scope, and the key output detail. Every part earns its place, and there is no redundancy or unnecessary elaboration.

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 zero-parameter, read-only listing tool with rich annotations and no output schema, the description is complete: it states what is listed, the scope, and the fields an agent should expect. Nothing critical is missing for correct invocation or result interpretation.

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?

The input schema has zero parameters and schema description coverage is 100%, so there are no parameter semantics the description needs to document. The per-org capability flags mentioned are output content, not input parameters, so the description appropriately avoids parameter-related filler.

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: it 'List[s] the promotions' the API covers, and further specifies the per-org capability flags included. This clearly distinguishes it from sibling list tools such as list_events and list_judges, as well as from get_* tools.

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 description makes the usage context clear: use it to see which promotions/orgs the API covers and their capabilities. It does not explicitly name alternatives or exclusion conditions, but with zero parameters and a distinct resource type, the intended use is apparent and no conflicting alternative is suggested.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations: the endpoints are 'signed', scoped to the 'calling account', and the response includes subscribed event kinds. Pagination and rate limits are not mentioned, but those are minor for this simple list operation.

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 a single focused sentence that front-loads the action and resource, then adds the two most useful qualifiers: account scope and returned event kinds. No filler or redundant phrasing.

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 zero-parameter, annotated as read-only list tool with no output schema, the description is complete enough: it states what the list contains, who it belongs to, and a key output attribute. Nothing an agent needs to call it 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?

The input schema has zero parameters, so the baseline is 4 and there is nothing for the description to explain. No parameter-level detail is needed.

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 ('List'), a specific resource ('webhook endpoints'), and a clear scope ('registered on the calling account'). It also adds the result content ('event kinds each one subscribes to'), which distinguishes it from the sibling create/delete/rotate webhook tools.

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 description implies the correct use case: retrieving the account's webhook endpoint registry rather than creating, deleting, or rotating secrets. It doesn't explicitly name alternatives or exclusions, but the context is clear and no prerequisites are needed for a zero-parameter read-only list.

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?

The description reveals critical behavioral details beyond the destructiveHint annotation: the old secret stops working immediately, the receiver must be updated first, and the new secret is returned only once. These are essential for the agent to understand the consequences of the action and are not present in the 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 three short sentences, each earning its place: purpose, immediate-effect warning, and return behavior. It is front-loaded with the core action and contains no fluff.

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, no-output-schema tool, the description covers the action, the critical ordering requirement, and the return value ('new secret is returned once'). The destructive annotation is supplemented with concrete impact, making the description complete 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?

The input schema already provides 100% coverage for the single parameter endpoint_id, including its source ('Endpoint id from list_webhook_endpoints'). The description does not add additional parameter-level detail, 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 ('Replace') and a specific resource ('the signing secret of one webhook endpoint'), clearly distinguishing it from siblings like create_webhook_endpoint and delete_webhook_endpoint. This leaves no ambiguity about what the tool does.

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 description provides clear operational context: 'old secret stops verifying immediately, so update the receiver first' implies when and how to use it safely. It does not explicitly name alternatives or state when not to use it, but the tool's unique purpose among siblings makes the usage context clear.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those flags: it characterizes the search as 'typeahead' and clarifies that the output is a slug suitable for other tools. It does not disclose result limits or response format, but with annotations present, this is acceptable.

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 compact sentences: the first defines scope and behavior, the second states the intended use. No filler, and the action is front-loaded, making it easy for an agent to parse quickly.

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 one-parameter read-only search tool, the description covers the essential invocation context: what is searched, typeahead behavior, and the purpose of the output. It omits response structure details, but that is a minor gap given the simple input and strong annotations.

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?

The schema only describes q as a string with minLength 2. The description enriches this by explaining that q is the name a user typed and that the tool converts it to a slug, adding meaning that the schema alone does not convey.

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 (search) across two resources (fighters and events) and emphasizes 'in one call', which distinguishes it from narrower sibling tools like search_fighters. The scope and action are immediately 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?

The second sentence gives explicit usage context: use it when a user has typed a name and you need a slug for other tools. However, it does not name alternatives or state when not to use it, so it lacks the explicit exclusion/alternative guidance needed for 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds useful behavioral context by noting cursor-based pagination and that only identity fields are returned, which is not inferable 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?

Two sentences, front-loaded with the core purpose and filters, followed by pagination and a pointer to get_fighter. No filler or redundant restatement of the 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?

Given the read-only annotations and the simple optional-parameter search surface, the description covers what the tool does, how results are paginated, what fields are returned, and where to go for more detail. The identity-fields statement is especially valuable since there is no output schema.

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 descriptions already cover q, org, and country, and the description's 'name, nationality or promotion' largely restates them. The only added parameter insight is 'cursor paginated', which lightly explains limit/cursor but does not fully compensate for the undocumented limit and cursor parameters at 60% schema coverage.

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 action ('Search the fighter roster') and explicit filters (name, nationality, promotion), distinguishing it from siblings like get_fighter for full records and the generic search tool. The scope is immediately 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?

Description gives a clear routing rule: use this for identity-level roster searches and get_fighter for the full record. Cursor pagination also signals this is intended for list-style queries rather than single-record lookups.

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