Agentalog — Agent Auto Log

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds value beyond that: a 60-second cache window, the fact that it is a 'MAT catalog read, like the list', and that retry_key returns the same read for five minutes. It does not cover auth or error behavior.

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 dense, but the second sentence re-enumerates nearly everything the first sentence already listed ('every skill', 'capabilities', protocol version, documentation), which is genuine redundancy rather than added value. The incremental detail (icon URLs, first-seen date) is buried inside the repetition.

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 describe the payload (skills, capabilities, protocol version, docs/icon URLs, registries with licenses, first-seen date). It is complete enough to call correctly, though the duplicated enumeration slightly muddies what is actually returned.

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

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

Schema coverage is 100%, and the schema already says chave is the 'key from a2a_agent_search' and documents retry_key's length and five-minute reuse. The description largely restates the schema's key provenance, so 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 ('Read one A2A agent') and immediately names the returned fields, so it is clearly distinguishable from the sibling list tool a2a_agent_search. An agent knows this is a single-item detail read without opening any schema.

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

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

'Take the key from a2a_agent_search' explicitly routes the agent to the prerequisite tool and names the source of the required parameter. There is no explicit when-not or exclusion, but the single-item vs list split with the sibling 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?

With readOnly/idempotent/non-destructive already declared by annotations, the description still adds real behavior: 60-second caching, retry_key dedup window, provenance from public registries with no review queue, one merged row per agent with `sources` and `credits` licenses, and that the call is forwarded to `https://api.agentalog.com`. It does not describe rate limits or error behavior, keeping it below 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?

The purpose is front-loaded, but the marketing flourish ('served as it comes — no review queue hides a record; quality is the order, never visibility') and the host-forwarding sentence consume space without helping the agent select or call the tool. Useful content and flavor text are interleaved rather than cleanly separated.

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, no-required, no-output-schema search tool, the description covers return shape (one row per agent, sources, credits, key for a2a_agent), merge semantics and pagination pointers, which is what an agent needs to act. Only minor gaps remain, such as ordering of results.

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 parameter baseline is 3; the description goes beyond it by stating the cross-parameter combination rule ('Values inside one parameter are OR'd, different parameters are AND'd'), which the schema does not express, plus the shape of each returned row.

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 (find) and resource (A2A agents, defined as agents publishing an AgentCard) plus the filter axes it accepts. It also distinguishes itself from the sibling a2a_agent by noting 'Each row carries the key for a2a_agent', so an agent understands this is the search step of a two-step flow 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 practical invocation context: query tag/publisher/protocol values via `/api/a2a/facets`, and 'Prefer `_links.next`' for pagination; the OR-within / AND-across rule tells the agent how to combine filters. It never states when NOT to use it versus a sibling like a2a_agent, so it stops short of full when/when-not guidance.

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

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

Annotations already declare 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 the read-only/idempotent/non-destructive profile, but the description adds substantial behavioral context beyond them: it emphasizes twice that the address is never contacted and results come from prior weekly visits, describes the contents of each returned group, and discloses 5-minute caching tied to the optional retry_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 opening is well front-loaded, but the no-contact guarantee is stated twice ('Never visits the address' and 'The answer never contacts that address'), and the response-field walkthrough is dense back-to-back prose. Roughly a third of the text is redundant with itself rather than with structured data.

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 lookup tool with no output schema, the description does the heavy lifting of explaining the shape of the response (signals, records with exato/same_host, domain facts) and the no-contact guarantee. It omits error behavior for malformed URLs or non-endpoint input, which is a minor gap given the tool's simplicity.

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 in the schema; the description restates 'send the endpoint URL' without adding format or constraint details beyond the schema's 'without credentials'. The retry_key caching tie-in is the only marginal addition, so 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 ('check its address' before installing a remote MCP server) and enumerates the three data groups it returns: address_signals, records, domain. An agent can distinguish this from siblings like listing_security or mcp_index_signals, which target catalog listings rather than an arbitrary endpoint URL.

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

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

