meta-agent-tools

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description is consistent with them. Beyond that it discloses a 60-second cache TTL and characterizes the call as 'a MAT catalog read, like the list', which is real behavioral context an agent cannot get from 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 purpose statement is front-loaded well, but the description then restates itself: 'every skill its card declares' appears in the first sentence and is re-listed verbatim in the second, along with duplicated coverage of capabilities and protocol version. The duplication costs space without adding 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?

With no output schema, the description carries the return-value burden and does enumerate the response shape (skills, capabilities, protocol version, docs/icon URLs, first-seen timestamp, registries and licenses). For a 3-parameter read tool with full schema coverage this is sufficient, though auth/licensing nuance for api_pass is left to the 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 description coverage is 100%, so all three parameters (chave, api_pass, retry_key) are already documented in the schema. The description only reiterates that the key comes from a2a_agent_search, adding 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?

It states a specific verb and resource ('Read one A2A agent') and enumerates the salient contents (skills, capabilities, protocol version, health, registries). The final clause 'The same row as the list plus what the card declares' cleanly positions it against the sibling a2a_agent_search (the list).

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?

'Take the key from a2a_agent_search' gives a concrete prerequisite and implicitly routes the agent: use search to obtain the chave, use this tool to fetch the single record. There is no explicit when-not guidance, but the list-vs-single split is clear from 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is real: it discloses the 60s cache window, the retry_key idempotency window, that data is unfiltered/unreviewed and served live from public registries, and that the call is forwarded to a MAT catalog index host. It stops short of describing auth requirements for the private api_pass 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?

The purpose and filter logic are front-loaded and earn their place, but sentences like 'no review queue hides a record; quality is the order, never visibility' and 'which travels with the data' are promotional filler that a calling agent gains nothing from. Trimming those would make it tighter without losing any operational 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 an 11-parameter, no-required, read-only search tool with no output schema, the description supplies the row shape (merge across registries, `fontes`, `creditos`, `key` for a2a_agent) and the combination semantics. It omits only return-count/pagination framing, though the schema's `_links.next` hint covers that adequately.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: values within one parameter are OR'd while different parameters are AND'd. That is genuinely useful combination logic beyond per-field docs, and the per-field meanings are left correctly 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 first sentence names a specific verb (Find) plus the resource (A2A agents, defined as agents publishing an AgentCard) and enumerates the searchable axes: text, health, protocol version, registry, skill tag, publisher. It also implicitly separates itself from the sibling a2a_agent by stating each row carries that tool's key, so an agent can tell the search tool from the fetch 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 implies the workflow (search here, then use the `key` with a2a_agent) and states the OR/AND filter semantics and 60s cache, which guide how to call it. But it never explicitly says when to prefer this over siblings like mcp_index_search or feed_search, nor any conditions to avoid it. Usage is inferable rather than stated.

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/non-destructive, so the description earns credit for adding real context: a per-crawler-family daily allowance of 1,000 reads with 429 on overage, billing being disabled, and no X-API-Pass required. This is meaningful behavioral detail beyond 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?

Six dense sentences mixing purpose, crawler rate limits, billing state and index scope; the core 'what does this return' statement is buried and diluted. Informative but not front-loaded or tight for a single-parameter status tool.

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 should clarify what the status call returns, but it never states the response shape. Quotas, billing state and scope are covered adequately, leaving the return-value gap for a tool an agent must call to check access.

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

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

Schema coverage is 100% and the schema already documents api_pass format and its 'generate before buying' note. The description adds only tangential context ('pass prefix mat_', 'reads need no X-API-Pass'), so the baseline 3 applies since the schema carries the parameter semantics.

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 opening says it reports 'monthly data package and private purchase status' and a 'MAT-only balance,' which hints at a status/balance read, but the phrasing is muddled and never states a clean verb+resource. It distinguishes scope (MAT-only, separate from other indexes) but not from siblings like api_usage or api_access_buy.

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?

There is no explicit when-to-use or when-not-to-use guidance. The line 'there is no package to buy' faintly implies api_access_buy is not applicable, and 'reads need no X-API-Pass' implies the pass may be omitted, but neither is framed as routing advice.

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?

Adds substantial context beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): explicit payment requirement, MAT-only balance, current disabled-billing state, and the 429 behavior once the shared crawl allowance is exceeded. This is exactly the kind of operational context annotations cannot express.

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

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

Front-loads the offer, price and validity, then layers caveats, which is the right ordering. It is somewhat sprawling, however: the crawler-family allowance and 429 details read as api_access behavior rather than this purchase tool's, adding length that does not serve the buying decision.

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?

Covers everything an agent needs before calling: price and duration, required payment, required pass format, current unavailability, rate-limit consequences, and the separation of MAT allowance from other indexes. With no output schema, the remaining gap (return payload shape) is minor for a purchase endpoint.

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 payment, api_pass, transaction and credit_token in detail. The description only restates the mat_ prefix and MAT-only rule that the api_pass schema field already contains, adding no new parameter semantics. 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 precise verb+resource with concrete terms: 'Buy 1,000 basic data reads for US$1, valid for 30 days.' It also carves out what this tool is not for ('Catalog discovery and ordinary browsing are free'), separating it from api_access and the free-browsing path without requiring schema inspection.

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 usage context: free operations are called out, payment must be explicit, and it warns that 'Billing is off for now: there is no package to buy,' which effectively tells the agent not to invoke it. It stops short of naming a specific sibling (api_access, pricing, billing) as the alternative path.

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 only that the payload includes quota and quickstart content, which is modest added context beyond the structured data, hence a middle 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?

