meta-agent-tools

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real operational context beyond them, notably "Cached for 60 seconds" and the "MAT catalog read, like the list" framing. It does not cover failure modes or what happens with an unknown key.

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 lead sentence is front-loaded and useful, but the second sentence restates the same fields (skills, capabilities, protocol version, documentation) already covered in the first, adding redundancy without new information. The size is warranted by the rich return payload, but the duplication costs it.

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 describing return values and does so thoroughly, including the key's provenance and the caching window. It is complete enough for a read tool whose annotations already carry the safety profile.

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

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

Schema description coverage is 100%, so both `chave` and `retry_key` are already documented in the schema. The description's "Take the key from a2a_agent_search" merely echoes the schema's own note about the parameter's origin, adding no format or syntax detail. Baseline 3 is correct.

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 A2A agent") and enumerates what is returned: skills, capabilities, protocol version, health, documentation, registries and licenses. It also delineates itself from the list sibling via "The same row as the list plus what the card declares."

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" establishes the required upstream workflow and implicitly routes the agent: search first, then read the individual agent. No explicit when-not or exclusion guidance is given, but the context is clear.

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

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

Annotations cover only the safety profile (readOnly/idempotent/non-destructive), while the description adds substantial behavioral context the annotations cannot: 60-second caching, no review queue, one row per agent merged across registries, the `fontes`/`creditos` provenance fields, and the fact that the call is forwarded to `https://api.agentalog.com`. This is exactly the extra context the lower bar for annotated tools rewards.

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 filters are front-loaded, but the sentence 'no review queue hides a record; quality is the order, never visibility' is promotional filler that does not help an agent invoke the tool. The hosting/forwarding sentence is useful but the prose is longer than the actionable content requires.

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 tool with no output schema, the description supplies merge semantics, provenance fields, boolean logic, and caching. Return-shape detail is thin (only that rows carry a key and license), and pagination is delegated to the schema's `_links.next`, leaving minor gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond it by stating the cross-parameter logic — 'Values inside one parameter are OR'd, different parameters are AND'd' — which the per-parameter schema descriptions do not spell out.

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

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

Opens with a specific verb and resource ('Find A2A agents') and immediately defines the entity ('agents that publish an AgentCard') plus the full set of filter dimensions. It also distinguishes itself from the sibling a2a_agent by noting each row 'carries the key for a2a_agent', making the search-vs-fetch split clear without opening either 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?

Routing cues are present: rows carry the key for a2a_agent, and `/api/a2a/facets` is named as the place to enumerate tag and protocol values. It does not state explicit when-not-to-use conditions or an alternative search tool, so it stops short of full 5-level 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 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 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real behavioral value: it never contacts the address, results come from weekly measurements and cached domain data, and caching lasts 5 minutes. That is the kind of safety/performance 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?

Purpose is front-loaded, but the description is dense and partly redundant — "Never visits the address" is immediately re-stated as "The answer never contacts that address." Portuguese output keys (`sinais_do_endereco`, `registros`, `mesmo_host`, `dominio`) are introduced without translation, adding parsing load.

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 and does describe the returned structure (address signals, catalog listings with `exato` flag, `mesmo_host` count, domain facts, `no_catalogo`/`registrar` fallback). A little more on the meaning of each signal would make it fully complete.

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

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

Schema coverage is 100%, so both parameters are already documented. "Send the endpoint URL" restates the required param and adds nothing on `retry_key` beyond what the schema says, so the baseline 3 applies.

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

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

States a specific verb+resource: checks a remote MCP server address before installation, aggregating address signals, catalog listings and domain facts. Clear and distinct from the listing-oriented siblings, though it never names an alternative tool to disambiguate further.

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?

"Before installing a remote MCP server, check its address" gives an explicit trigger condition, and the no-catalog case tells the agent what to do next (submit via `registrar`). No sibling alternative is named, so it stops short of a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds genuine behavioral detail: risco-rated servers route to deniedMcpServers, expired or unchecked items are excluded, and the URL/?* wildcard semantics for route matching. That is more than the 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 the core output (managed settings), followed by supporting clauses about wildcard matching, exclusion rules, and the `comandos` output. Dense but each sentence carries output-shape information; no obvious filler.

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

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