Gives clear triggering context ('before installing a remote MCP server') and a fallback path: an address outside the catalog returns no_catalogo: false, and the 'register' field tells the agent to submit it for review. It does not explicitly name competing tools (e.g., listing_security) or state when this check is unnecessary.

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 behavior beyond that: risk-rated servers are routed to deniedMcpServers, expired/unchecked items are excluded, and the `?*` pattern permits query parameters. It stops short of describing pagination or return shape, so a 3-4 is warranted.

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 dense but front-loaded with what it produces, then breaks out the key output fields and inclusion rules in short sentences. Nearly every sentence carries distinct information, though the flow is somewhat telegraphic.

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 input parameters and no output schema, the description carries the burden of explaining the return structure, and it does so by naming managed_settings, allowManagedMcpServersOnly, and commands plus the inclusion rules. The dangling `docs` reference is a minor gap but overall it is complete enough for a zero-input export 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?

The tool takes zero parameters, so per the baseline rule a 4 applies. The description's discussion of output fields (managed_settings, allowManagedMcpServersOnly, commands) is output semantics rather than parameter meaning and does not change this baseline.

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 makes clear this produces Claude Code managed settings (allowedMcpServers/deniedMcpServers) and claude mcp add commands from the watch list. The transformation and its outputs are identifiable, though it is phrased as a noun phrase rather than a clean verb+resource and never explicitly contrasts with siblings like list_watched_tools.

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

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

It implies the use case (feeding a Claude Code managed settings source, per `docs`) and notes that allowManagedMcpServersOnly restricts user-added servers, which is contextual guidance. However there is no explicit when-to-use/when-not or comparison against the other watch-list tools, 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): it discloses a 10-second-per-network rate limit with queueing rather than erroring, email delivery with `email` as reply address, the multipart/form-data voice path, and explicit size caps (32 KiB JSON, 2 MB audio, 2-minute recording). This is exactly the operational context annotations cannot carry.

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

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

Purpose and rate limit are front-loaded, and most sentences carry information, but the phrasing is awkward and roundabout ('one that arrives sooner waits its turn and then goes out — no error'), and the multipart details are buried at the end rather than scoped to the voice use case.

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 18-parameter tool with no output schema, the description covers rate limits, delivery channel, reply routing, enum-driven modes, and the voice upload path. It omits only minor details such as what a successful submission returns, which is low-stakes since no output schema is defined.

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 94%, so the baseline is 3, but the description adds real value the schema cannot: the multipart/form-data structure for voice (`dados` carrying this JSON plus an `audio` file) and that audio may replace `message`. These transport-level parameters do not appear as schema properties, so the description is doing necessary work.

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

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

The description opens with a specific verb+resource: 'Write to the people behind the product', and enumerates the accepted intents (question, sponsorship/partnership/ad proposal). It does not name any sibling, but no sibling tool overlaps with 'contact', so differentiation is implicit and 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 implies when to use the tool ('One route for a question and for a sponsorship, partnership or ad proposal') and even maps `type` to the placements endpoint, but gives no when-not guidance and names no alternative route. Usage is inferable rather than stated.

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

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

Annotations already 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 cover read-only/idempotent/non-destructive safety. The description adds some operational context (results ordered by recency in the index, paging via keyset vs offset), but these mechanics reference query parameters that do not exist in the schema, so the disclosure is only partially useful. The closing note ('we index and link; the feeds belong to whoever publishes them') is a disclaimer rather than behavior.

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 paragraph spends most of its length on query/ordering/paging mechanics tied to nonexistent parameters and includes filler ('the question a reader or an agent actually asks'). Reasonably sized but not every sentence earns its place.

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

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

For a two-parameter, 100%-covered, no-output-schema tool, the description needs little more than scope plus the domain semantics. Instead it overreaches into a filter/paging model that does not exist in the tool, leaving the agent with an inaccurate mental model and no guidance on alternatives.

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

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