A single compact sentence with no filler, and the key content (whole API surface, quota, quickstart) is front-loaded. It is efficient, though arguably under-specified rather than ideally concise.

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 and no parameters, the description carries the burden of explaining what comes back and it only gestures at it ('quota and quickstart'). For a zero-arg discovery endpoint that is minimal-but-adequate rather than complete; a caller still cannot tell what shape or size of index to expect.

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 takes zero parameters, so there are no parameter semantics to explain; the baseline for a no-arg tool is 4. Nothing in the description contradicts or confuses the empty 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 identifies the resource (the API surface) and that it is a self-describing index containing quota and quickstart material, but 'self-describing index' is loose phrasing and it does not distinguish this discovery tool from close siblings like index_stats or mcp_index_search. An agent gets the general idea but not a precise verb+resource contract.

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?

There is no statement of when to call this versus the many other index/discovery tools (index_stats, mcp_index_search, mcp_index_signals, api_usage). With 29 siblings and several near-duplicates, the absence of any routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds one genuinely useful behavioral fact beyond that — the call does not consume credit — but says nothing about auth expectations, rate limits, or response shape.

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?

It is a single compact phrase with no filler and the distinguishing detail (no credit consumed) placed immediately. It is arguably too terse to stand alone as a sentence, which keeps it from a 5.

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

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

With one well-documented parameter, safe annotations, and no output schema, the description is adequate for calling the tool. It hints at the return value (remaining credits) but gives no sense of the response shape, so it is minimum viable rather than 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?

There is a single parameter (api_pass) and schema description coverage is 100%, with the schema explaining the mat_<hex>_<hex> format and how to obtain it. The description adds no parameter meaning at all, 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 names a specific quantity (remaining MAT read credits) and a key property of the operation (does not consume credit), so the agent knows what comes back. It does not differentiate itself from adjacent credit/billing tools such as api_access, api_access_buy, or billing, so it stops short of a 5.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no routing to alternatives like api_access_buy for purchasing more credits. The implied use case (check balance before spending) must be inferred entirely.

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 does not go beyond them to explain what 'configuration in force' means, whether the data is live or cached, or what 'agent prices for contact and publishing' refers to.

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?

It is a single short sentence with no padding, which is good, but the sentence is syntactically broken and buries the subject, so the brevity does not translate into clarity.

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 and no parameters, the description must carry the burden of explaining what is returned. Instead it offers a cryptic phrase, and it does not distinguish this tool from the similarly scoped 'pricing' sibling, leaving the agent under-informed.

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 takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 reads as a fragment ('x402 configuration in force and the agent prices for contact and publishing') with no clear verb. It hints that the tool surfaces x402/billing configuration and pricing, but an agent cannot confidently say what the tool actually retrieves or how it differs from the sibling 'pricing'.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the overlapping sibling 'pricing'. The agent is left to infer that this is an informational read, which the annotations already imply.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive); the description adds real behavior: page size of 20, per-filter counts returned, unknown filter values ignored rather than erroring, and a `_links.next` cursor for pagination. That is genuinely useful context beyond 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?

Extremely dense but front-loaded: resource and filters first, then paging/combinator rules, then the walk instruction. Every clause carries a distinct fact; no filler sentences.

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 compensates by naming the `_links.next` cursor and the per-filter counts. It does not describe the link records' fields themselves (title, url, etc.), which leaves a small gap for an agent assembling output, but the invocation contract is otherwise fully covered.

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 enum is documented, so the baseline is 3. The description goes beyond it by explaining that values are comma-separated lists with OR semantics inside a parameter and AND across parameters, and that unknown values are dropped rather than rejected — semantics 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?

States a specific resource ('curated engineering links') plus the two filtering axes (topic and source type) and enumerates the valid source types inline. It also differentiates from the sibling briefings_topics by noting topic slugs come from that 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?

Gives clear operating context: 20 per page, OR within a parameter, AND across parameters, unknown values silently ignored, and follow `_links.next` to exhaust the set. It implies when to use it (browsing curated links by topic/type) but never states an explicit alternative or when-not condition beyond the briefings_topics pointer.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: item contents (source, source type, two-line summary in English and Portuguese) and the '404 until the first publication' availability constraint. It stops short of describing pagination or ordering of the 'newest links'.

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?

Reasonably front-loaded, but it repeats the same payload description twice ('source, source type and a two-line summary' appears in both the second and fourth sentences), and the first sentence is a run-on combining counts and newest links. A trim would help.

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-shape burden and does so adequately, enumerating topics, counts, links and per-item fields, plus the slim `?resumo=1` variant. The main gap is that it never clarifies its relationship to briefings_links.

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?

Zero declared parameters, so the baseline is 4. The description does mention a `?resumo=1` query flag that returns only `total`, `slug` and `total` per topic, which is useful semantics, though oddly it is not represented in the empty input schema.

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

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