With no parameters and no output schema, the description must explain the returned structure, and it does: managed_settings, allowManagedMcpServersOnly, deniedMcpServers routing, and comandos. An agent knows what it will get and why items are included or excluded.

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 parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% with no params to document.

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 the resource clearly: it produces the watch list rendered as Claude Code managed settings (allowedMcpServers/deniedMcpServers) plus `claude mcp add` commands. The action verb is implied rather than stated ('The watch list as...'), and it does not differentiate itself from siblings like list_watched_tools, but an agent can grasp what it emits.

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 explicit when-to-use framing, prerequisites, or named alternatives. It references `docs` and describes output fields, but never says when this tool should be chosen over list_watched_tools or similar siblings.

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

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

Annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) already declare the write and non-destructive profile, so the description is not carrying the safety burden. It goes further by disclosing a rate limit with queue semantics — 'One message every 10 seconds per network: one that arrives sooner waits its turn and then goes out — no error' — which is genuinely actionable, plus the delivery path ('reaches the team by e-mail, with `email` as the reply address'). It does not say whether submissions are acknowledged or deduplicated.

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

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

Three sentences, front-loaded with the purpose, and each sentence contributes something (intent routing, rate limiting, delivery). The middle sentence ('One route for a question and for a sponsorship, partnership or ad proposal (`tipo`, with the placements of `GET /api/partners`)') is syntactically tangled and forces a re-read, which costs it a point.

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 16-parameter tool with 7 enums and no output schema, the description covers the transport mechanics well but not the form itself. It never explains the branching structure implied by `tipo` (which fields apply to a question vs. each proposal kind), nor the seven undocumented parameters. Adequate, but an agent filling this out is left guessing about roughly half the fields.

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

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

Schema description coverage is only 56% across 16 parameters, several of which (`fuso`, `pais`, `prazo`, `formato`, `projeto`, `horarios`, `pagamento`) are documented nowhere. The description does add real value for two fields, linking `espaco` to placement ids from `GET /api/partners` and `email` to the reply address, but it leaves the majority of under-documented parameters unexplained, so it neither fully compensates nor is redundant with the schema.

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

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

The description states a specific verb and target: 'Write to the people behind the product', and enumerates the two supported intents (a question, or a sponsorship/partnership/advertising proposal). That is enough for an agent to know the tool submits a contact message. It stops short of naming the resource formally (a contact/lead submission endpoint) and reads a little colloquially, but the purpose 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?

It gives clear context for when to reach for this tool — 'One route for a question and for a sponsorship, partnership or ad proposal' — and ties the proposal branch to `tipo` and `GET /api/partners` placements. There are no explicit exclusions or named alternatives, but the sibling list contains no competing contact/submission tool, so the routing guidance present is sufficient.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write. The description adds real value beyond them: a concrete rate limit (20 new guests per network per hour) and cookie-based reuse behavior (an existing browser gets its guest from the `mr_guest` cookie). It never explains the failure mode when the cap is hit, which keeps 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, but the opening fragment "Creates a guest mr_…" is clipped and reads as broken text rather than a clean front-load. The rate limit and cookie behavior are the highest-value parts and they land after the garbled lead.

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

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

There is no output schema, so the description bears some burden for describing what comes back; it only hints at persistence via the `mr_guest` cookie and never says what the created guest object contains or what happens on rate-limit failure. Adequate for a zero-param tool, but not fully self-contained.

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 parameters, so the schema carries everything and the baseline is 4. The description's "Asks for no e-mail" helpfully reinforces that this call takes no arguments, which matches 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 ("Creates") and resource ("guest"), and the rest of the sentence clarifies scope. Sibling tools are all listing/feed/index oriented, so no guest-related alternative exists to disambiguate against, but the operation is unmistakable. The truncated "mr_…" fragment is noise but doesn't obscure the purpose.

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" implicitly tells the agent no input is required, and the rate-limit line implies this is a lightweight anonymous identity. However, there is no explicit when-to-use statement, no prerequisite, and no named alternative, so usage is 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 only declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description goes well beyond that by disclosing the quota regime, that automatic review approves low-risk MCP listings while uncertain cases wait for a human, that unauthenticated submission is allowed, and the specific failure modes (400 invalid body, 429 exhausted quota). That is exactly the extra behavioral context the 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?

The purpose is front-loaded and the status-polling instruction is useful, but the quota rule is stated twice almost verbatim ('Limit: one submission a day and three in the queue per owner' versus 'Each owner can submit once a day and keep up to three submissions in the queue'), which is pure redundancy in an otherwise short description.

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

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