Schema coverage is 100% and both real parameters (dominio, retry_key) are documented in the schema, so the baseline would be 3. However, the description describes a set of filter/search parameters (q, text, format, language, availability, next_cursor, offset) that are entirely absent from the schema, which is actively misleading rather than merely redundant.

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 clear verb+resource: finding every feed known for a domain, framed as answering whether a site publishes a feed. This domain-scoped discovery purpose is distinguishable from siblings like feed_search and feed_posts, though the name of an alternative is never used to sharpen 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?

Gives implied context ('the question a reader or an agent actually asks') and describes ordering behavior, but never states when to choose this over feed_search or feed_posts, nor any prerequisites or exclusions. Usage is inferable 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/idempotent/non-destructive, and the description adds substantial context beyond them: content comes from the stored copy, a request never fetches the site, the HTML is passed through an allowlist (script/style/iframe/event handlers dropped with contents), and neither body can carry script. That is exactly the sanitization and freshness behavior an agent needs.

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

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

Front-loaded with the payoff (both bodies plus the link) before the sanitization detail. Slightly redundant — the allowlist sentence and the closing 'Neither can carry script' make the same point twice — but every sentence is load-bearing and readable.

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: field names, formats, and the 404 error condition are all spelled out. Nothing needed to call this three-parameter read tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents `id`, `ord`, and `retry_key`; the description's restatement that `ord` is 0-based-newest duplicates the schema. It adds no format or edge-case detail for `id` or `retry_key`, so baseline 3 applies.

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

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

States a specific verb and resource ('Read one post whole') and immediately enumerates what comes back: Markdown body, safe-HTML body, and the original link. It also positions itself against the sibling feed_posts by explaining that `ord` originates there, so an agent can tell the two apart without opening schemas.

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?

Explicit workflow context: '`ord` comes from feed_posts; 0 is the newest,' and the failure mode '404 when the feed or the position is unknown.' It does not name when *not* to use this (e.g., vs feed_search for finding posts), so it stops short of full alternative routing.

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

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

Annotations already cover the read-only idempotent safety profile, and the description still adds substantial behavior: it is a cached copy read on our own schedule rather than live data, capped at 40 posts in publish order, excludes the body, and includes read_at as the read timestamp. This is the kind of 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?

The opening is strong and front-loaded, but the description repeats itself: 'never a URL' appears twice, 'WITHOUT the body' twice, and the 'our copy / not the live feed' idea is stated in two overlapping sentences. Trimming the repetition would preserve all the signal.

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 describe returns, and it does: the fields returned, the 40-item cap, ordering, the read_at timestamp, and the empty-list case. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint beyond the schema: the id must come from this index and never be a URL, which tells the agent how to source the value. It adds nothing for retry_key's semantics beyond what the schema already documents.

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 ('posts of one feed') plus the scope ('as our queue read them') and enumerates the returned fields. It clearly separates itself from feed_post (single body) and feed_find/feed_search (resolution), so an agent can pick it without opening the schema.

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

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

Explicit routing: 'Find the feed first (feed_find or feed_search)' and an explicit precondition that it 'takes an id from this index, never a URL.' It further states when-not: it is not the live feed and not a proxy, and returns an empty list when the feed has not been read. Alternatives and exclusions are both named.

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 still adds real behavioral context: keyset vs offset paging, 'follow next to walk everything', and a provenance disclaimer ('we index and link; the feeds belong to whoever publishes them') that tells the agent results are third-party 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?

Front-loaded with the action and filter set, then dense operational detail; every sentence carries information. Slightly overloaded – the filter enumeration at the top partly duplicates the same axes later in the sentence about q/ordering – but no padding.

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 eight-parameter, optional-only search with no output schema, the description covers ordering, both paging modes, cursor-following, retry semantics being delegated to the schema, and data provenance. Gaps: it never sketches the result shape, and it references a year filter not present in the schema, which could send an agent looking for a parameter that does not exist.

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 each parameter and the baseline is 3; the OR/AND combination rule and the filter-to-parameter mapping add marginal value. However, the description names a 'year of the newest item' filter and a 'namespace' filter that do not map cleanly (or at all) onto the eight declared parameters, which muddies rather than clarifies 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?

