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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real context beyond them: only PDF files are read, the text stays local and is never transmitted, and it returns a local: ID whose downstream tools only expose an outline and short passages. This is meaningful behavioral disclosure not present in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action, then the privacy constraint, then the return/downstream contract. No filler, though the downstream-tool sentence front-loads the return value slightly before it is needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by describing the return value (a local: ID) and how it feeds read_paper/match_quote. Privacy, file-type limits, and downstream behavior are covered; only edge cases such as duplicate additions or metadata-failure handling are left unaddressed.

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 both 'path' and the optional 'id' (DOI/arXiv ID with auto-fill behavior). The description adds a constraint (only PDF files are accepted) that bears on the path parameter, but no format or syntax detail beyond the schema, 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?

States a specific verb and resource: add a user's local PDF to their football-docs library, and clarifies the scope is a PDF the user already has (e.g. from a subscription). This clearly separates it from remote-fetch siblings like search_papers/get_paper, though it doesn't explicitly name a sibling to contrast against.

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 a concrete usage context ('a paper from their library's subscription') and names the downstream consumers (read_paper, match_quote), which implies when the tool is useful. However, it never states when NOT to use it or how it relates to alternative ingestion paths, leaving routing 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 (readOnlyHint=true, destructiveHint=false) indicate safe read operation. The description adds context by specifying 'compare' and 'specific data type or concept', aligning with annotations. No behavioral traits like response format or limitations are disclosed, but annotations cover safety.

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 an example, no wasted words. Efficiently communicates purpose and usage.

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 has 2 parameters and no output schema. The description is minimal and lacks any mention of return format or behavior, which is a notable gap given no output schema. It 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 coverage is 100%, with descriptions for both parameters (topic and providers) including examples. The description's example ('shot events') adds minimal extra meaning; baseline 3 is appropriate as schema does the heavy lifting.

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 compares providers for a specific data type/concept, with an example. The name 'compare_providers' aligns with this purpose, and it is distinct from sibling tools like list_providers and get_provider_docs.

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 for comparing representations across providers via an example, but lacks explicit when-to-use or when-not-to-use guidance, such as mention of alternative tools like search_docs for finding docs. It is clear but not exhaustive.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds genuinely useful bounds: only the library text copy is removed, while the user's own file and Zotero are untouched. That materially narrows the blast radius beyond what annotations convey, though it omits what happens on an unknown or already-removed ID.

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, zero filler, with the action and its scope boundary front-loaded. 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 single-parameter destructive tool with no output schema, the description covers the essential unknown — what is and isn't deleted — and annotations cover reversibility and safety. Minor gaps remain around failure behavior and whether confirmation is required.

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?

Only one parameter, and schema description coverage is 100% — the schema itself enumerates the accepted ID forms (DOI, arXiv, OpenAlex, zotero:KEY, local:…). The description adds no further semantics, 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?

States a specific verb and resource ('Remove one paper's text') plus the target collection ('football-docs library'), and immediately scopes what is *not* affected. It distinguishes itself from source-preserving siblings, though it doesn't name a counterpart tool by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: remove a paper's indexed text when you no longer want it in the library. There is no explicit when-to-use versus alternatives (e.g., re-indexing, add_local_paper, search_docs), and no stated preconditions or confirmation requirement.

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 and openWorldHint, so safety is covered. The description adds genuinely useful provenance behavior that annotations cannot convey: arXiv IDs resolve via arXiv with the paper's licence, DOIs via OpenAlex then SportRxiv or Crossref. It does not mention failure behavior (e.g. what happens if the ID is unknown) or rate limits.

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 action and identifier types before the use case. The returned-field list is dense but each item is meaningful for a lookup tool; nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so by enumerating title, authors, dates, venue, IDs, licences, open copies, abstract and citation line. Combined with the read-only annotations and full param coverage, an agent has enough to call it correctly, though error/empty-result behavior is 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 the single parameter is fully documented with examples, so the baseline is 3. The description goes beyond the schema by naming two additional accepted ID forms (zotero: ID and local: ID) that the schema does not list, adding real value.

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 ('look up one paper') and enumerates the exact identifiers accepted (DOI, arXiv ID, OpenAlex ID, zotero: ID, local: ID) plus the fields returned. The singular 'one paper' clearly separates it from the sibling search_papers.

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 an explicit use case ('check that a reference exists and says what is claimed'), which tells the agent when this tool is the right choice. It stops short of naming an alternative or stating when not to use it, so it does not reach 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 indicate readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. The description adds 'provenance-bearing docs' implying reliability, but doesn't expand on behavior like error handling or data format.

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: one for core function, one for usage context. No wasted words. Front-loaded with the action and resource.

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 purpose, usage order, and filtering. No output schema exists, but the description doesn't explain return format. However, for a straightforward retrieval tool with good annotations, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter. The description reiterates filtering options (topic, category) and emphasizes 'resolved provider,' adding context but not compensating for low coverage since coverage is already high.

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 verb 'retrieve' and resource 'provider docs', specifying filtering by topic or category. It distinguishes from siblings by mentioning 'resolved provider' and referencing resolve_provider_id as a prerequisite.

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 explicitly says 'Use after resolve_provider_id when you know which provider to inspect and want provenance-bearing docs.' This gives a clear usage context and prerequisite. It does not explicitly state when not to use, but the context 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 only cover the safety profile (readOnly, openWorld, non-destructive), while the description adds substantial behavior: returns author/date/licence/snapshots, an earliest-snapshot date fallback for undated pages, HTML+PDF support, sectioned returns for long pages, stopping at bot checks, and refusing local addresses. That is far beyond what the structured metadata conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then usage, then edge-case behaviors in short declarative sentences. Slightly dense and long, but every sentence carries distinct information about the return payload or edge cases rather than 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?

There is no output schema, so the description must carry the return burden, and it does: text plus author, date, licence, snapshots, sectioned long pages. It also documents the key failure modes (bot checks, local addresses) needed to 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'section' semantics ('Long pages come back by section'), matching the schema's note that it comes from an earlier call's outline, but adds no new syntax or constraints 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 (Read) and resource (public web page), then concretizes it with examples (blog post, newsletter, club or vendor article). An agent knows exactly what comes back: page text plus author, date, licence and Wayback snapshots. No sibling tool overlaps this scope, so differentiation is implicit.

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 a clear when-to-use rule: 'for methods first published on the web ... after finding the page with a web search,' which also sequences it after a search step. It does not state explicit exclusions or name an alternative tool, but none of the paper/provider siblings competes for this job.

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 destructiveHint=false, so the agent knows this is a safe read operation. Description adds that it lists providers and their metadata, which is consistent and sufficient. No additional behavioral traits needed beyond what's disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded with purpose and usage. Every word earns its place with no redundancy or filler. Highly efficient.

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 zero parameters, no output schema, and a simple list operation, the description fully covers what the tool does and how to use it. No 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?

No parameters defined (0 params), so baseline is 4 per scoring guidelines. Description does not need to add param info since schema coverage is 100% and there is nothing to describe.

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?

Description uses specific verb 'List' and clearly identifies resource as 'all indexed football data providers' with included attributes (document count, coverage categories). This distinguishes it from sibling tools like search_docs and get_provider_docs.

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 states when to use: 'Use to understand what documentation is available. Call this first to see what providers are indexed before searching.' This provides clear context and implies alternatives (e.g., search_docs for searching).

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, non-destructive, open-world behavior, so safety is covered. The description adds substantive return semantics the annotations cannot convey: the four outcome classes (exact, normalised, close, none), the similarity score, the section/page locator, and the W3C TextQuoteSelector, plus advice to quote the source's own words on a 'close' result.

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, no filler. The core purpose and accepted sources come first, with the return categories and the 'before citing' directive layered after.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description's enumeration of result types, similarity score, locator and TextQuoteSelector is exactly what an agent needs to interpret the response. Combined with usage and source semantics, nothing material 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?

With 100% schema coverage, the baseline is 3. The description goes beyond it by expanding what 'source' accepts – 'a paper (any ID read_paper takes) or a web page URL' – tying the paper-ID namespace to a sibling tool, and by framing the quote as the thing being verified.

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 (check) and resource (quote against its source), and names the two source kinds it accepts. It is clearly distinguishable from siblings like get_paper or read_paper, which retrieve rather than verify.

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 'before citing a definition or a claim', giving a concrete decision point. It does not name an alternative tool or state when not to use it, so it stops short of full when/when-not 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 destructiveHint=true, readOnlyHint=false, idempotentHint=true. The description adds real value beyond that: it names exactly what is destroyed (whole library + SportRxiv copy) and adds a consent precondition. It does not discuss reversibility or downstream effects (e.g. SportRxiv side effects), hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the destructive scope and then the consent gate. 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?

For a destructive, irreversible-sounding single-param tool, the description covers scope, consent gating, and shares the safety burden with annotations. It leaves some ambiguity about whether the SportRxiv deletion is propagated externally, but is otherwise complete enough to call 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% and the 'confirm' parameter is already documented as 'Must be true to delete.' The description reinforces intent ('only when the user asked for it') but adds no format/syntax 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?

States a specific destructive verb ('Delete') and a precisely scoped resource (the user's whole football-docs paper library and the SportRxiv copy), including the destructive scope detail that distinguishes it from sibling forget_paper.

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 gives the gating condition for invocation: 'Call with confirm: true only when the user asked for it.' This is clear when-to-use guidance plus an exclusion, tying directly to the required parameter.

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?

Goes well beyond the readOnly/openWorld annotations: discloses caching behavior ('second call sends no request'), the 200-character passage cap, the licence returned, that it never logs in and halts at bot checks, and what happens on failure. 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?

Five tight sentences, front-loaded with the primary action and scope; each sentence carries distinct operational information (modes, caching, truncation, failure routing) with no 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?

With no output schema, the description fully covers return shape (full text by section with licence, or outline plus passages) and error behavior, which is what an agent needs to call and interpret this 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 coverage is 100%, so baseline is 3; the description adds real meaning by tying `query` to passage/section/page results and `section` to the outline from an earlier call, and by explaining the passage-length constraint applied to returned text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Read a paper's text') and immediately distinguishes two operating modes: fetching an open copy in full versus returning only an outline with short passages for user-supplied papers. This differentiates it from metadata siblings like get_paper and search_papers.

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 triggering context and explicitly routes the agent to add_local_paper when no open copy can be read, and notes the zotero:/local: identifier paths. It lacks explicit 'use X instead when Y' statements against all siblings (e.g. get_paper), 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.

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

Annotations indicate non-read-only and non-destructive. Description adds that it's a queued request, not an immediate modification, which is crucial behavioral context. 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?

Three sentences, each purposeful: states action, gives usage context, and adds behavioral note. No unnecessary words, front-loaded with key 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?

Given the simplicity (4 params, no output schema), the description covers purpose, usage scenarios, and queuing behavior. Lacks detail on return value or confirmation, but sufficient for agent decision-making.

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?

Input schema has 100% coverage with clear descriptions for each parameter. The description does not add new parameter information beyond what the schema provides, meeting baseline but not exceeding.

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 verb 'Request' and the resource 'provider's documentation', specifying actions (add, update, recrawl). It distinguishes from sibling tools like get_provider_docs or search_docs which are read-only.

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 states when to use: 'when you notice docs are outdated, a provider is missing, or you know of a better documentation source.' It also notes requests are queued, implying delayed action. Missing explicit when-not-to-use or alternatives among siblings.

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 only cover the read-only, open-world, non-destructive profile, but the description adds substantial behavior: the source fallback order (local DuckDB, then API), the exact degraded-mode return (setup steps plus a DuckDB query) when unconfigured, API key issuance policy, the release-stamp check against a live URL, the offer to run a curl download, and that the next call picks up the new file without a restart.

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 in the first sentence and the mode/precedence information follows logically. The tail about weekly releases, the release-stamp URL, the curl command and the download URL is operational detail that is useful but dense; it could be tightened without losing 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 six-parameter, all-optional resolver with no output schema, the description covers inputs, sources, auth, degraded mode and freshness workflow well. The main gap is that it never sketches the shape of a successful result (e.g. one ID per provider), so an agent knows how to call it but not quite what to expect back.

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 already 100%, so a 3 is the baseline, but the description adds value by explaining how parameters combine — 'look up by provider + id (pass namespace too, e.g. transfermarkt \'spieler\', opta \'person\')' — and by clarifying that a name match is a shortlist rather than an answer. It does not document the type enum or the id/reep_id fields beyond what the schema already says.

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 ('Map... to its IDs') and resource (football entities in the Reep register), enumerates the entity types and target providers, and lists the three lookup modes. It is clearly distinguishable from siblings like resolve_provider_id because it scopes itself to cross-provider ID resolution via the Reep register.

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 conditional guidance: look up by provider+id (with namespace), by reep_id, or by name; and it states prerequisites such as REEP_DUCKDB_PATH / REEP_API_KEY, that keys are issued by hand, and that the file should be current before bulk matching. What it never does is name a sibling alternative (e.g. resolve_provider_id) or state when NOT to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's additional behavioral context is minimal. It adds that resolution maps to a canonical key, which is consistent. No contradictions, but no extra behavioral details like error handling or idempotency.

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: first states the action concisely, second lists usage examples. No wasted words. Front-loaded with the core purpose.

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 tool's simplicity (one param, no output schema, read-only), the description fully covers what an agent needs: purpose, when to use, and input examples. No gaps.

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 description already defines the query parameter. The tool description adds concrete examples (e.g., Stats Perform, Opta F24) that help clarify acceptable input values, enhancing semantic understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: resolving a provider name/alias to a canonical key. It specifies the verb 'resolve', the resource (provider name to key), and lists numerous examples, leaving no 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?

Explicitly says 'Use when users mention brands, vendors, products, or aliases' with specific examples. Implies it's a preprocessing step for searching. Lacks explicit exclusion criteria but provides clear guidance on when to invoke.

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, non-destructive, closed-world), and the description adds real behavioral context beyond them: partial-result marking, disclosure of unmatched query terms, and an explicit explanation when a provider is not indexed. It does not address ranking depth or result-count behavior beyond max_results, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose in the first sentence and then the use cases, which is the right ordering. The middle clause about partial results, unnamed terms, and unindexed providers is dense and slightly repetitive, but each clause carries actionable information for interpreting results.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the work of explaining return semantics (most relevant chunks, partial flagging, diagnostic messages), which is exactly what an agent needs here. Remaining gaps are minor: how results are ranked and whether there is any result-count ceiling.

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 all three parameters are already documented in the schema, including query examples and the provider filter. The description only indirectly supports the 'provider' parameter via its note about unindexed providers and adds no syntax or format detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search football data provider documentation') and then enumerates the exact content types it retrieves (event types, qualifier IDs, endpoints, coordinate systems, data models, cross-provider mappings). That enumeration separates it cleanly from siblings like get_provider_docs and list_providers without needing to name them.

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 finding event types, qualifier IDs, API endpoints..." gives clear positive context for when to invoke it, which is more than most search tools offer. It stops short of explicit when-not guidance or naming the alternative (e.g., get_provider_docs when the provider/topic is already known), so it misses the top band.

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, openWorld, non-destructive), so the bar is lower. The description still adds real context: OpenAlex matches full text so a hit may merely cite the idea, the reply names which services were queried, and FOOTBALL_DOCS_PAPERS=off disables lookups entirely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and sources, then usage, then caveats. Every sentence carries information, though the block is dense and the full-text caveat is woven in mid-paragraph rather than isolated.

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 5-parameter, read-only, no-output-schema tool the description covers sources, matching behavior, routing to siblings and an environment gate. It only lightly touches what the reply looks like beyond naming the services queried, but nothing essential for correct invocation 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 query, sources, year_from/year_to and max_results with examples and defaults. The description's query-syntax hints (quoted phrases, AND/OR/NOT) largely restate the schema, and only the full-text matching nuance goes beyond it. 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 (search) and resource (scholarly papers) with the exact scope: OpenAlex, arXiv and SportRxiv, and which fields each covers (title, abstract, full text). An agent can distinguish it from get_paper, read_paper and search_docs without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete use cases (find the paper behind xG, VAEP, EPV, pitch control, or works that cite an idea) and an explicit alternative path for material without a DOI: search the web and read it with get_web_source. Both when-to-use and when-to-route-elsewhere are stated.

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