There is no output schema, and the description covers the full lifecycle (submit, automatic or human review, poll `status_api`), quotas and error codes, so an agent can act without more. The one gap is that it never says the submission response yields the `:id` used in the status path, forcing the agent to infer where that identifier comes from.

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 schema documents `url`, `kind`, `body`, `name`, `tagline` and `category` thoroughly. The description adds only the 'For a skill, provide its SKILL.md URL' hint, which largely restates the schema's `url` text, so this sits at the baseline for a fully documented 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 states a specific verb and resource ('Submit an MCP server, skill or plugin for review') and enumerates the accepted kinds, so an agent immediately knows this registers a new listing for review. The review-and-decision framing further distinguishes it from read-side siblings like get_listing or list_listings.

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

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

It gives concrete operating context: one submission per day, three queued per owner, no account required, and instructs the agent to poll `status_api` (with the exact path and 'no credential') to learn the outcome. What is missing is explicit routing versus the overlapping `submit_okf` sibling, which also appears as a `kind` value here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral detail beyond that: ordering by recency without `q` vs relevance with `q`, keyset vs offset paging, and an ownership/attribution note ('the feeds belong to whoever publishes them'). This is meaningful context the annotations do not 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?

The lead question is well front-loaded, but the body is long and mixes paging mechanics, filter semantics, and licensing asides. Several clauses reference non-existent parameters, so the length is not fully earned.

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?

No output schema, so the description must carry return-value burden, and it partly does (ordering, cursor vs offset). However, the mismatch between described filter/paging parameters and the actual two-parameter schema leaves the agent unsure what it can actually pass.

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% for the two real parameters (dominio, retry_key), so the description owes little. Worse, it describes a rich set of parameters (`q`, format, language, availability, `next_cursor`, `next`, `offset`) that do not exist in the input schema, which is misleading rather than additive.

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 (find feeds) and frames the real question ('Does this site publish a feed?'), scoping it to a domain. It is clear what the tool returns, though it never names the obvious sibling (feed_search) to distinguish itself.

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 some context ('the question a reader or an agent actually asks') and explains paging/ordering behavior, but never states when to use this versus feed_search or feed_posts. Usage is implied rather than explicit, and the filter parameters it describes are not usable per the schema.

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 read-only, idempotent, non-destructive, but the description adds material context beyond them: it reads from a stored copy captured at feed-read time, never fetches the site, the HTML is sanitized through an allowlist with script/style/iframe/event handlers dropped along with their content, and it returns 404 when feed or position is unknown.

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

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

Front-loaded with the core purpose and uses inline code markers to bind field names to concepts, which aids scanning. It is dense and slightly redundant (the script-safety point is made twice via the allowlist detail and 'Neither can carry script'), but every sentence still contributes 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 so fully: it names both body fields, the original link, the sanitization guarantee, and the 404 failure mode. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, setting the baseline at 3. The description only adds the origin of `ord` (it comes from feed_posts, 0 is newest) and says nothing about `retry_key`, so it does not meaningfully exceed 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 ('Read one post whole') and enumerates exactly what is returned: the Markdown body (`conteudo`), the safe HTML body (`conteudo_html`), and the original link. It also distinguishes itself from feed_posts by noting that `ord` comes from that sibling, so an agent can route correctly without opening either 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 clear context: you obtain `ord` from feed_posts and 0 is the newest, which tells the agent the prerequisite call. It does not explicitly compare against feed_search/feed_find or state when-not-to-use, but the sequencing guidance is strong enough that usage is clear.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description layers on substantial extra context: capped at 40 posts, publication ordering, body excluded, this is our cached copy read on our own schedule rather than the live feed, `lido_em` records read time, and it returns an empty list when the feed has never been read.

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 informative, but noticeably redundant: 'never a URL' and 'takes an id from this index' are each stated twice, and the body exclusion is repeated. Trimming those would tighten it without losing meaning.

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

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