States a specific verb+resource ('Search the feed index') and enumerates the filter axes (format, audio/video, community, namespace, recency). It never distinguishes itself from the near-name sibling feed_find, so an agent cannot tell the two apart from the text alone, but the core 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?

Gives concrete invocation rules: filters and text resolve in the same full-text query, values within one parameter are OR'd while different parameters are AND'd, and the paging/ordering model flips based on whether `q` is supplied (keyset/recent vs offset/relevance). What it does not supply is an alternative-tool call-to-action (e.g., use feed_find instead when ...), which keeps it out of the top band.

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

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

Annotations already 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 readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: results may be cached up to 15 minutes, and reading the endpoint does not refresh the record. It also pre-empts a likely misinterpretation by explaining that an empty list does not mean the listing is gone.

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 timeline concept, but it repeats itself: emptiness is explained twice ('empty when nothing changed since the series began' and again 'An empty list means no change...') and the 12-month stale rule is stated both inline in the event list and again as a standalone sentence. Roughly a third of the text is redundant.

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 the return value, and it does: newest-first ordering, event type vocabulary, and the empty case. Caching and non-refresh semantics round it out; only explicit alternative-tool routing is absent.

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 both parameters (id, retry_key) are documented in-schema with their source and the five-minute idempotency window. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource: a timeline of a listing's repository events, newest first, with the event vocabulary enumerated (abandono, sumiu, renomeado, readme_mudou, manifesto_mudou). An agent can tell it apart from get_listing or listing_status, though the distinction is inferred rather than stated.

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?

Provides interpretive context (empty list meaning, 15-minute cache, what 'stale' means) but never says when to reach for this versus get_listing, listing_status, or listing_security. Usage is implied by the resource described rather than routed explicitly.

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

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

With readOnlyHint/idempotentHint already declaring the safety profile, the description adds substantial context beyond annotations: no credentials or tool calls, `initialize`+`tools/list` probing, 7-day recheck after success, second check on failure, 5-minute cache, daily cap and shared GitHub governor, and `not_remote` for local servers/plugins.

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 and the telegraphic style is efficient, but the description is very long and contains redundancy — 'no command execution or referenced-script review' is restated later as 'The review does not run commands or follow references', and the signal enum is dumped 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 carries the return-value burden and does so thoroughly: it names the MCP signal codes, describes `revisao.achados` fields (path, line, excerpt, context), the `tipo: skill` marker, and the explicit 'unchecked'/'not_remote' outcomes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it tells the agent where the required `id` comes from ('Take the id from list_listings') and ties the 5-minute cache to the read semantics of `retry_key`, both of which go beyond the schema text.

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

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

States a specific verb and resource — 'Read a remote MCP server or SKILL.md review' — and splits it into the two distinct result shapes (MCP signals vs. static skill findings). This clearly distinguishes it from siblings like get_listing, listing_status, and list_listings without opening any schema.

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

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

Gives the trigger ('before installing'), routes the agent to the id source ('Take the id from list_listings'), and points to 'the limits in aviso'. It is clear context but stops short of explicitly naming an alternative tool or stating when NOT to use it, so it falls just 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?

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 safe-read profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond them: reading never contacts the server, results are cached for 5 minutes, and field-level truncation limits (4,000 chars, schema null above 8,000). This is substantive context an agent could not get from the annotations.

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

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