States a specific resource (engineering topics with curated briefings) and the returned quantities (counts plus newest links), which is well beyond a tautology. However, it never distinguishes itself from the sibling briefings_links, so an agent must guess which of the two to pick.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative, despite briefings_links being an obviously overlapping sibling. The only usage-adjacent detail is the `?resumo=1` slim-mode flag, which is a mode switch rather than routing advice.

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

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

Beyond the annotations it discloses substantial behavioral traits: no captcha, no account, no payment required; a rate limit of one message per 10 s per network; and the exact overflow behavior (a sooner-arriving message waits its turn rather than erroring). It also explains delivery — the message reaches the team by e-mail and `email` becomes the reply address.

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, which is good, but the text repeats itself for no gain: 'Free, no captcha and no payment' is restated as 'No captcha, no account, no payment,' and the 10-second-per-network queue rule is stated twice in near-identical wording. The parenthetical insertions also make it denser than 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?

For a 10-parameter, non-read-only, non-idempotent tool with full schema coverage, the description covers what matters: no auth/payment, throttling behavior, and message delivery. Since there is no output schema, it could say more about the success/error response, but the queueing note covers the main failure mode.

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 the baseline is 3, but the description adds real meaning: `tipo` selects the proposal route and its `espaco` placement ids come from `GET /api/partners`, and `email` is used as the reply address in the delivered e-mail. It does not, however, explain field applicability per `tipo` value beyond noting that the proposal fields turn on.

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: write a question or a sponsorship/partnership/ad proposal to the people behind the product. That is unambiguous and cannot be confused with any sibling (billing, endpoints, environments, etc.), though it never explicitly differentiates itself from a named 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 clear usage context: use it for a question or for a sponsorship/partnership/ad proposal, and states that a single route serves both cases via `tipo`. No exclusions or named alternatives are offered, but with no competing sibling there is little to disambiguate.

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?

Adds real behavioral context beyond the annotations: a per-network rate limit of 20 new guests per hour and cookie-based reuse ('a browser that already has one gets it back from the mr_guest cookie'). The cookie-reuse statement sits in mild tension with idempotentHint=false, but it describes a client-side cookie mechanism rather than true request-level idempotency, so it is context rather than a contradiction.

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

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

Three short sentences with the verb front-loaded, but the telegraphic style ('mr_…', fragmented clauses) reads like notes rather than a coherent description. It is compact, but the cryptic token fragment and slightly scattered sentence order cost structure points.

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 creation tool with no output schema, the description covers the key operational facts: no email needed, rate limiting, and cookie-based identity reuse. It is largely complete, though it could be slightly more explicit about what the returned guest token is used for.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The prose correctly implies no inputs are required (no e-mail), which is consistent with the empty 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+resource ('Creates a guest') and the 'mr_…' fragment signals the returned token type. It also implicitly distinguishes this from create_listing by noting publishing a listing needs an account, helping the agent tell it apart from account-creation siblings. The truncated 'mr_…' is the only clarity blemish.

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?

'Asks for no e-mail' and 'Publishing a listing is what requires an account (or a payment)' imply the use case is anonymous/guest access before an account exists. However, no explicit when-to-use or when-not-to-use against alternatives in the sibling list (e.g., api_access, create_listing) is given; the routing is inferred rather than stated.

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 say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes far beyond that: cost ($0.10 for agents), quota limits, automatic vs human review, and critically the ordering guarantee that 400 (refused body) and 429 (exhausted quota) fire BEFORE the 402 so no payment settles for a listing already known to fail. That is exactly the kind of consequence detail an agent needs before invoking a paid mutation.

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, which is good. But the body is a dense wall of payment detail with visible redundancy: the 402-with-accepts point is made twice ('402 with accepts[], $0.10 — pay and repeat' and 'A valid body without payment keeps receiving the 402 with the price'), and the rhetorical 'Two doors to the same action' consumes space without adding operational content.

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 must cover outcomes, and it does: it directs the agent to poll status_api (GET /api/listings/:id/status) for the review decision and explains the review and validation order. It stops short of stating what the immediate successful response returns (e.g., the new listing id), which the polling instruction only implies.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including url, kind and body. The description's parameter-relevant content ('For a skill, the SKILL.md URL is enough') slightly reinforces the url semantics but adds no format, constraint or default information beyond the schema. Baseline 3 applies.

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

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

The first sentence states a specific verb and resource set: 'Registers an MCP server, skill or plugin,' which tells an agent exactly what the tool produces. It does not, however, name or contrast itself against likely-confusable siblings such as submit_okf or create_guest, so the agent must infer the boundary.

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 concrete conditions: a human with a session is free (1/day, queue of 3), an agent hits a 402 with accepts[] at $0.10, and it points to status_api for the decision. It also offers an alternative path for OKF bundles ('POST /api/okf/ping is free'), but the guidance is framed around payment flow rather than choosing among sibling tools.

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 safety is covered. The description adds useful non-obvious behavior: ordering by recency vs relevance, keyset vs offset paging, and an indexing disclaimer. That value is diluted because the paging and ordering rules reference parameters (`q`, `next_cursor`) absent from the schema.

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

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