With no output schema, the description carries the full burden and does so: it lists the returned fields, the 40-post cap, ordering, and the empty-list case, so an agent knows exactly what to expect from a call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance beyond the schema: the id must come from this index and must never be a URL, which is a common misuse it pre-empts.

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 (list the posts of one feed) and enumerates the returned fields (title, date, author, summary, categories, enclosure), explicitly excluding the body. It cleanly separates itself from feed_post (single body) and feed_find/feed_search (feed discovery).

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 instructs to find the feed first via feed_find or feed_search, and states the hard precondition that it accepts an index id, never a URL. It also names feed_post as the alternative when the body is needed.

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. The description adds substantial behavior beyond that: OR within parameters versus AND across parameters, pagination mode switching based on q, keyset vs offset, following next to walk everything, and the index/link ownership model.

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

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

The description is front-loaded with the core purpose and then proceeds to query and pagination behavior. It is dense and largely waste-free, though the first two sentences overlap slightly by both summarizing the searchable dimensions.

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 8-parameter search tool with no output schema, the description covers filtering, query combination, ordering, and pagination well. It does not describe the return shape or result fields, and the retry_key behavior is left entirely to the schema. Adequate but with clear gaps for a no-output-schema tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful query semantics beyond the schema by explaining that values within one parameter are OR'd while different parameters are AND'd, and by describing q as free text over name, description, and domain. It also references a 'year of the newest item' filter that is not clearly represented in the schema, a small mismatch.

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: search the feed index / find feeds by text and filters. It lists concrete filter dimensions such as format, audio/video, community, and availability. It does not explicitly distinguish itself from the sibling feed_find, 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?

It explains the key usage conditions: without q the order is newest-first with keyset pagination via next, while with q the order is relevance-based with offset pagination. It also states that text and filters run in the same full-text query. However, it gives no explicit when-not-to-use guidance or named 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?

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact — owners can see their own listing even when pending or hidden — which is authorization context the annotations cannot express, though it is stated tersely and without saying what non-owners receive.

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 filler, and the core resource is front-loaded. It is efficient, though the extreme terseness borders on under-specification rather than crispness.

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

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

For a two-parameter read with full schema coverage and no output schema, the description is minimally adequate. It never indicates what the returned page contains (fields, owner-only extras, error behavior for missing IDs), which leaves real gaps for an agent deciding how to consume the result.

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

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

Schema description coverage is 100%: `id` is documented as coming from `Anuncio.id` and `retry_key` is fully specified in the schema. The description contributes nothing about either parameter, 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?

"One listing's page" names the resource but uses a vague noun ("page") instead of a clear verb+resource like "retrieve a single listing." It does not distinguish this tool from near siblings such as get_listing_readme, listing_history, or listing_status, so an agent still has to infer which listing-related read it wants.

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 use this versus list_listings, get_listing_readme, or listing_status. The visibility note implies a context (pending/hidden listings) but never says when the caller should reach for this tool or what the alternative is.

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

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

Annotations already cover readOnly/idempotent/destructive safety, so the bar is lower. The description adds genuinely new behavior: the content is served from R2, it does not fetch GitHub, it inherits the listing page's visibility, and it returns 404 when nothing was stored. It stops short of describing response format or body size, but the visibility and failure semantics are useful additions.

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 gating condition is front-loaded and the sentences are short and information-dense. There is mild redundancy, since the 'call only when `readme_api` exists' rule appears early and is restated at the end, but nothing is wasted.

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

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

For a simple read-only fetch of a stored document, the description covers origin, visibility, the 404 failure case, and the gating precondition. With no output schema, it could say more about what the README payload looks like (format, size), but the operational essentials are 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 coverage is 100%, so both `id` and `retry_key` are already documented in the schema. The description adds no syntax or format details about the parameters beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific resource (the collected project README for a listing) and clarifies its origin (R2 bucket `mural-coleta`), which is more specific than the title alone. However, it does not explicitly name a sibling it replaces or contrast with `get_listing`, so routing relies on inference rather than explicit differentiation.

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 an explicit, actionable precondition: call it only when `get_listing` includes `readme_api`, and warns that a page without that field has no README and the route answers 404. This is a clear when-to-use and when-not-to-use rule tied to a sibling 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the visit-counting side effect, the 1-visit-per-owner-per-day cap, the X-Visit-Counted response header and why it exists, and the branch logic for destination selection. This is exactly the additional context structured fields cannot carry (note the mild tension with readOnlyHint=true, which the prose openly surfaces rather than hides).

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

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