Front-loaded with what is returned, followed by error state, structure, provenance of capabilities/suspicions, and caching. Dense but each sentence carries distinct information; minor verbosity in the backtick-heavy manifest sentence.

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 exists, and the description compensates well by enumerating the returned fields (name, title, description, input schema, protocol annotations, capabilities, suspicions, server instructions). Complete enough for an agent to call it correctly, though it omits any note on pagination or result size beyond truncation limits.

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

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

Schema description coverage is 100%, so both id and retry_key are already documented in the schema, including the five-minute reuse semantics. The description's 'cached for 5 minutes' overlaps but adds no new syntax or format detail, 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 and scope: the tools and instructions a remote MCP server announced at its last check, normalized as a manifest. An agent can tell this is a read of a stored manifest rather than a live query, but it never explicitly names or contrasts with close siblings like check_tool or listing_security.

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

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

Usage is only implied. The '404 tools_not_read when the server was not read yet' clause tells the agent what a failure means, but there is no explicit when-to-use-this-vs-alternatives guidance, e.g. versus check_tool or get_listing.

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/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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavior beyond annotations: oldest-first ordering, 100-per-page pagination, default 30-day window, cursor semantics, and polling behavior. The trailing `email: true` clause is somewhat confusing because no such parameter exists in the schema.

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

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

The description front-loads the core purpose but repeats the 100-per-page constraint and includes a confusing unsupported `email: true` reference. It is adequately sized but not tightly structured.

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

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

For a single-parameter read operation with annotations and no output schema, the description covers the key behaviors an agent needs: default window, pagination, cursor reuse, and polling when no new changes exist. The unexplained `email: true` clause is a small 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?

Schema description coverage is 100%, and the only parameter, `depois`, is already fully documented in the schema. The description restates its meaning without adding syntax, format, or validation details beyond what the schema provides.

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

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

The description clearly identifies the resource as changes in watched tools, with ordering and pagination. However, it does not explicitly differentiate this tool from siblings such as list_watched_tools or watch_tool, leaving the agent to infer the distinction.

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

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

The description gives clear operational guidance: omit `depois` for the last 30 days, pass the previous cursor to get only new changes, and poll with the same cursor when nothing is new. It does not name alternatives or explicitly state when not to use this tool versus list_watched_tools.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses quota consumption, a daily check schedule, 30-day slot lifetime with no auto-renewal, the already_watched no-op on repeat calls, and that skills never enter the Claude Code allowlist. The repeat-call statement is scoped to an active watch, and slot expiry plus per-slot quota consumption still make repeated calls non-idempotent, so it is consistent with idempotentHint=false rather than contradicting it; failure modes (invalid ID, quota exhausted) are not covered.

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 text is dense and front-loaded: purpose first, then constraints, repeat behavior, and lifetime, with no filler sentences. The telegraphic style ('Daily schedule, subject to source quota') is slightly clipped but each clause carries information an agent needs.

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 tool with no output schema, the description supplies the lifecycle (30-day slots, no renewal), quota caveat, prerequisite (skill collection enabled), repeat-call outcome, and a cross-system consequence (allowlist exclusion) — enough to call it correctly. It omits what a successful watch returns and how quota exhaustion surfaces, which keeps it from a 5.

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

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

There is a single required parameter with 100% schema description coverage, and the schema already explains the `mcp_…`/`skl_…` listing_id format. The description only implies the target via 'remote MCP or supported SKILL.md' and adds no format or sourcing detail beyond the schema, 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 opens with a concrete verb+resource: 'Watch a remote MCP or supported SKILL.md', which is unmistakably a subscription-creation action and clearly distinct from siblings like unwatch_tool and list_watched_tools. It also sharpens scope with 'Skills cover text and review signals, not execution', so an agent knows exactly what is being watched.

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 eligibility conditions — the target must be a live remote MCP or a skill whose public raw.githubusercontent.com SKILL.md is supported, and skill collection must be enabled first. It does not explicitly contrast this tool with alternatives (e.g., get_listing, list_watched_tools) or state when watching is the wrong move, so it stops short of full when/when-not guidance.

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