The core capabilities lead, but there is filler: 'the question a reader or an agent actually asks' and the closing 'We index and link; the feeds belong to whoever publishes them' add no operational information. Roughly one third of the text is rhetorical rather than directive.

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 should clarify the response shape, yet it only says 'answers with every feed.' Worse, it describes a filtering/paging interface the 3-parameter schema cannot express, leaving the agent unable to reconcile the description with what it can actually send.

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 each of the three real parameters (dominio, api_pass, retry_key) is documented in the schema itself, so the baseline would be 3. The description adds no meaning for any of them and instead describes filters, `q`, and `next_cursor` that do not exist in the schema, actively confusing the agent about what it can pass.

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 opening question ('Does this site publish a feed?') plus 'Answers with every feed known for a domain' names a specific resource (feeds) and scope (per domain), so the agent knows what it returns. It does not explicitly differentiate itself from close siblings like feed_search or feed_posts, so it stays below a 5.

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

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

It does give conditional usage ('without q ... with q ...') and describes ordering and paging modes, which is real guidance. However, it never states when to prefer feed_find over feed_search/feed_posts, and the conditions hinge on a `q` parameter that the schema does not expose, so the routing advice is muddled.

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/idempotent annotations by disclosing that the body comes from a stored copy and is never fetched live, that HTML is sanitized via an allowlist (script/style/iframe/event handlers dropped with content), and that a 404 is returned for unknown feed or position. These are exactly the freshness, safety and error semantics an agent needs.

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

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

Front-loads the purpose and the two outputs, then layers in caching and sanitization caveats. It is dense and mostly earns its place, though the sanitization paragraph repeats the 'cannot carry script' point twice, adding a little 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?

With no output schema, the description usefully enumerates the returned fields and the 404 error case, and it documents the caching model. It is complete enough to call correctly, though it does not clarify the identity format of `id` or interaction with retry_key beyond what the schema states.

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 repeats the `ord` origin and 0-is-newest semantics already present in the schema, and says nothing about `api_pass` or `retry_key`, so it adds little beyond the structured fields.

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 ('Read one post whole') and names the concrete return fields (`conteudo`, `conteudo_html`, original link), which an agent can distinguish from the list-oriented siblings feed_posts and feed_search. It also clarifies the ordering key (`ord`) that anchors the read.

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

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

Explicitly routes the agent to feed_posts as the source of `ord`, implying the correct two-step workflow. It lacks a direct statement of when not to use it (e.g. use feed_posts for multiple posts), so it falls short of the explicit alternatives/exclusions bar.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial context: result cap (40), publication ordering, body exclusion, that it is OUR snapshot copy rather than a live feed/proxy, and the empty-list behavior when unread. This is well beyond what annotations provide.

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 a clear framing question, but the same constraints are stated twice ('never a URL' twice, 'WITHOUT the body' twice), making it needlessly repetitive. The core signal is strong, but the wording is padded.

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 compensates fully by enumerating returned fields (title, date, author, summary, categories, enclosure) and their exclusions (no body), plus the empty-list case. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds real meaning to the id param by stressing it must be an id from this index and never a URL, and hints at the snapshot semantics ('lido_em says when we read it'), but it does not extend the api_pass or retry_key parameters.

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 ('the posts of one feed... without the body') and enumerates returned fields. It clearly distinguishes itself from feed_find/feed_search (finding the feed) and from the single-post endpoint, so an agent can route correctly 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?

Gives explicit prerequisites (find the feed first via feed_find or feed_search) and an explicit constraint ('takes an id from this index, never a URL'). It also names the alternative for the body ('/items/:ord'), covering when this tool is and is not 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 cover the read-only/idempotent/non-destructive profile, but the description adds behavior beyond them: keyset cursor paging without `q` vs offset paging with `q`, relevance-vs-recency ordering, and an explicit 'we index and link' ownership caveat. That is meaningful context the annotations do not carry.

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 paging and boolean logic are front-loaded and useful, but the opening two sentences ('Search the feed index by text and filters...' / 'Find feeds by text, format, language and availability') restate the same idea, and the trailing ownership line is tangential. Slightly redundant rather than wasteful.

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 9-parameter, no-output-schema search tool, the description covers the critical calling contract: paging model, ordering, filter composition, and an auth-related pass parameter. It is largely complete, with only minor gaps (the 'year'/'language' filters it mentions have no corresponding schema parameter).

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

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

Schema coverage is 100%, so the schema already documents every parameter and the baseline would be 3. The description still adds value by explaining the OR/AND composition semantics across parameters and describing the cursor vs offset paging contract, which the flat schema cannot express.

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

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

The description opens with a specific verb+resource ('Search the feed index') and enumerates the filter axes, so the tool's purpose is unambiguous. It does not, however, explicitly distinguish itself from close siblings like feed_find or feed_posts, leaving the agent to infer the boundary.

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 real operational guidance: filter/text run in the same full-text query, values within a parameter are OR'd and across parameters AND'd, and it explains what to do with and without `q`. It stops short of naming a concrete alternative tool to use instead in other cases.

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 safety profile is covered and the description needn't repeat it. It does add genuinely useful behavior — that low/example bundles (normally hidden from search) are reachable here, and what fields are returned. It says nothing about auth, rate limits, or behavior for a missing/invalid 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 tight sentences, front-loaded with the returned payload before the scoping caveat about live/low bundles. No filler, though terms like 'provenance' and 'repository signal' are left undefined.

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 right thing by enumerating the returned fields, and it flags the non-obvious live/low behavior. The remaining gap is the undefined semantics of 'provenance' and 'repository signal', which an agent may need to interpret.

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?