Four dense sentences, each carrying a distinct fact (action, dedup rule, header semantics, routing), and the core operation is front-loaded. The dash clause 'it is how the client knows without counting twice' is slightly belabored but not 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 one-parameter redirect tool with no output schema, the description covers destination resolution, the visit side effect, and the response header an agent needs to reason about. It stops short of describing the redirect response shape or failure modes (e.g., unknown id), leaving a small 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?

Schema coverage is 100% and the single `id` parameter is fully described in the schema, so the description correctly does not need to re-explain it. It adds no syntax or format detail beyond the schema, which is the expected baseline 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?

States a specific action and target: a 302 redirect to the listing's origin, with the destination resolution spelled out (remote MCP server → repository, otherwise → /l/:id). Clearly distinct from get_listing/list_listings by the word 'hop'/redirect, but no sibling is named, so the agent must infer the contrast.

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

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

The description explains what happens mechanically but never says when to choose this over get_listing or list_listings, nor any prerequisite or exclusion. The 'use this to open/visit a listing' intent is only implied by the name, so genuine guidance is absent.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: results may be cached up to 15 minutes, reading does not refresh the record, an empty list does not mean the listing is gone, and 'stale' is defined as no push for 12 months. It stops short of describing pagination or response shape, so it is a strong but not exhaustive behavioral 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 timeline concept and ordering are front-loaded, and the sentences are dense with useful facts, but the empty-list condition is stated twice ('empty when nothing changed since the series began' and 'An empty list means no change since the series began'), which is mild redundancy in an otherwise efficient block.

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 carry the return-value burden, and it does so reasonably: it lists the possible event types, states the ordering, defines staleness, and explains the empty case. It is nearly complete for a two-parameter read tool, missing only expected shape/volume of the timeline.

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 both id (from Anuncio.id) and retry_key (retry window, ASCII limit) are already documented in the schema. The description adds no parameter-level meaning beyond reinforcing the 15-minute cache window, 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 resource (the listing's repository timeline) and a specific payload: the ordered set of change events (abandono, sumiu, renomeado, readme_mudou, manifesto_mudou), newest first. It is clearly distinguishable from siblings like get_listing or listing_status, which return current state rather than history.

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 (query when you want the change history for a listing) and it notes the listing page exposes the same list as `historico`, but it never states when to prefer this tool over get_listing or listing_status, nor any precondition such as needing an existing Anuncio.id. No explicit alternatives or exclusions are given.

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?

Far exceeds the annotations: no credentials or tool calls, re-visit 7 days after a success, second check on failure, 5-minute cache, no third-party fetches, excerpts hide sensitive values, and the review never executes commands or follows references. The full operational profile is disclosed.

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

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

The purpose is front-loaded, but the body is an undifferentiated wall of text mixing prose with an inline enum dump (dns_morto, sem_https, ...) and untranslated terms (aviso, revisao.achados, nao_remoto). Several clauses earn their place, but the structure forces the agent to parse dense signal lists inline.

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: it names what MCP results contain (server, domain, tools, measured signals), what skill findings contain (path, line, excerpt, context), and enumerates the unchecked cases. 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%, but the description still adds value: it clarifies the id's provenance (list_listings) and ties the retry_key window to the 'same read for five minutes' caching behavior. Minor addition, but real.

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 a remote MCP server or SKILL.md review before installing,' and splits the two review modes (MCP vs. skill). It is clearly distinct from get_listing/listing_status in intent, though it never names a sibling explicitly to route the agent.

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

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

Gives clear context ('before installing'), an explicit when-not ('Local MCP servers and plugins answer nao_remoto'), and tells the agent where the id comes from ('Take the id from list_listings'). No named alternative tool for adjacent tasks, so not a 5.

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

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

Beyond the readOnly/idempotent annotations it discloses that no credential is needed, that the id is unguessable, that unreviewed content is never returned, the full state lifecycle (every submission born pending, safety check, human review on risk findings), and the 60 s per-PoP cache. This is exactly the operational context an agent needs before polling.

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 state list are front-loaded well, but the text runs long and repeats the same point twice ('only the decision comes back' appears in the opening and again near the end). The lifecycle explanation earns its place, the duplication does not.

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

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

There is no output schema, so the description must carry the return contract — and it does, naming all five possible states and clarifying that no content is returned. Combined with the polling and auth guidance, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description still adds meaning: the id format (`lst_…`), that it is unguessable, and that it comes from the `id` field of the POST /api/listings response (surfaced there as `status_api`).

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 ('moderation state of a listing') and enumerates the exact return values (pending / live / low / hidden / blocked). It is clearly distinguishable from siblings like get_listing, which returns the page itself rather than the decision.

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 when-to-use ('poll it after create_listing', 'the receipt you poll after POST /api/listings') and a cadence constraint ('poll every few minutes, not every second') because answers are cached 60 s. It implicitly separates itself from get_listing by stressing that only the decision comes back, but never names the alternative 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds substantial context beyond them: reads never contact the server, results are cached five minutes, descriptions truncate at 4,000 chars and input schemas become null above 8,000, and `capacidades`/`suspeitas` are computed from current rules at read time. The only gap is that the 404 error behavior could be tied more explicitly to caller action.

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 what is returned, followed by error semantics, field normalization details and caching. Dense but each clause carries information; minor friction comes from the fragment opening and the untranslated `capacidades`/`suspeitas` field names.

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

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

There is no output schema, so the description carries the return-value burden, and it does so by enumerating the normalized manifest fields and the server instructions plus derived signals. Combined with the caching and error notes, an agent has enough to call and interpret it; deeper structural detail of the returned payload is the only omission.

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 both parameters (id and retry_key) are already documented in the schema, including the `Anuncio.id` provenance. The description adds nothing about parameter syntax or format, 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?

States a specific verb-and-resource: it returns 'the tools and instructions a remote MCP server announced at its last check', then enumerates the normalized fields. That distinguishes it from get_listing, listing_status and listing_history, which cover other listing facets. The opening fragment is slightly elliptical (the return verb is implied rather than stated), but the content 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?

Usage is strongly implied: you read this to inspect the tool manifest a server announced, and the '404 tools_not_read when the server was not read yet' note tells the agent when there is nothing to fetch. However it never states when to prefer this over siblings such as get_listing, listing_history or listing_security, and there are no explicit 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 only declare the safe-read profile (readOnly, idempotent, non-destructive); the description adds substantial beyond-annotation behavior: live-first ordering with a `low` tail, cursor semantics (`next_cursor`, keyset, no ceiling), per-listing HTML pages and sitemap shards, an FTS5/bm25 index kept in the same write transaction, and `low_count` capping at 200. This is exactly the 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?

The catalog scope is front-loaded and the sentences are dense but information-bearing, covering ordering, traversal, and query mapping without filler. It is on the long side and packs several independent facts into single sentences, but each clause earns its place for an agent that must traverse and filter correctly.

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 explaining the traversal contract (cursor, no ceiling, low_count, HTML/sitemap alternatives) an agent needs to page results. For a 16-parameter read tool this is close to complete; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so all 16 parameters are already documented in the schema; the baseline is 3. The description largely restates that parameter content (low=0, interpret=0) and its most novel semantics — next_cursor, low_count — concern return/traversal behavior rather than parameters, so it adds only marginal parameter-level meaning.

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

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

The description opens with a concrete scope — 'Public mosaic of live MCP servers, skills, plugins and OKF knowledge bundles' — which tells an agent exactly what universe of records it operates on and implicitly distinguishes it from narrower siblings like list_mcp_servers or search_bundles. It never states a verb ('list'/'search'), relying on the name and title, so the purpose is clear but not explicitly action-framed.

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 operational conditions for specific parameters (low=0 to drop the tail, interpret=0 to disable query understanding, follow `next` to walk everything), which implies when to reach for those switches. However, it never names or contrasts a sibling tool (e.g. mcp_index_search, search_bundles, get_listing) or states when NOT to use this tool, so usage is implied rather than guided.

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 and idempotent and non-destructive, so safety is covered. The description adds genuine behavioral context the annotations lack: results are filtered to kind=mcp and live, and the same resource is reachable via an alias route. It does not, however, describe pagination or result 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?

The core facts earn their place, but 'Only live kind=mcp. Only `kind=mcp` and only `live`.' restates the same constraint twice in consecutive sentences, which is wasted space in an otherwise short description.

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, 0-required-parameter list tool with annotations and a fully documented schema, the description covers scope, filtering, and route aliasing adequately. The only minor gap is leaving 'live' and 'kind=mcp' undefined, which is not essential to call the tool correctly.

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

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

Schema description coverage is 100%, so limit, cursor, search, and retry_key are already documented in the schema. The description adds nothing about parameter syntax or interaction, 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?

It states this is the MCP subregistry served from GET /v0.1/servers and that results are restricted to kind=mcp and live, which is enough to tell it apart from siblings like mcp_index_search or list_listings. The phrasing is route-centric rather than verb-centric, but the resource and scope are 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 explains that this is the route a generic MCP client reads and that /v0/servers is kept as an alias, which implies when to prefer it. However, it never states when to use this over the sibling search/index tools (mcp_index_search, list_listings), so selection guidance is 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: daily check cadence, quota-induced delays, the proxima_em/verificado_em timestamps, and e-mail delivery to the verified address with an unsubscribe link. The e-mail and unsubscribe material is only loosely tied to a listing operation, which keeps this from a 4.

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 purpose is front-loaded in the first sentence, but the remaining five sentences drift across check scheduling, skill coverage, quotas, e-mail/unsubscribe, and wallet-only owners. Several of these do not clearly serve an agent deciding whether to call this tool, so the text is longer than it needs to be without being incoherent.

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 what comes back, and it partially does so (review level, slots, plans, timestamps). However, it never clarifies the shape or grouping of the returned list, and it spends space on notification mechanics that do not complete the picture for a caller.

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 per the rubric the baseline is 4. The mention of proxima_em and verificado_em describes response fields rather than inputs, which is harmless but not 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 description names the resource (the MCP servers and skills the account watches) and enumerates the fields returned (review level, slots, plans), so an agent knows what it gets. It does not name a verb explicitly and does not differentiate itself from the watch_tool/unwatch_tool siblings, but the read-only listing intent is unmistakable.

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 watch_tool, unwatch_tool, or check_tool. The only routing-like sentence ('Wallet-only owners follow changes through the API') is oblique and reads more like an account-type caveat than guidance for selecting this tool.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavior: result ordering (newest change first), AND-combined filters, and the guarantee that with q the total is the exact match count even when the page is empty. It omits anything about the shape of a returned 'signal', but the added ordering and total semantics are substantive.

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 core scope and keeps to four short sentences with no filler. The casou=0 concept is explained twice (once parenthetically, once in full), which is mild redundancy but the rest earns its place.

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

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

With no output schema and no required parameters, the description carries the ordering, filter logic and total semantics an agent needs to query correctly, and annotations cover safety. What a 'signal' record contains is left unspecified, which is the main remaining 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?

Schema description coverage is 100%, so the per-parameter baseline is 3; the description exceeds it by explaining the cross-parameter semantics (filters AND'd) and clarifying casou=0 as the catalog-miss case rather than just repeating the enum label. It still adds nothing for retry_key or limit 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 ('Browse what independent MCP indexes measured') and scopes it to servers the catalog does not list, which distinguishes it from catalog-listing siblings like list_mcp_servers and mcp_index_signals. It does not name any sibling explicitly, so an agent must infer the boundary rather than being told.

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 use case: 'the list to look at before submitting a server' for casou=0, and states that filters are AND'd, which tells the agent how to combine them. No explicit when-not-to-use or named alternative tool is offered, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: a cap of 20 signals (one per index and record), the ordered identity rules (registry name, exact endpoint URL, GitHub owner/repo), and the explicit exclusion that a shared domain never matches. It still omits staleness/freshness of the signals beyond the retry window.

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

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

Front-loading is decent, but the opening is a pair of rhetorical questions and the identity rules are packed into dashes and asides. The content is relevant yet could be stated in fewer, tighter sentences without losing the constraints.

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

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

There is no output schema, so the description carries the return-value burden. It hints at the content (does the server answer, with which access, is the repo alive, which indexes and licenses) and the count limit, but never specifies the shape or fields of a signal, leaving the agent to guess the response structure.

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 both parameters are already documented, and the description only echoes that the id comes from list_listings. It 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 second sentence states a concrete resource and scope: independent MCP indexes' measurements about one listing of this catalog, with license attribution. The opening rhetorical questions convey the content (liveness, access level, repository health) but frame purpose as queries rather than a stated verb, leaving the action slightly 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?

It tells the agent where the id comes from ('Take the id from list_listings') and gives a matching rule for when a signal attaches to a listing. However, it never contrasts this with adjacent tools such as mcp_index_search, index_stats, get_listing, or listing_status, so the agent must infer when to choose this over them.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by explaining the 202 semantics, that verification happens on the collector and nothing is published or fetched before the key matches, the re-read-on-resubmit behavior, and hard rate limits of 100 URLs per request and 200 per host per UTC day. These are exactly the async/rate-limit facts an agent cannot infer from structured fields.

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

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

Front-loaded and information-dense, but the 202/key-check point is made twice and in slightly inconsistent wording ('the key is checked by the collector before anything is read' vs 'We answer 202: the key has not been checked yet'). That redundancy and ambiguity cost space in an otherwise tight paragraph.

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 burden itself and does so by explaining the 202 response and the collector-side verification flow. Combined with rate limits, host/key ownership rules and the /api/ping pointer, an agent has what it needs to call this correctly, though the exact success/failure signals beyond 202 are left implicit.

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, but the description adds real meaning on top: key as a proof-of-ownership artifact, host as the bundle owner, and keyLocation constrained to the same host. The rate limit and resubmit semantics also attach concrete behavior to urlList. It does not, however, add syntax detail 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+resource: 'Submits OKF bundles from a host you control', and immediately frames the operation as an IndexNow submission. It is clearly distinguishable in nature from read-type siblings like get_bundle and search_bundles, though it never names a sibling explicitly. The one weak spot is that 'OKF bundle' is jargon the description only partially unpacks.

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

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

Gives concrete operating context: prove ownership via a key file, put it at https://<host>/<key>.txt or point keyLocation at the same host, then send URLs. It even defines re-submission semantics ('Re-sending a URL is how you say the bundle changed'). It stops short of stating when NOT to use this versus get_bundle/search_bundles, so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral value with 'its slot becomes free', disclosing a resource/consequence that annotations do not express, but it omits auth requirements, reversibility, and what the response returns.

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 the action front-loaded and the consequence trailing; no filler, no redundancy. Nothing here could be removed without losing 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 trivial one-parameter mutation whose annotations cover destructiveness and idempotency, the description is close to sufficient, and no output schema means return values need not be explained. However, the noun drift across name ('tool'), description ('server'), and schema ('Listing ID') leaves the target object ambiguous.

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

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

Schema coverage is 100% and the single 'id' field is fully documented as a Listing ID, so baseline 3 applies. The description adds no parameter detail of its own and its noun ('server') differs from the schema's 'Listing ID', which adds mild ambiguity rather than clarity.

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 ('stop watching a server') plus the consequence ('its slot becomes free'), which is enough to separate it from watch_tool and the various list_* siblings. It stops short of 5 because it never explicitly names the inverse sibling or scopes what kind of server/listing is being unwatched.

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 description only asserts the action. An agent must infer that this is appropriate when it no longer wants to watch something, and nothing warns about side effects like losing a slot you may need later.

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

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

The description is otherwise unusually rich (daily schedule, source quota, account e-mail notifications, 30-day non-renewing slots, Claude Code allowlist exclusion), but it explicitly claims 'Watching again is a no-op,' i.e., repeated identical calls produce no further effect, while the annotations declare idempotentHint=false. That is a direct contradiction of a declared annotation, which the rubric scores as 1.

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 front-loaded (core action first, then constraints) and compact overall. However, several compressed fragments such as 'account e-mail for changes' and 'Skills cover text and review signals, not execution' read as telegraphic rather than cleanly structured, keeping it just below top marks.

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

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

For a one-parameter subscription tool with no output schema, the description covers the operational facts an agent needs: prerequisites, schedules, quota, expiry, and allowlist behavior. It says nothing about what a successful watch returns or how to manage the resulting subscription, but that gap is minor given the sibling tools available.

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%: the single listing_id parameter is fully documented in the schema (format `mcp_…`/`skl_…`, sourced from `/api/listings`). The description adds no additional syntax, constraints, or examples beyond that, 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 opening sentence names a concrete action (watch) and its two supported resources (a remote MCP server or a supported SKILL.md), so the agent immediately knows what the tool operates on. It does not explicitly differentiate itself from siblings such as unwatch_tool or list_watched_tools, but the verb is distinct enough to disambiguate.

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 selection conditions: 'Choose a live remote MCP or a skill with a supported public raw.githubusercontent.com SKILL.md, after skill collection is enabled,' plus schedule/quota context. It stops short of naming alternatives (e.g., unwatch_tool) or stating explicit when-not-to-use cases, so it is context-rich but not fully routing.

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