grade

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

Annotations already declare readOnlyHint=false, destructiveHint=false, so the description needn't restate safety, and it instead adds genuine context: the public counter counts people, not clicks, so repeated calls do not inflate it. However, this is in tension with idempotentHint=false and leaves the agent unsure whether repeating creates a duplicate favorite record or errors. It also omits auth requirements and 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?

Two short sentences: the purpose is front-loaded and no words are wasted. The second sentence is terse to the point of being cryptic in isolation (what public counter?), but the definition is not padded or verbose.

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 annotations covering the safety profile and no output schema, the description is close to adequate: it states the action and the counter semantics. The remaining gap is the repeat-call behavior, which is precisely what an agent would need to resolve against idempotentHint=false, plus any auth requirement.

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% with a single required parameter, so the schema already defines channel_id and even supplies a format example. The description adds nothing about the identifier (slug vs. numeric id, case sensitivity, whether an invalid channel fails). Baseline 3 applies when the schema does the heavy lifting.

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

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

The first sentence, "Favorita um canal," states a specific verb and resource, and the channel_id example (`GloboNews.br`) makes clear it operates on a single channel. It does not explicitly contrast itself with remove_favorite or list_favorites, so it falls short of 5. The Portuguese-only phrasing amid otherwise English metadata is a minor clarity cost.

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 call this versus siblings like remove_favorite or list_favorites, nor prerequisites such as authentication or a valid existing channel. The second sentence is an anti-abuse note (don't spam the endpoint), not a when-to-use rule. Usage is only implied by the verb.

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

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

Annotations cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, yet the description adds real context: a hard 40-channel cap per sub-tab and the response shape (which folder/sub-tab received the channel, plus the full refreshed library). It doesn't mention permissions, but the quota and return-behavior disclosure is 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?

Four short, front-loaded sentences that lead with the action and constraint. The clause 'para a tela abrir no lugar certo' is mild UI rationale rather than operational fact, but overall it is tight.

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

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

With no output schema, the description usefully covers return behavior (destination folder/sub-tab and the already-updated library, so `GET /api/library` is unnecessary), and it states the capacity limit. Combined with annotations covering safety, an agent has enough to call it correctly, though auth/prerequisite context 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 coverage is 100%, so both parameters (group_id as the receiving sub-tab, channel_id as the catalog ID like `GloboNews.br`) are already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

The generic name/title ('add_item' / 'Add item') is rescued by 'Adiciona canal à sub-aba', which names a concrete verb (add) and resource pair (channel into a sub-tab/group). It is clear, but it never distinguishes itself from the sibling add_favorite, which is also an 'add' operation an agent could confuse it with.

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: it states the 40-channel-per-sub-tab ceiling and notes you need not re-fetch the library, but gives no explicit when-to-use vs the alternatives (add_favorite, create_group) or any prerequisite/auth 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 fully covered by structured data. The description contributes one extra behavioral fact — that the index is organized per language and exposes HTML pages — but says nothing about size, caching, or when the index is refreshed.

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

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

A single short sentence with no filler, front-loaded with the core concept ('índice da API inteira'). It is arguably too terse given how vague the return content remains, but there is no wasted text.

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

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

With no output schema, the description carries the burden of explaining the return value, and it only gestures at it ('idiomas e páginas HTML de cada um') without describing the structure an agent would receive. For a zero-parameter discovery tool the gaps are modest but real.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is nothing for the description to compensate for. Baseline of 4 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 resource and scope: a self-describing index of the entire API, broken down by language with the HTML page for each. That is more than a restatement of the name, though the phrase 'auto-descrito' leaves the actual payload content somewhat abstract. No sibling tool does the same job, so differentiation is implicitly fine.

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

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

There is no when-to-use guidance and no mention of how this relates to alternatives such as health, pricing, or the various list_* discovery tools. An agent must infer that this is a meta/discovery endpoint rather than a functional one.

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 bar is lower, yet the description still adds value: the chat-pass branch only works with a credential, and it explains the meaning and current OFF state of the `prices.abuso_24h_usd` door. That is meaningful behavioral 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?

Four compact sentences, front-loaded with the core purpose ('Preços e tetos') and then the usage rule. It is efficient, though the internal jargon ('porta de UA vazio/curl') costs some clarity for an external reader.

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

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

For a zero-param, read-only tool with no output schema, the description covers enough of the return surface (current prices, caps, credential-dependent chat-pass status, and a specific field) to invoke it meaningfully. It does not fully enumerate the response shape, but the complexity is low.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4 and there is no parameter semantics to compensate for. Nothing in the description contradicts or embellishes a parameter contract.

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 (current prices and caps) and even names a field (`prices.abuso_24h_usd`), so an agent can tell this tool returns live billing numbers. However, it never distinguishes itself from the sibling `pricing` tool, leaving a real ambiguity about which one 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?

It gives a clear directive: read the current number from here before spending a call rather than assuming the documented price. That is actionable when-to-use guidance, but it never names an alternative sibling (e.g. `pricing` or `chat_pass`) or states when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely non-obvious behaviour: the panel is empty without community reports submitted via POST /api/play-report, and it explains that `geo` distinguishes regional restriction from general failure. That is real context beyond the annotations.

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

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

The purpose and the outage-vs-block framing are front-loaded, then the return fields are enumerated compactly. It is dense but each clause carries information; only the long field-by-field enumeration makes it slightly heavier than necessary.

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

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

With no output schema, the description compensates by naming the key return paths (`geo`, `regions[]`, `latency[]`, `pra_voce`) and their meaning, and by disclosing the community-data prerequisite. It does not describe pagination or the top-level success-rate/failure-reason shape in detail, but for a single-ID read tool this is close to sufficient.

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

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

Only one parameter (`id`) and schema coverage is 100%, so the schema fully documents it. The description adds no syntax, format or ID-source detail, which puts it at the baseline 3 for a single well-documented parameter.

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+resource: 'Saúde comunitária do canal' with success rate, failure reasons and affected environments, and it articulates the diagnostic distinction ('canal fora do ar' vs 'bloqueado no seu país'). It does not, however, differentiate itself from the sibling tools `health`, `geo` or `play_reports`, which sit in the same conceptual space.

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 the framing that this separates a global outage from a country-level block, which tells the agent why it would call this. But there is no explicit when-to-use, no 'use X instead when...', and the sibling `health` is never mentioned, so routing between them is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral note — no WebSocket, i.e. a non-live fetch — but says nothing about how many messages are returned, ordering, pagination, or rate limits. With annotations carrying the safety burden, a 3 is appropriate.

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

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

A single short sentence that front-loads the resource and action with no filler. It is efficient, though the terse parenthetical is the only qualifier and adds little structure.

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 whose annotations cover the safety profile, the essentials are present. However, with no output schema, the description does not indicate what the returned messages look like or their count/ordering, and it offers no usage routing — leaving notable gaps for an agent deciding between chat_history, get_history, and chat_send.

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

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

There is a single parameter (channel_id) with 100% schema description coverage, so the schema already documents the required 'ID do canal no catálogo'. The description adds no format, source, or lookup details beyond that, matching the baseline 3 for a fully documented single parameter.

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 ('últimas mensagens da sala de um canal') and a retrieval action, so an agent can tell it fetches recent chat messages for a channel. It does not explicitly contrast itself with near siblings like get_history or chat_send, which keeps it short of a 5.

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

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

There is no when-to-use guidance and no reference to alternatives such as chat_send (posting messages), get_history (other history), or clear_history. The only hint is the parenthetical '(sem WebSocket)', which implies a polling/HTTP fetch but without saying when that is preferable.

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

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

The description adds substantial behavioral context beyond the annotations: the exact charge ($0.10/30 days), the 402-without-payment path, and the auth scope (X-Guest-Token guest vs. HTTP-only account session). However, it asserts repeated calls are effectively idempotent ('sem risco de pagar duas vezes'), which conflicts with idempotentHint=false.

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

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

It is front-loaded with the price and purpose, and every clause carries operational meaning (cost, status codes, identity, storage). It is somewhat dense and repeats 'quem fala no chat' twice, costing a little 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 0-parameter tool with no output schema and sparse annotations, the description covers pricing, charge/idempotency behavior, status codes, identity scope, and where the purchase is recorded ('direito'). Only the success response body shape is left unstated, which is acceptable given no output schema exists.

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

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

With 0 declared parameters, the baseline is 4. The description still adds meaning by identifying the implicit identity input, the X-Guest-Token header (recognized by the WebSocket 'hello') or the account session, which is not in the schema.

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

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

The description names a specific resource and scope ('Passe mensal do chat ($0.10 / 30 dias)') and the HTTP payment semantics (402 vs 200) make it clear this is a paid-pass acquisition endpoint. The verb itself is implicit rather than stated, but the resource is unambiguous and clearly separable from siblings like chat_send and chat_history.

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

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

It tells the agent when it can be called ('dá para chamar antes de escrever, sem risco de pagar duas vezes') and describes the no-guest fallback path via the account session. It gives real context for invocation, though it never names a sibling alternative or states exclusions 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 only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes well beyond that: it discloses a paywall, the exact 402/accepts[] failure mode with a retry protocol, and the identity precedence (guest token over account session). That is exactly the extra behavioral context annotations cannot carry.

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

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

Four sentences, each doing distinct work: purpose, cost model, failure/retry path, and identity. Nothing is repeated or padded, and the purpose is front-loaded before the payment mechanics.

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 non-idempotent, paid mutation with no output schema, the description covers cost, auth identity, and the 402 recovery path, which is the information an agent needs to call it successfully. It never says what a successful response contains, a minor gap that 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?

Schema description coverage is 100%, so body, author, and channel_id are already fully documented in the schema (including the max_length and stable-nickname behavior). The description adds no parameter-specific detail beyond what the schema states, so the baseline 3 applies.

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

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

The opening clause names a specific verb and resource ("Manda mensagem na sala de um canal por HTTP"), which clearly separates it from read-oriented siblings like chat_history and get_history. It stops short of naming an alternative explicitly (e.g. post_comment vs chat_send), so it lands at 4 rather than 5.

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

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

Strong operational guidance: reads are free while writes cost $0.10 per 30 days, an invalid pass yields 402 with accepts[], and the caller should pay and repeat the identical call. It also states who is speaking (X-Guest-Token guest, otherwise account session). It does not, however, contrast when to prefer this tool over post_comment or other siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description only adds the scope qualifier 'inteiro ... de uma vez' and says nothing about irreversibility, re-authentication, or what 'history' actually contains, which would be the value-add beyond the annotations.

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

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

A single short sentence with the destructive scope front-loaded and no filler. Nothing in it is redundant or padded.

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

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

For a zero-parameter, irreversible, destructive tool the description leaves real ambiguity: which history (watch history, chat history, browsing?) given that multiple siblings reference history, and no warning that the wipe cannot be undone. The annotations cover the destructive flag but not the domain ambiguity.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate or clarify beyond confirming the operation is unfiltered and total.

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 ('Limpa') and resource ('histórico inteiro do dono'), and the phrase 'de uma vez' signals a wholesale wipe rather than a partial edit. It does not explicitly contrast itself with the read-oriented siblings (get_history, chat_history), so differentiation is only 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?

The description says what happens but never when to use it, when not to, or which alternative applies. With siblings like get_history and forget_watch in the same family, an agent gets no routing guidance at all.

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 readOnly=false, idempotent=false, destructive=false, so the description carries most of the burden and does deliver: no captcha, no account, no payment, one message per 10s per network with queuing instead of an error, and delivery to the team via email with `email` as reply-to. The disclosure is real, but the rate-limit/delivery facts are restated rather than expanded, so it stops 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?

Purpose is front-loaded, but the body is heavily redundant: the 10-second rate limit is stated twice, and 'sem captcha / sem conta / sem pagamento' appears three times in slightly varied wording. Roughly half the sentences could be deleted with no loss of information.

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

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

With no output schema, the description usefully explains the observable outcome (message reaches the team by email, email used as reply-to) plus auth and rate-limit behavior for a 10-parameter write tool. Nothing an agent needs to call it correctly appears to be 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% and every field is documented, including enums and aliases. The description adds only marginal meaning (that `tipo` binds the proposal fields and that `email` becomes the reply address), so the baseline 3 for schema-complete tools is correct.

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

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

States a specific verb+resource ('Fale com quem faz o produto') and explicitly names the two intents it covers: dúvida and sponsorship/partnership/ad proposals. An agent can distinguish this contact tool from every media-oriented sibling (chat_send, post_comment, etc.) 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?

Clearly says when to use it (a question, or a sponsorship/partnership/ad proposal) and ties the proposal path to the `tipo` field and the slots of `GET /api/partners`. It does not name an alternative tool or state exclusions, but no sibling covers the same ground, so the routing guidance is adequate.

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 safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely useful behavior the annotations do not carry: the 8-folder-per-owner ceiling and the fact that the response returns the entire refreshed library, so a follow-up GET /api/library is unnecessary. It still omits failure behavior when the cap is exceeded, which holds it back from 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, front-loaded sentences with zero filler: action first, constraint second, return-behavior third. Every sentence earns its place and no restatement of the name or schema.

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

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

For a one-parameter mutation tool with no output schema, the description covers purpose, the key limit, and the return payload (full updated library), which is exactly the missing-output-schema compensation an agent needs. Only the cap-exceeded failure path is left unspecified.

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

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

Schema description coverage is 100% with a single documented parameter (name, up to 40 chars), so the schema already does the work. The description adds no syntax or format detail beyond it, making the baseline 3 correct.

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

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

"Cria tab/categoria pessoal" states a specific verb and resource, and adds the scoping detail that it is a *personal* category. It is clear what the tool does, but it does not name or differentiate itself from any sibling (e.g. create_group), so an agent must infer the distinction from the name alone.

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, and no alternative tool is named. The 8-folder cap is a constraint, but it reads as a limit rather than a selection rule, leaving the agent to infer when this tool applies.

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=false, idempotent=false, destructive=false. The description adds meaningful mutation context: a hard limit of 12 sub-tabs per folder and a response that includes the fully updated library, removing the need for a follow-up GET /api/library. It does not describe what happens when the limit is exceeded, so it is not fully complete.

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, front-loaded with the core action. The limit and response behavior are stated efficiently with no filler, and the follow-up API call guidance is directly actionable.

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 mutation with no output schema and full schema coverage, the description supplies the key operational facts: what it creates, the per-folder limit, and that the response already includes the updated library. Error handling for exceeding the limit is not covered, but the core calling context is complete.

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

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

Schema description coverage is 100%, so both parameters (category_id and name) are already documented with types and constraints. The description adds no further parameter syntax or format details beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource: creates a sub-tab inside a category. This distinguishes it from create_category, which likely creates the parent folder. However, the tool name 'create_group' and the description's term 'sub-aba' are not identical, so the naming alignment is slightly loose.

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 guidance on when to use this tool versus siblings like create_category, nor any exclusions. The intended scenario is implied by 'Cria sub-aba numa categoria,' but an agent must infer the boundary between creating a category and creating a sub-tab.

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 safety profile (not read-only, not idempotent, not destructive). The description adds real behavioral context beyond them: no email/credentials are requested, the token is the sole access credential, and losing it forfeits the library unless the account already claimed it. That is meaningful consequence disclosure. It stops short of stating rate limits, expiration, or whether repeated calls create separate guests.

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

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

Two sentences, front-loaded with the action and the returned token, followed by the operational warning. No filler. Minor friction from the abbreviated 'ipt_…' token prefix and the mixed-language phrasing.

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

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

For a no-argument creation tool with no output schema, the description covers the essential facts: what is created, that a token comes back, that the token is critical, and the claim escape hatch. Missing only edge details like whether repeated calls create new guests or any output format specifics.

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 with an empty schema, so the baseline is 4. The description correctly implies no input is required ('não pede e-mail nem nada'), consistent with the schema.

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

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

States a specific verb+resource (creates a guest) and clarifies the essential output artifact: a token prefixed 'ipt_'. It does not name or contrast with any sibling tool, so an agent gets the what but not explicit differentiation from alternatives like chat_pass or me.

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?

'Não pede e-mail nem nada' implies this is the frictionless/anonymous entry path, and it points to POST /api/auth/claim as the follow-up route. However, it never states when an agent should prefer create_guest over other available tools; the guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not burdened with the safety profile. It nonetheless adds genuinely non-obvious context: only the owner's comment can be deleted, and a 404 is deliberately returned to avoid revealing whether someone else's comment exists. That error-semantics disclosure is exactly the kind of behavior an agent needs when interpreting a failed call.

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

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

Two sentences, zero filler: the purpose and ownership scope come first, the non-obvious 404 rationale second. 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 one-parameter destructive tool with full annotation coverage and no output schema, the description supplies the key surprising behavior (ownership + intentional 404). It does not discuss irreversibility or response content, but with destructiveHint set and no output schema, those are minor omissions.

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 parameter 'id' already documents its origin (Comentario.id), so the schema carries the semantics. The description adds nothing about the parameter beyond what the schema states, 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 verb (Apaga) and resource (um comentário) plus a scope qualifier (do próprio dono), which lets an agent separate it from post_comment (which adds) and list_comments (which lists) 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?

The ownership restriction implies when it is applicable, but there is no explicit when-to-use statement, no named alternative, and no prerequisites or exclusions. Usage is inferable but not 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds that it removes a channel from the owner's history, clarifying the scope of destruction, but does not detail reversibility, permissions, or side effects beyond that. This is a modest addition beyond annotations.

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

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

A single sentence that is front-loaded and wastes no words. Perfectly concise for such a simple 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 the simple operation, one parameter, and the presence of annotations, the description is largely complete. It clearly states the action, and the parameter schema provides necessary detail. The lack of usage guidelines is a minor gap, but not critical for this tool.

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

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

Schema description coverage is 100%, and the single parameter channel_id is fully documented in the schema with an example. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

States a specific verb (tira/removes) and resource (canal/channel) and scope (histórico do dono/owner's history), clearly indicating the action. It does not explicitly differentiate from siblings like clear_history, but the name forget_watch and the specific channel parameter make the purpose distinguishable.

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

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

No explicit guidance on when to use this tool versus alternatives such as clear_history or remove_favorite is provided. The description implies usage for removing a single channel from history, which is adequate but leaves the agent to infer context.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: a fallback to BR with `source: "fallback"` when no edge detection occurs, plus what `detected` reports. This goes beyond the annotations by disclosing return-field semantics, though other possible `source` values remain unexplained.

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

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

Two compact sentences, front-loaded with the core purpose before the fallback detail. Nothing is wasted, though the brevity borders on cryptic for a reader unfamiliar with the domain's `source`/`detected` vocabulary.

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 full burden of explaining returns, and it only partially does so: it names `source` and `detected` but only one enum value ('fallback') and omits the rest of the response shape. Adequate for a trivial zero-arg read, but incomplete.

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 sets the baseline at 4. There is no argument syntax or filtering to document, so nothing is missing on this dimension.

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

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

The description states the resource concretely: suggested country and language for the caller. The vague name 'geo' is rescued by 'País e idioma sugeridos', but the description never distinguishes this from siblings like list_countries or list_languages, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_countries/list_languages. Usage is only implied by the phrase 'para quem está chamando' (for the caller), leaving the agent to infer the trigger.

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 does add one genuinely useful non-obvious trait: the returned streams are already rewritten to point at "o nosso hop" (our proxy/CDN hop), which an agent would not learn from the schema or annotations. It stops there, saying nothing about what else the record includes.

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

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

A single short sentence with no filler and the resource front-loaded. It is efficient, though "ficha completa" is vague enough that the brevity shades into under-specification.

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 burden of explaining what is returned — yet "ficha completa" never enumerates or characterizes the fields. For a single-record fetch with no output schema and no return-value documentation, an agent cannot anticipate the payload.

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 documented in-schema with an example (`GloboNews.br`). The description adds no additional meaning about the identifier, 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?

"Ficha completa de um canal" names the resource (a channel) and implies a full-record retrieval, so the basic intent is inferable. However, it never states a clear verb or what the record contains, and it does nothing to distinguish itself from siblings like get_channel_guide, channel_health, legacy_stream, or search_channels.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of any alternative tool. An agent must guess whether this or get_channel_guide/channel_health is the right call for channel metadata.

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/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the guide=1 availability gate, the two-day staleness window, and the advice to check the response date. It doesn't describe pagination or error behavior, keeping it below 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 dense sentences that front-load the core purpose and then layer constraints and field hints, with little waste. Slightly terse and mixes prose with backticked field names, but it is well 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?

With no output schema, the description steps in usefully by naming the returned field `guide_now` and warning to check the response date. Combined with the availability and validity rules, an agent has enough to call and interpret the result, though return structure is only partially sketched.

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

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

There is a single parameter with 100% schema coverage ('ID do canal no catálogo'), so the schema already carries the semantics. The description adds no further meaning about the `id` value, making the baseline 3 appropriate.

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

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

States a specific resource — today's programming for a channel — and enumerates exactly what it contains (now, next, and the full list). This clearly separates it from the generic sibling get_channel without needing to name it.

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 precondition for use: only channels with `guide=1` are supported, and data is valid for up to two days, so the agent knows when the call is useful. It does not name an explicit alternative tool for channels without a guide, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that — results are filtered to catalog-available channels, so some watched content will be absent — but says nothing about result volume, ordering, or how history is populated (record_watch is the likely sibling).

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 brief sentences with no filler, and the scoping constraint is front-loaded. It is efficient, though the title and description restate each other somewhat and the description could carry more without becoming bloated.

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 paginated read tool with full annotation coverage and complete schema descriptions, this is minimally adequate. However, with 41 siblings including several history-related tools and no output schema, the description never states the return shape, ordering, or how to distinguish watch history from chat history.

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%: both limit and offset are documented, including the silent cap at 50 and the next_offset pagination hint. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Names the resource precisely (history of channels watched by the owner) and adds a scope constraint (only channels available in the catalog), which separates it from chat_history and clear_history by content. The verb is implied rather than stated (returns/lists), so it falls just short of a 5.

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

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

No indication of when to call this versus the numerous sibling history tools (chat_history, clear_history, record_watch, forget_watch) or what triggers it. The catalog-only filter hints at behavior but is not framed as usage 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 structurally. The description adds genuine context by disclosing the shape of what comes back (nested folders, sub-tabs, channels, feed URLs at every level), which matters because there is no output schema. It stops short of noting size, auth requirements, or caching behaviour.

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

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

A single front-loaded sentence with no filler, and the scope ('the entire gallery') plus a content inventory is delivered immediately. The only friction is the language mismatch, which costs a little parsing effort for an English-speaking agent.

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's job is to convey what returns; it does so by listing the four levels of content including feed URLs. Auth/ownership is implied by 'do o dono' but not spelled out, and there is no note on response size or nesting depth for what is clearly a large aggregate payload.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object at 100% coverage, and no parameter-level guidance is needed.

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

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

The description names the specific resource (the owner's entire gallery) and enumerates its contents: folders, sub-tabs, channels, and per-level feed URLs. It is more informative than the bare title 'Get library', but it does not differentiate itself from siblings like get_channel or me, and it is written in Portuguese while every sibling and the title are English.

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 alternatives; the agent must infer that get_library is the broad 'fetch everything' call and get_channel the narrow one. No prerequisites, no caveats about payload size, and no exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description's only added claim is that it reflects the newly published commit, which is a useful behavioral trait, but it is buried in unclear phrasing and says nothing about what status/response is returned or any auth/failure semantics.

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

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

It is a single short sentence, so it is not bloated, but it is neither front-loaded nor plainly worded — the key fact (health/liveness of the current deploy) is obscured by jargon rather than stated first.

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 full burden of explaining what a caller gets back, yet it never states the return shape or success/failure semantics. For a health endpoint used by deploy smoke tests, that leaves the agent unable to reason about 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, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter detail is needed or missing.

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 word "Liveness" gestures at a health check, but the sentence is cryptic jargon ('o commit publicado agora', 'é como o smoke espera o próprio deploy') rather than a clear verb+resource statement. An agent can guess this reports liveness/current deployed commit, but it is not stated plainly, and nothing distinguishes it from the sibling channel_health.

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 an oblique hint about how a smoke test waits on its own deploy, which implies post-deploy verification, but no explicit when-to-use, when-not-to-use, or relationship to the sibling channel_health. The agent must infer the invocation context from a metaphor.

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 bar is covered. The description nonetheless adds real behavioral context: it does not remove access denials or CORS requirements, does not fetch origin, and does not write to D1. This meaningfully sets agent expectations beyond the annotations.

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

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

The description is dense and front-loads what it returns, but it spends sentences on UI details (the legacy_url button, the isolated page accepting lang/theme) that do not correspond to tool parameters, diluting the useful content.

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

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

There is no output schema, so the description must carry the return contract; it names the returned items (official site, stream URL, legacy player) but not their format or shape. Combined with the page-oriented lang/theme detail, this leaves an agent with an approximate rather than precise picture.

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

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

Schema coverage is 100% for the single 'id' parameter, so the schema documents it fully and the baseline is 3. The description does not add syntax or format detail for 'id'; instead it describes lang/theme options that belong to a target web page rather than the tool's inputs, which is mildly confusing rather than helpful.

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: public metadata for a stream, including the official channel site, a copyable stream URL, and the legacy HTTP player. An agent can tell this is a metadata read for a given stream. It stops short of naming how it differs from siblings like get_channel, so it's clear but not sibling-differentiated.

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

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

There is no explicit when-to-use guidance and no alternative tools named. The statements 'não busca origem' and 'uma leitura indexada' imply scope (metadata-only, no origin fetch), but the agent is left to infer when this tool is preferred over get_channel or the stream-URL siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact — that results are restricted to cities with an active/playable channel — but says nothing about pagination, ordering, or result size.

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 sentence with no waste, and the scope qualifier is front-loaded before the filter list. Slightly terse phrasing makes the 'canal tocável' constraint less immediately parseable, but structurally it is efficient.

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

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

For a two-param, fully documented, read-only list tool this is close to adequate, and annotations carry the safety profile. However, with no output schema and no mention of result size, ordering, or pagination, an agent can't anticipate the return shape; the Portuguese text against an otherwise English toolset is also mildly jarring.

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 description mentions filtering by country and by state/subdivision, which mirrors the two schema parameters, but adds no syntax, default, or combinability details beyond what the schema already documents at 100% coverage. Baseline 3 applies when the schema carries parameter semantics.

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

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

The description names the resource (cities) and a meaningful scope constraint — only cities that have a playable/touchable channel — plus the two axes of filtering. That verb+resource+scope is clear, but it never mentions sibling tools like list_countries or list_subdivisions, so the agent gets no 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?

There is no statement of when to use this versus the many sibling listers (list_countries, list_subdivisions, list_networks). The filtering axes are implied as usage but no condition or alternative is spelled out.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's real value is the added detail that credentialed calls tag the caller's own comments with `mine: true` and that this flag drives deletability. That is genuine behavioral context beyond the structured fields; pagination/return shape is still unstated.

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: purpose first, behavioral detail second, no filler. Appropriately sized for a trivial list 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?

For a one-parameter read-only list operation with annotations covering the safety profile and no output schema required, the description supplies purpose plus the `mine` flag semantics. Only pagination/ordering behavior is absent, which is a minor gap here.

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 single `id` parameter is fully documented in the schema (100% coverage, including 'ID do canal no catálogo'), and the description adds nothing about it. Baseline 3 applies since the schema carries the semantics.

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

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

The description names the resource and its scope — community comments attached to a specific channel — which separates it from post_comment and delete_comment. It omits an explicit verb like 'list' (that lives only in the name/title), so it is clear but not maximally self-contained.

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 never states when to choose this over siblings such as get_channel or delete_comment, nor any preconditions. The only contextual note ('com credencial na chamada') describes authentication behavior, not when-to-use 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 that results include a playable count and a flag URL, a useful return-value hint given there is no output schema, but it says nothing about ordering, empty results, or whether counts are scoped.

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 dense sentence with no filler, and the resource is front-loaded before the returned-field details. It is a sentence fragment rather than a well-formed statement, 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?

With no output schema, the description usefully notes the returned fields, and the tool is simple (0 required params, one enum). However it omits any usage context or differentiation from the many list_* siblings, leaving gaps an agent would have to infer.

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

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

Schema description coverage is 100% and the single enum parameter is fully documented in the schema, including the behavior of each value. The description's parenthetical about kind=radio merely restates the schema, so the baseline of 3 is correct.

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

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

The description names a specific resource (countries from the catalog) and states what each entry carries (playable count and flag URL), which tells an agent what it gets back. It lacks an explicit verb and does nothing to distinguish itself from siblings like list_cities, list_subdivisions, or list_languages, so it falls short of a 5.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer (e.g. list_cities vs list_subdivisions for geographic drill-down). The only guidance-like fragment, 'kind=radio conta estações', duplicates the schema's own enum documentation rather than routing the agent.

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

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

Annotations already establish readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description does add one genuine behavioral fact beyond the structured data: that only channels present in the catalog are returned, implying silently filtered results. It says nothing about ordering or result limits, so it is a modest but real addition.

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 clauses, no filler, and the filtering constraint is stated up front. It is arguably too terse, but nothing in it 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 no-parameter, read-only listing tool with no output schema, the description covers what it returns (owner's favorites, catalog-restricted channels) and needs little more. Ordering and whether pagination applies are minor omissions.

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 and the schema is empty with 100% coverage, so there is nothing for the description to clarify. Baseline 4 applies for a no-argument tool.

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

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

The description identifies the resource ('Favoritos do dono' / owner's favorites) and a display action ('Exibe'), but uses no explicit verb-resource phrasing and is only readable to a Portuguese speaker, while the tool name and title are English. It is clear enough to distinguish from add_favorite/remove_favorite, but the purpose is stated vaguely rather than precisely.

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

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

There is no when-to-use guidance, no mention of the sibling add_favorite/remove_favorite pair, and no indication of preconditions. The agent is left to infer that this is the read side of the favorites triad.

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 fully covered. The description adds two pieces of real behavioral context – results are filtered to languages with a playable channel, and each entry includes a count – but says nothing about ordering, 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?

A single short clause with no filler, and the scope qualifier is front-loaded. It is slightly hurt by being a noun phrase rather than a full statement, and by being written in Portuguese while the tool ecosystem and sibling names are English.

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?

This is a parameterless read-only lookup with no output schema, so the description only needs to convey what comes back: a filtered set of languages with per-language counts, which it does. It stops short of describing result ordering or structure, which an agent assembling a response would need.

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

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

The tool takes zero parameters, so the baseline is 4. The schema is empty with 100% coverage and there is nothing for the description to compensate for on this dimension.

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 names the resource (languages) and constrains the scope to those that have a playable channel, plus notes each entry carries a count. That is more specific than a bare 'list languages', but it never distinguishes itself from the many sibling list_* tools (list_cities, list_countries, list_networks, list_qualities) or states the list verb explicitly.

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 qualifier 'que têm canal tocável' implicitly tells the agent this returns only languages with playable content, which is a usage-shaped scope. However there is no explicit when-to-use, no when-not-to-use, and no pointer to an alternative 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered without the description's help. The description adds the scope rule (only networks with a playable channel) and notes the count is included, which is genuine behavioral context, but says nothing about ordering, pagination, or result shape for what may be a long list.

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 terse sentence with zero filler; the scope constraint and the count are both front-loaded. Nothing 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 no-parameter read-only listing tool with no output schema, the description covers what the list contains and that a count accompanies it. It would be stronger if it sketched the returned fields (network name, channel count) since no output schema exists to carry that.

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

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

The tool takes no parameters and the schema is empty, so there is nothing for the description to clarify. Baseline 4 applies for a zero-parameter tool.

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

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

The description identifies the resource (networks and broadcasters) and a meaningful scope constraint (only those with a playable channel), plus what is returned (a count). That is more specific than a bare restatement of the name, but it never explicitly says it 'lists' and never differentiates itself from the many sibling list_* tools (list_cities, list_countries, list_languages, list_tags).

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

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

There is no when-to-use guidance, no statement of prerequisites, and no mention of an alternative tool among the numerous list_*/search_* siblings. The scope phrase about 'playable channel' hints at filtering but does not explain when an agent should reach for this instead of something like search_channels.

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 safety is covered structurally. The description adds that values are drawn from catalog streams and broken down by radio/codec/bitrate, which is useful context. It says nothing about result ordering or whether values are deduplicated, so it does not go beyond the annotation-backed baseline.

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

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

A single, front-loaded sentence with no filler. It is efficient, though the one-line form leaves room for a brief note on return shape that would have cost little.

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, no output schema and annotations covering the safety profile, the description supplies the essential information: what is enumerated and from where. A short indication of the returned value format would make it fully self-sufficient, but nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. No parameter meaning needs to be added, and the description correctly does not invent any.

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 ('qualidades distintas') and scopes it to the catalog's streams, then enumerates the facets involved (radio, codec, bitrate). That is enough for an agent to know it returns a distinct-value list rather than a filtered search. It does not explicitly distinguish itself from sibling enumerations like list_languages or list_tags, but the resource itself is unambiguous.

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

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

Usage is only implied: it is a lookup/enumeration tool, so an agent can infer it should be called when it needs the set of available quality values. No when-not conditions, prerequisites, or alternatives are stated, so the guidance stays at the minimum-viable level.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needs incremental value. It does add one real behavioral fact: results are filtered to subdivisions that actually have a playable channel, which is not derivable from the annotations or schema. It says nothing about result size, ordering, or nesting.

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?

One short sentence fragment with no filler; the scope qualifier is the only content and it is front-loaded. It is efficient, though arguably under-specified rather than truly 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?

For a simple read-only list tool with full schema coverage and no output schema, the description is minimally viable. It does not clarify the parent/child relationship with list_countries, nore whether the result set is paginated or hierarchical.

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 parameter (country, ISO 3166-1 alpha-2) is documented in the schema itself. The description adds nothing about the filter's semantics or what happens when country is omitted, 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 names the resource (states/provinces) and adds a scope qualifier ('that have a playable channel'), which is more than a tautology. However, it is a bare noun phrase with no verb and it draws no boundary against clearly related siblings such as list_cities, list_countries, or list_networks, which follow the same 'list X' pattern. It is also written in Portuguese while the tool and sibling names are English, adding friction.

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 tool versus list_countries or list_cities, no prerequisites, and no mention of how the country parameter changes the call. Usage must be inferred entirely from the name.

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=true, idempotent=true, destructive=false, so the safety profile is covered and the bar is lower. The one piece of added behavior — that results include counts — is useful but thin; nothing is said about ordering or how the count is derived, and there is no output schema to lean on.

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 tight clause with the resource front-loaded and the optional scoping condition last. No filler, no restating of the tool name.

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

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

For a zero-required-parameter read-only lister with full parameter documentation and safety annotations, the description covers what the tool returns (tags with counts, nationally scoped) adequately. Only the ordering/shape of the returned tag list is left unspecified, which is minor absent an output schema.

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

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

Schema description coverage is 100%, so both parameters (limit with its 100 ceiling, country as ISO 3166-1 alpha-2) are already fully documented structurally; baseline 3 applies. The description only mirrors the country filter and does not add syntax or edge-case behavior beyond the schema.

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

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

The description names a specific resource (tags of playable radio stations) plus the extra payload (contagem) and an optional scope (por país), which is enough to tell it apart from fillers like list_cities or list_countries. It never states the verb explicitly, but a list operation is unambiguously implied by the sibling naming and the plural resource.

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?

'opcionalmente por país' implies a use case (filter when you want a per-country breakdown) but gives no explicit when-to-use/when-not and no guidance on choosing between this and the sibling listers. Usage is inferred, not stated.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds useful context that the session comes from a cookie forwarded by the MCP client and clarifies that user.id is the owning account, but the identity clause is worded confusingly.

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

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

It is short and front-loads the returned fields, but the trailing clause about 'the account being the account library's account' and user.id ownership is circular and reads as padding rather than clarification.

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 returns and does name email and library size. However, the muddled user.id/account-ownership sentence leaves the identity model ambiguity unresolved for a tool whose whole purpose is identifying the session account.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing further the description could usefully document about inputs.

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

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

The description states a specific resource (the session's account) and what it yields (email and library size), which is more than the tautological name 'me'. It does not explicitly distinguish itself from siblings like get_library or billing, but the session-scoped intent 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The agent can infer it is called to identify the current account, but that inference is left entirely to the reader.

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 what they cannot: operator-only access via METRICS_TOKEN, disclosure that responses contain addresses (sensitive data), and a retention window where rows vanish after `retention_days`. That is meaningful operational context 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?

Four short sentences, front-loaded with the resource and the auth constraint. Slight redundancy between 'com endereço' and 'traz endereço', but nothing 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?

No output schema exists, yet the description conveys the critical return characteristic (addresses are included) plus auth and retention. It leaves the response shape and pagination behavior only partially implied, but the essentials for correct invocation 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 description coverage is 100%, so the schema already documents `ok`, `limit` (including the silent 50-item cap) and `channel_id`. The description adds nothing parameter-specific, so the baseline 3 is correct.

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

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

States a specific resource (raw per-channel play reports including the client address) and scope (single channel), and contrasts itself with both the public panel and the health endpoint that 'never returns IP'. An agent can distinguish it from channel_health 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?

'Use para investigar um canal específico' gives a clear investigative context, and it explicitly positions itself against the public panel as the reason for its separate existence. It stops short of naming a concrete alternative tool or a when-not condition for report_play.

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 annotations already declaring readOnly=false, idempotent=false, and destructive=false, the description adds real behavioral context beyond them: the 20/hour per-owner rate cap and the fact that an omitted author yields a stable, server-generated nickname rather than a new identity per message.

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

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

Two sentences, front-loaded with the core action and the rate limit, with no wasted phrasing. The second sentence is somewhat redundant with the schema's author description but adds the stability-over-time angle.

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 write tool with full schema coverage, no output schema, and annotations covering the safety profile, this is largely complete: action, rate cap, and identity behavior are all stated. Minor gaps remain around failure behavior and max length (deferred to the list response).

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

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

Schema coverage is 100%, so the schema already documents all three parameters, establishing the baseline of 3. The description's note that the author alias stays stable over time adds a slight nuance beyond the schema's "sem ele o servidor gera um estável," but does not materially extend parameter meaning.

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

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

The description states a specific verb and resource ("Comenta num canal" = comments on a channel), which an agent can distinguish from siblings like list_comments and delete_comment. It is clear but does not explicitly name or contrast against those siblings.

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

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

Usage is implied by the action, and the description adds a rate-limit constraint (20/hour per owner) that shapes when the call will succeed. However, it names no alternatives and gives no explicit when-to-use vs when-not guidance relative to siblings.

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

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

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

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

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

A single short sentence with no filler; the content claim is front-loaded and immediately followed by the cost reassurance. Every clause earns its place.

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

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

For a zero-parameter, read-only lookup with no output schema, the description adequately states what is returned (public prices and free allowances) and that the call is free. Only the return format or freshness of the pricing data is left unspecified, which is a minor gap at this complexity.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It appropriately does not invent parameter detail.

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

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

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

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

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

There is no explicit when-to-use guidance and no naming of alternatives (billing, api_access_buy, api_usage). 'No charge' is the only usage-relevant hint, signaling the call itself is free, but which tool to consult for actual account costs versus public list prices is left to inference.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description adds genuine context: no captcha, no payment, free submission, and a rate limit of one message every 10 s per network. This is useful operational detail an agent cannot infer from annotations. The rate-limit and submission facts apply to the downstream contact endpoint rather than this tool's own behavior, which keeps it from 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?

Front-loading is decent, but the negation clause is repeated: 'Não ativa streams... Não provisiona, não cobra e não ativa transmissão' says the same non-action twice. The submission instructions are useful but add length that partially duplicates the rate/no-captcha points.

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

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

For a read-only, zero-required-param tool with no output schema, the description covers purpose, non-actions, submission channels, and rate limits — enough for correct invocation. It could say more about what the returned info/contacts actually contain, but annotations and schema already carry the safety and parameter burden.

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

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

Schema coverage is 100% for the single optional 'lang' enum, and its inline description already documents the pt/en/es/fr/de/hu values and the pt fallback. The main description adds nothing about the parameter, so the baseline 3 is appropriate.

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

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

The description states a concrete verb+resource: it is an authorized-transmission offer that provides information and contacts for producers, without activating streams. It differentiates itself from siblings (legacy_stream, pricing, billing) via explicit negative scope ('não provisiona, não cobra, não ativa'), though it never names an alternative tool. What the tool positively returns (info/contacts) remains slightly abstract.

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 exactly how to act: 'Use contact.form_url no browser, contact.email por e-mail ou POST /api/contact para apresentar o projeto.' It also clarifies when NOT to expect action (no stream activation, no provisioning, no charging). No sibling tool is named as an alternative, so it stops short 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 a non-read-only, non-idempotent, non-destructive write, and the description usefully confirms what is written and where (the owner's viewing history). It does not disclose duplicate handling, whether an existing entry is overwritten, or any auth/ownership requirement — the latter being notable given the 'dono' (owner) framing.

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 no filler. It is efficient, though bordering on under-specified rather than genuinely information-dense.

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 a fully documented schema and no output schema, the description covers the core action adequately. However, the 'owner history' concept remains unexplained (whose history, under what auth, and how it relates to get_history/forget_watch), leaving a small but real 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 channel_id parameter already carries its own description plus a concrete example ('GloboNews.br'). The description's 'canal assistido' merely mirrors that field, adding no format or constraint 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 gives a specific verb+resource ('Registra um canal assistido no histórico do dono' = records a watched channel in the owner's history), which is a meaningful action rather than a restatement of the name. It is distinguishable from the removal sibling forget_watch, though it never explicitly contrasts with add_favorite, which also writes channel-related state.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no named alternative. The agent must infer from the name alone whether this is for telemetry-style watch reporting (vs report_play) or for saving a channel (vs add_favorite).

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, idempotentHint=true, and readOnlyHint=false, so safety and repeat-call semantics are covered. The description adds a genuinely new behavioral fact beyond the structured data: removing the favorite returns a point to a public counter, a side effect invisible in the annotations. It does not say whether the operation fails on a non-favorited channel, 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?

One sentence, front-loaded with the action and followed by the effect, with no filler. It loses a point for mixing language with the English tool title and for leaving "contador público" 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?

No output schema exists and annotations carry the safety profile, so the description need not explain return values. However, the unexplained "contador público" (what counter, whose counter, what a point is) and the absence of any precondition or error behavior leave an agent with an incomplete operational picture for a destructive mutation.

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

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

Schema description coverage is 100%; the single channel_id parameter is fully documented in the schema with an example value (`GloboNews.br`). The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource pair ("Desfavorita o canal" / unfavorite the channel), which is unambiguous and distinct from the sibling add_favorite. It never names add_favorite or any alternative, so an agent must infer the contrast from the name alone.

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, no prerequisites (e.g. the channel must already be favorited), and no mention of the natural alternative add_favorite or list_favorites. The agent gets a purpose statement but no routing information.

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?

Rich detail beyond the annotations: dedup semantics (counts once per owner/channel/day/result), the 200 + `reason: ja_relatado_hoje` response on re-report, and the statement that browser/OS/country are derived from the request (User-Agent, edge) and ignored in the body. Notably, the idempotent-like re-report behavior adds nuance the `idempotentHint: false` annotation alone would not convey.

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?

Dense but front-loaded: the ok/not-ok outcome and the derived-field rule come first, then the dedup behavior, then the rationale. Every sentence carries information, though the repetition of the User-Agent/país point costs a little.

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 supplies the return contract (200 status, `reason: ja_relatado_hoje` is not an error) and the failure-code linkage. For a 3-param write-report tool, nothing an agent needs to invoke 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 baseline is 3, but the description adds real meaning: it clarifies that browser/OS/country are NOT body parameters and that sending them changes nothing, preventing a plausible misuse. `code` applicability ('só quando ok é false') is reinforced.

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

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

States a precise verb+resource: reports whether a channel played (ok=true) or failed (ok=false + code). It is clearly distinguishable from sibling `play_reports` (a listing) and ties into `channel_health`. An agent knows exactly what this call does.

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

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

Explains the motivating condition — 'Sem relato, o catálogo não aprende' — and routes the agent to the downstream consumer, `GET /api/channels/:id/health`. It does not give explicit when-not-to-use exclusions, but the context for calling it is clear.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds real context beyond them: responses are personalized per browser/system/country, each channel carries social.your_fails, and the response is Cache-Control: private. The 48-hour online caveat is also disclosed, though return shape/pagination is not described.

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 single dense paragraph front-loads the core purpose before drilling into filters and behavioral notes, and it is appropriately sized for a 14-parameter tool. The trailing Cache-Control/your_fails detail is slightly tangential to tool selection but still 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, the description still signals what returns look like (per-environment social.your_fails) and the personalization/caching behavior, which is the key non-obvious trait. For a 14-param search tool it is largely complete, though it omits pagination/limit behavior and result ordering defaults beyond sort.

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 5 parameters carry enums, so the schema already documents every parameter thoroughly. The description largely recaps that same filter set (q, country, category, language, network, quality, playable, kind, tag, sort, online) with little added syntax or default behavior 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 ("Busca canais públicos") and enumerates the filter dimensions and the kind/sort/online modifiers, so the tool's scope is unmistakable. It calls itself the product's entry point, hinting at primacy, but it never names a sibling (e.g. get_channel, list_tags) to differentiate itself explicitly.

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 by "É a porta de entrada do produto" and by per-filter notes like kind=radio and online=1, which tell the agent how to reach radio stations or recent channels. However, there is no explicit when-to-use/when-not guidance and no reference to alternatives such as get_channel for a single channel or list_tags for tag lookups.

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