There is one parameter with 100% schema description coverage ('Bundle id, the `id` of every item in the list'), so the schema carries the semantics. The description adds no format, source, or lookup guidance for the id beyond what the schema already says — baseline 3 for high 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?

The description names a specific resource (one bundle) and enumerates exactly what the card contains — root index.md URL, version, concept count, provenance, repository signal — so an agent can tell it apart from search_bundles or list_listings by output shape. It never explicitly names the alternative, but the singular scope is unambiguous.

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 note that `live` and `low` (example/fixture bundles excluded from search) 'both answer here' gives a real usage hint: this tool reaches bundles search won't return. However, it never states the prerequisite (obtaining a bundle id from search_bundles) or when to prefer this over search_bundles, leaving usage only implied.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds one genuinely useful behavior beyond annotations: an owner sees their own listing even when it is pending or hidden, which implies visibility varies by caller identity. It does not mention auth requirements or the retry/api_pass semantics.

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 very short sentences with no waste and the resource identity front-loaded. The terseness is nearly cryptic ('One listing's page' reads more like a fragment than a full statement), which keeps it just short of exemplary.

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 should say what a 'page' returns, and it doesn't; the unusual MAT-only api_pass acquisition flow is left entirely to the schema. The owner-visibility note partially compensates for a simple single-fetch tool, but key expectations remain 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 description coverage is 100%, so the schema already documents id, api_pass, and retry_key thoroughly (including provenance and format). The description adds nothing about parameter meaning, which is acceptable given the schema does the work, but it earns no bonus.

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

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

The description states a specific resource ('One listing's page'), which distinguishes it from the list-shaped siblings like list_listings and search-like feed tools. The verb is implicit ('get' is carried by the name/title) but the singular scope is clear. It stops short of naming which sibling to use instead.

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?

There is no explicit when-to-use guidance or routing vs alternatives such as listing_status, listing_history, or get_listing_readme, all of which plausibly answer questions about a single listing. The visibility sentence hints at an owner-scenario but never frames it as a selection criterion.

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

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

Annotations already declare readOnly/idempotent/non-destructive and the description is consistent with them, while adding context the annotations cannot carry: 404 semantics when nothing was stored, the R2 backing store, and that visibility matches the listing page. This is real behavioral value beyond 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?

The core condition is front-loaded, but the same rule is stated twice ('Only when get_listing carries readme_api; 404 when none was stored' and again in the final sentence), which is redundant padding rather than earning 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 simple read tool, the description covers storage location, visibility model, and error behavior, which is nearly everything an agent needs. Only the separation between the required `id` and the auth/retry parameters is left entirely to the 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 description coverage is 100%, so the baseline is 3 and the schema already documents `id`, `api_pass`, and `retry_key`. The description only implicitly references the listing id and adds no syntax or format detail for the three parameters.

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 combination (retrieve the README collected for a listing) and names the storage location (R2, bucket `mural-coleta`). It also distinguishes itself from the get_listing sibling by making the README's existence conditional on that listing carrying `readme_api`.

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 call it ('only when the listing page carries `readme_api`') and what happens otherwise (404, no README collected). It also rules out a false assumption by noting it does not fetch GitHub. Routing relative to get_listing is unambiguous.

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

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

Annotations declare readOnlyHint=true, but the description states the call 'counts a visit' (persisted per owner per day, alongside a sibling `listing_history`). That is a modification of environment state, so the description directly contradicts the readOnlyHint annotation. Flagged as an annotation contradiction.

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

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

Three compact sentences with the primary mechanism front-loaded and no filler. Minor deduction for jargon ('302 hop', 'counts a visit') that could be stated more directly.

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 should describe what the caller receives (the redirect target and the `X-Visit-Counted` header). It covers the header and the dedupe rule, but never explains the redirect destination or how a client is expected to follow the 302, leaving a real gap for a single-param tool.

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

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

Only one parameter (`id`) exists and schema description coverage is 100%, so the schema already carries the semantics. The description adds nothing about the ID's format or scope, making the baseline 3 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 conveys the mechanism (a 302 redirect to the listing's origin URL) but uses jargon ('302 hop') rather than a plain verb+resource statement. It never clarifies how this differs from the sibling `get_listing` or `listing_history`, so an agent must guess which one to call for a given intent.

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?

There is no explicit when-to-use guidance and no alternative named among the many listing siblings (`get_listing`, `listing_history`, `listing_status`). The only implied usage signal is that calling it registers a visit, which an agent could infer but is not stated as a selection rule.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value by revealing that the response includes the commit deployed right now, which is not derivable from annotations. It stops short of describing the response fields or whether a failing check returns an error status, which matters since there is no 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?

A single short sentence that front-loads the core concept ('Liveness'). It is efficiently sized, though the trailing clause about the smoke test is ambiguous rather than informative, slightly reducing its value.

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 parameters and no output schema, the description carries the burden of explaining the return value, and it only gestures at it ('the commit deployed right now'). It does not describe what a healthy or unhealthy response looks like, which an agent needs to interpret the result.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description adds no parameter meaning, but none is needed or possible 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 conveys that this is a liveness endpoint that also reports the currently deployed commit — a specific resource (health/version state). However it opens without a verb and the second clause ('the smoke waits for its own deploy') is internal jargon that obscures more than it clarifies. No sibling is health-related, so differentiation is not required, but the purpose could be stated plainly in fewer words.

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 only usage hint is 'it is how the smoke waits for its own deploy', which vaguely suggests deploy-verification polling but is phrased in opaque team jargon. There is no explicit statement of when an agent should call this versus not, nor any precondition or polling 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the returned statistics (size by provenance, last changed), but it does not describe response format, pagination, or any operational constraints. With annotations carrying the behavioral load, this is an adequate but not rich disclosure.

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 concise sentence fragment with no wasted words, and it front-loads the core output content. It could be slightly clearer with an action verb, but it is efficiently sized for a no-param tool.

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 no parameters and no output schema, the description should ideally explain the shape of the returned statistics. It does provide a high-level summary (size by provenance, last changed), but it leaves the exact response structure unspecified and does not clarify which index is being described, leaving a minor completeness gap.

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?

There are zero parameters, so the baseline is 4. The schema is empty and the description does not need to explain any parameter semantics, making this dimension appropriately handled.

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

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

The description names the resource (the index) and the data dimensions (size by provenance, last changed), but it is a noun phrase without an action verb and does not differentiate itself from related siblings like mcp_index_signals or api_index. An agent can infer it is a stats endpoint, but the purpose is not sharply defined.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no context about what 'the index' refers to. The description only states what data is returned, leaving 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?

Adds genuine context beyond the annotations: DELETE reverses the like, and repeat calls do not stack because the counter counts distinct people rather than calls. This is useful behavioral disclosure. There is mild tension with idempotentHint=false, since the description implies repeat calls are effectively a no-op on the counter, but this reads as nuance about what is counted rather than a direct contradiction.

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

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

Two tight clauses with the primary action front-loaded and no padding. The second clause ('the counter counts people') is slightly cryptic in its brevity but earns its place by conveying distinct counting semantics.

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

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

For a 2-param action tool with no output schema, the description covers purpose, the inverse operation, and repeat-call behavior. It omits auth/permission needs and any explanation of guest_token, leaving the required-token requirement undocumented.

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 only 50% (id is documented, guest_token is not). The description explains nothing about either parameter and never mentions guest_token, so it fails to compensate for the documentation gap. It adds no meaning beyond the schema.

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

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

States a specific verb and resource ('Likes the listing'), which is unambiguous and cannot be confused with the read-oriented siblings like get_listing or listing_status. It does not explicitly name a sibling or an unlike counterpart, so it falls just short of full differentiation, but the purpose is 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?

'DELETE undoes it' and 'Calling again does not add up' imply when the operation is meaningful and what its inverse is, giving real usage context. However, no alternative tool or explicit when-to-use/when-not condition is named, so guidance remains 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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: an authenticated call marks the caller's own comments with `mine: true`, which the agent could not infer from the annotations or 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 short sentences, front-loaded with the resource scope and then the auth-dependent response flag. Nothing redundant; every clause carries information.

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

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

For a simple one-parameter read tool with annotations covering safety, the description is nearly sufficient, but there is no output schema and the description says nothing about result shape, pagination, or comment ordering. An agent knows what it fetches but not what it gets 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 100% and the single `id` parameter is already documented as 'ID of the listing'. The phrase 'a live listing' hints that the ID must reference a live listing but adds no syntax or format detail beyond the schema, so the baseline 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 identifies the resource (comments) and its scope (on a live listing), but the action verb lives only in the title 'List comments'. It does not say what is returned or in what order, so the purpose is understandable but minimal.

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 on when to call this versus alternatives such as get_listing, feed_posts, or listing_history, and no prerequisites or boundaries stated. The only condition given ('with a credential') describes a response side effect, not when to use the 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?

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantive context beyond that: it defines cache freshness (up to 15 minutes), explains empty-list semantics, defines stale as no push for 12 months, and clarifies that reading the endpoint does not refresh the record. This is unusually rich behavioral disclosure for a read-only endpoint.

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

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

The description is front-loaded and informative, but it repeats key ideas: 'no push for 12 months' is stated both for 'abandono' and again as the definition of stale, and the empty-list meaning is stated twice. These redundant sentences cost conciseness without adding new 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 read-only endpoint with full schema coverage and no output schema, the description gives strong context on event types, ordering, empty results, caching, and stale semantics. It omits the internal structure of each timeline event, but the core behavior an agent needs is present.

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 input schema already documents id, api_pass, and retry_key. The description adds no parameter-specific syntax or format detail, making the baseline of 3 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 clearly states the resource and output: a timeline of the listing repository's last events, with event types named and ordering specified. It does not explicitly distinguish this tool from siblings such as get_listing or listing_status, so it falls short of a 5 under the rubric's sibling-differentiation requirement.

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 by the purpose statement: an agent can infer that this tool retrieves a listing's repository history. There is no explicit guidance on when to use this instead of alternatives like get_listing or listing_status, and no stated exclusions.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: no credential needed, only the decision is returned and never the unreviewed content, the id is unguessable (`lst_…`), the listing page stays owner-only until public, and responses are cached for 60 s per point of presence. This is exactly the extra behavioral context annotations cannot carry.

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 and states are front-loaded, and most sentences carry real information (caching, credential-free access, visibility rules). It loses a point for redundancy: 'only the decision comes back' is asserted twice in near-identical form, and 'per point of presence' is jargon that costs reading time without adding clarity.

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

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

For a single-parameter, read-only polling tool with no output schema, the description is complete: it explains what is returned (the decision, not content), the state vocabulary, the lifecycle (born pending, auto-review, human review for uncertain cases), and how often to poll. Nothing needed 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?

Schema coverage is 100% and there is only one parameter, so the schema already documents `id`. The description still adds meaning: the id is unguessable and prefixed `lst_…`, and it comes from the `POST /api/listings` response, reinforcing provenance beyond the schema's own wording.

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

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

States a specific resource and action: the moderation state of a listing, with the enumerated states (pending/live/low/hidden/blocked) and the trigger point ('poll it after create_listing'). It is clear what the tool returns. It does not explicitly distinguish itself from siblings like get_listing or listing_history, which also surface listing data, so sibling differentiation is left 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 concrete when-to-use: poll after `POST /api/listings`, whose response carries this URL as `status_api`. It also gives cadence guidance ('poll every few minutes, not every second'). No explicit when-not-to-use or named alternative (e.g., why not get_listing), which keeps it below 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 cover the read-only/idempotent/non-destructive profile, yet the description adds substantive behavior: the `low` tail is always ordered after `live` results, the cursor is keyset-based with no ceiling, FTS5 is kept in the same transaction as text writes, and `low_count` is a LIKE with a 200 cap. These are non-obvious traits an agent cannot get from annotations alone.

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 opening states the purpose first, but the single dense block then mixes filtering behavior, cursor mechanics, implementation internals (FTS5, bm25, keyset), and tangential facets (HTML pages at /l/:id, the sitemap XML shards) that an agent calling this tool does not need. Several sentences are informative but the whole is longer and more jargon-laden than necessary.

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 burden of explaining the return surface, and it does name the cursor field (`next_cursor`) and `low_count`. Combined with coverage of ordering, filtering, and tail behavior for an 8-parameter, zero-required tool, it is close to sufficient, though it never states what a listing record contains.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters in detail, including the bm25 weighting and retry_key window. The description largely restates those semantics rather than adding new meaning, which is the baseline-3 case; only the `q` + `low=0` → `low_count` interaction adds novel framing.

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 opening sentence names the resource concretely: 'Public mosaic of live MCP servers, skills, plugins and OKF knowledge bundles,' and the schema's kind enum confirms the scope. It does not, however, distinguish this tool from siblings like list_mcp_servers, mcp_index_search, or search_bundles, so an agent must infer the boundary.

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 real operational guidance — follow `next` to walk everything, `low=0` to drop the tail, `interpret=0` to disable query understanding — but never states when to choose this tool over the sibling search/list tools. Usage is implied through option behavior rather than routed explicitly.

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 with the hard filter (only kind=mcp, only live) and the canonical-vs-alias route distinction, but says nothing about result shape or paging behavior beyond what the schema states.

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 endpoint and scope are front-loaded and the passage overall is short. However, 'Only live kind=mcp. Only `kind=mcp` and only `live`.' is a verbatim self-duplication, so not 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 zero-required-parameter listing tool, the description covers scope, filtering, and route semantics, and the schema covers input and pagination. With no output schema, however, it never hints at what a result entry contains, leaving a real gap for an agent deciding what to do with the response.

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 all five parameters individually documented (limit, cursor, search, api_pass, retry_key), so the schema does the heavy lifting. The description adds no syntax, format, or default detail beyond it, making the baseline 3 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 identifies the exact resource and scope ('MCP subregistry (GET /v0.1/servers)', filtered to live kind=mcp entries), which tells an agent what the call returns. It never states the verb 'list' explicitly and does not distinguish itself from close siblings such as mcp_index_search or mcp_index_signals, so it falls short of a 5.

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

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

There is a hint of intended use ('the route a generic MCP client knows how to read without knowing this product'), but no explicit when-to-use, when-not-to-use, or alternatives are named. With siblings like mcp_index_search and mcp_index_signals in the same family, the agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavior the annotations do not: results are sorted newest-change-first and filters are AND'd, both of which affect how results must be read. It does not cover pagination or the api_pass/retry_key operational implications, keeping it short of a 5.

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

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

Three short sentences with the scope and sort order front-loaded. The casou=0 concept is explained twice, which is mild redundancy, but overall the text is tight and every sentence carries usable 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 7-parameter read-only search with full schema coverage and no output schema, the description supplies what the schema cannot: result ordering, filter conjunction semantics, and the interpretation of the casou=0 slice. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100% (every parameter, including the casou enum and the fonte/estado enums, is documented in the schema), so the baseline is 3. The description restates the meaning of casou ('what the indexes know and the catalog does not') and the AND-combination rule, adding only marginal semantics beyond the schema.

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

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

The description gives a concrete verb and resource: 'Browse what independent MCP indexes measured,' and scopes it to servers 'this catalog does not list yet (casou=0).' This distinguishes it reasonably well from catalog-listing siblings, but it never explicitly names an alternative tool, so an agent must infer the boundary against mcp_index_signals or index_stats.

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

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

Usage is implied rather than stated: 'the list to look at before submitting a server' suggests a pre-submission workflow, and casou=0 is flagged as the relevant slice. However, there is no explicit when-to-use/when-not guidance and no named alternative such as mcp_index_signals or index_stats, so the agent has to guess which sibling to reach for.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the identity-matching rule (registry name, exact endpoint URL, or GitHub owner/repo, in that order; shared domain explicitly excluded) and the output cap of 20 signals, one per index and record. This is meaningful additional disclosure.

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 identity-matching and domain-exclusion sentences earn their place, but the two opening rhetorical questions are stylized filler rather than front-loaded purpose. The ordering buries 'what this tool does' behind questions and could be tightened.

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 adequately: signals per index, access level, repo liveness, license attribution, and a 20-signal ceiling. Combined with annotations and 100% schema coverage, an agent has enough to call it correctly; only the precise response shape is left unspecified.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including the MAT-only api_pass format and retry_key semantics. The description reinforces 'Take the id from list_listings' but adds no syntax or detail beyond the schema. Baseline 3 is appropriate when the 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 core is identifiable: it reports what independent MCP indexes measured about one catalog listing (reachability, access mode, repo liveness, license credit). This is distinct from siblings like mcp_index_search (search) and index_stats (aggregate stats). The rhetorical opening questions ('Does this MCP server still answer...') delay the plain verb+resource statement, but the purpose is ultimately 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?

It states 'Take the id from list_listings', which is a useful prerequisite and couples it to the correct sibling. However, it never says when to prefer this over mcp_index_search or get_listing, and gives no when-not guidance. Usage is implied but not explicitly bounded against alternatives.

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 annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description starts from a lower bar. It does add one genuine behavioral fact not in the annotations — that the endpoint is free to call ('no charge') — but says nothing about freshness, caching, or the shape of the pricing data returned.

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 short sentence with no filler; the content claim is front-loaded and immediately followed by the cost reassurance. 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 zero-parameter, read-only lookup with no output schema, the description adequately states what is returned (public prices and free allowances) and that the call is free. Only the return format or freshness of the pricing data is left unspecified, which is a minor gap at this complexity.

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 takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It appropriately does not invent parameter detail.

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

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

The description names the specific resource it exposes: current public prices and free allowances. It is clear what an agent gets back, though the phrasing is a label rather than a verb+resource statement, and it does not explicitly distinguish itself from sibling tools like billing or api_usage that could also look price-related.

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?

There is no explicit when-to-use guidance and no naming of alternatives (billing, api_access_buy, api_usage). 'No charge' is the only usage-relevant hint, signaling the call itself is free, but which tool to consult for actual account costs versus public list prices is 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 the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: results are restricted to `live` bundles, the list terminates at offset 1000, and no total is returned by design. Those are real operational constraints beyond the structured fields, though return/pagination shape beyond `next_offset` is only lightly touched.

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

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

Front-loaded and information-dense, but it wastes budget repeating the free-text field list almost verbatim in two separate sentences ('free text over name, tagline, description and origin' vs 'Free text matches the name, the tagline, the description and the origin identifier'). The pagination note is also split across two places.

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 12-parameter, zero-required search tool with no output schema, the description covers the key operational facts (live-only, pagination bounds, no total, where to get totals). It omits ordering-default behavior and result-shape detail, but nothing that would cause an incorrect invocation is clearly missing.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters including enums, defaults, and band formats. The description mostly restates this ('search root concept text', 'free text over name, tagline...'), adding little syntax or format meaning that the schema does not already carry. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search the index of OKF bundles') and immediately scopes it: free-text fields, filter axes, pagination, and the `live`-only constraint. It is far more specific than a tautology, but it never names or contrasts a sibling (e.g. get_bundle for retrieval, mcp_index_search for a different index), so the agent must infer routing.

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

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

Usage is implied through mechanism rather than stated: 'Paginate with limit/offset', 'Only `live` bundles', and the pointer to `GET /api/okf/stats` for totals. There is no explicit when-to-use-this-vs-alternatives guidance (e.g. when to call get_bundle instead), so context is inferable but not spelled out.

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 disclose that this is a non-read-only, non-idempotent, non-destructive write; the description goes well beyond that. It explains the 202 response meaning (key not yet checked), that verification and fetching happen on the collector and never at the edge, that nothing is published before the key matches, and the re-send-to-signal-change semantics — all consistent with idempotentHint=false.

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

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

The purpose is front-loaded, but the body is padded with repetition: 'No account, no charge' and 'No account, no payment' say the same thing, and the 202 behavior is stated twice. Several sentences do not 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?

With no output schema, the description carries the return-value burden and does adequately explain the 202 acceptance response and the deferred verification model. It covers limits and required setup, though it does not describe failure responses when the key fails to match.

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's URL-construction notes and the key-file default largely restate what the schema already documents for key, host, urlList, and keyLocation rather than adding new semantics.

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 opening sentence names a specific verb and resource ('Submits OKF bundles') and grounds it with an analogy to the IndexNow protocol. This is clear, but it never distinguishes itself from close siblings like feed_post or api_index, so the agent must infer which submission surface to use.

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 lays out concrete prerequisites (a key file on the host you control, or a keyLocation on the same host) and the operational limits (100 URLs/request, 200/host/day), which tells the agent when the tool is usable. It stops short of explicitly naming an alternative tool to prefer under different conditions.

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