Public TV and radio catalogue with measured stream health, folders and M3U feeds for VLC.
Scored across 41 tools
Most tools target distinct resources, but several overlapping clusters exist: get_programacao / get_programacao_dia / get_channel_guide / list_programacao all concern TV guides; health vs channel_health; contact vs producer_services. The detailed descriptions help, but the set still has multiple plausible misselection points.
Names are predominantly snake_case, but the verb convention is inconsistent: add_favorite, create_category, record_watch, and report_play use different verbs for similar creation/recording actions. Many tools are noun-only (channel_health, chat_history, me, geo), which makes the surface readable but not fully predictable.
41 tools is heavy for this domain and exceeds the 25-tool threshold for 'too many' in this framework. Many list_* and guide-related tools could likely be consolidated without losing core functionality.
Discovery, channel detail, favorites, history, and comments have strong lifecycle coverage. However, the library surface only creates folders/tabs and adds items—there is no update/delete for categories, groups, or items, and no account claim tool despite the claim endpoint being referenced.
Marks a channel as a favorite. A repeat does not add up: the public counter counts people, not clicks.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel to mark as a favorite, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The second sentence adds genuinely non-obvious behavior — repeated adds don't inflate the public counter because it counts people, not clicks — though it sits in mild tension with idempotentHint=false (a repeat is described as having no cumulative effect). Error behavior for an invalid channel_id is not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the purpose front-loaded and no filler. The second sentence is idiomatic rather than precise ("does not add up"), costing it a point, but the size is appropriate for a one-parameter 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 single-parameter mutation with no output schema and annotations covering safety, the description supplies purpose plus the repeat-call nuance. It stops short of stating what happens on an invalid channel or whether a failure is returned/raised.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, and the schema already documents it at 100% coverage including a concrete example (`GloboNews.br`). The description adds nothing 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?
"Marks a channel as a favorite" states a specific verb and resource, and is clearly distinct from the visible siblings remove_favorite and list_favorites. It doesn't explicitly name those alternatives, but the action 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?
There is no when-to-use or when-not-to-use guidance. The reader must infer that this is the write counterpart of remove_favorite/list_favorites from the sibling list rather than from any statement in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds a channel to a tab. 40 channels at most per tab. The response tells the folder and the tab where the channel went, so the screen opens in the right place. The response has the whole updated library, so you do not need to reload GET /api/library.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | Tab that receives the channel, `grp_…`. | |
| channel_id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: a hard limit of 40 channels per tab and a description of what the response contains (folder/tab location plus the whole updated library), which saves a follow-up 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?
Three short sentences, front-loaded with the action, then the constraint, then the return behavior. Every sentence carries information; only the phrasing of the last clause is slightly padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by explaining the response payload and the navigation-relevant fields. Missing only edge-case behavior such as duplicate-channel handling or the error when the 40-channel cap is hit.
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 group_id and channel_id are already documented with format examples in the schema. The description adds nothing about parameter syntax or validity beyond that, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Adds a channel to a tab'), so an agent knows exactly what is mutated. It is distinguishable from the other 'add_*' sibling (add_favorite) by resource, though it never names that sibling to sharpen the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and by the stated cap ('40 channels at most per tab'), which functions as a precondition. However, there is no explicit when-to-use guidance, no statement of what happens past the cap, and no routing to alternatives such as add_favorite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The index of the whole API, with the languages and the HTML pages of each language.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that it returns the API index with languages and HTML pages, which is useful content context, but it does not describe return format, size, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a zero-parameter endpoint, though the phrasing could be slightly more precise.
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 low complexity and rich read-only annotations, the description covers the basic content of the endpoint. However, with no output schema, it leaves the exact return structure and how it relates to sibling discovery tools 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?
The tool takes zero parameters, so there is no parameter semantics to document. The schema is empty and fully covered; the description appropriately does not discuss parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun phrase that describes an API index containing languages and HTML pages, but 'index of the whole API' is vague and does not state an action or clearly distinguish it from sibling list_languages. It adds content beyond the title, but the purpose remains only partially 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 guidance on when to use this tool versus alternatives. Sibling tools like list_languages and list_countries cover similar discovery needs, yet the description gives no context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The community health of the channel: the success rate, the failure reasons and the affected environments. It tells 'the channel is off the air' from 'the channel is blocked in your country'. geo tells whether it is a regional restriction or a general failure (with the countries), regions[] has the success and the failure by country, latency[] has the opening speed measured at the hop by country, and pra_voce sums it up for the country of the caller. Without community reports (POST /api/play-report), the panel is empty.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, so the bar is lower. The description nonetheless adds real context: the data dependency on `POST /api/play-report` and the consequence of an empty panel without reports. It stops short of describing auth, rate limits, or result shape beyond the named 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?
It is front-loaded with the purpose before enumerating fields, and every clause conveys meaning. The field-by-field enumeration (`geo`, `regions[]`, `latency[]`, `pra_voce`) is dense but justified given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return values, which it does by naming `geo`, `regions[]`, `latency[]`, and `pra_voce`. It also discloses the data-freshness prerequisite, leaving little an agent needs before calling it.
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 `id` parameter at 100% schema description coverage, with the schema already supplying format and an example (`GloboNews.br`). The description adds nothing about the parameter, so this sits at the baseline where the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (channel community health) and its content: success rate, failure reasons, affected environments. The framing 'tells the channel is off the air from the channel is blocked in your country' sharpens the purpose, though it never names sibling tools like `health` or `geo` to differentiate 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 through the diagnostic scenario (distinguishing a regional block from a general outage), and it notes the prerequisite that the panel is empty without community reports. However, it never states when to reach for this versus the sibling `health` tool or the `geo` tool, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The last messages in the room of a channel (without WebSocket).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds two useful behavioral traits beyond annotations: only the *last* messages are returned (a bounded window, not full history) and retrieval is pull-based via HTTP rather than a live socket. It still omits how many messages constitute 'last' and any pagination 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?
One short sentence with no filler; the resource is front-loaded and the qualifier is parenthesized at the end. Efficient, though the fragmentary noun-phrase construction is slightly less actionable than a verb-led sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with annotations covering safety, the description conveys the essential scope. With no output schema, it does not say what a 'last messages' response contains or how large the window is, and it leaves the get_history/clear_history disambiguation unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single channel_id parameter is fully documented with an example in the schema. The description's phrase 'of a channel' only loosely reinforces channel_id and adds no format or constraint detail, 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?
Names the resource (recent chat messages in a channel's room) and the mechanism (polling, 'without WebSocket'), so the agent can identify it as a read of chat messages. However, it is a noun phrase with no explicit verb, and it does not distinguish itself from the sibling get_history or clear_history, which an agent must resolve by name-guessing.
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 stated when-to-use guidance, no prerequisites, and no named alternative. The parenthetical '(without WebSocket)' hints that a socket-based route exists but never names it or says when to prefer one over the other, leaving the agent to infer selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a message to the room of a channel by HTTP. The speaker is the guest (X-Guest-Token), the same one that the WebSocket recognizes; without a guest, the account session.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The message text, within `max_length`. | |
| author | No | Nickname to use; without it, the server makes a stable one. | |
| channel_id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds real value beyond that: transport ('by HTTP') and the speaker-resolution rule (guest via X-Guest-Token, otherwise the account session), which an agent needs to predict whose name appears on the 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 tight sentences with the action front-loaded and no filler. The identity clause is slightly dense but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description leaves the return value (message id, echo of author, error on exceeding max_length) unspecified, and it never mentions rate limits or duplicate-message risk. Auth/identity, the main ambiguity for this tool, is covered, so it is adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with three fully documented parameters, so the schema carries the semantics. The description adds no syntax, format, or constraint detail (e.g. the max_length referenced by the body param) beyond what is already structured.
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 ('Sends a message to the room of a channel'), which is clearly distinct from comment-oriented siblings like post_comment and the read-side chat_history. It does not name any sibling explicitly, so it lands just below the top band.
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 over post_comment, chat_history, or any other messaging path, and no preconditions or exclusions. The identity note explains who the speaker is, not when the tool should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clears the whole history of the owner at once.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 one useful behavioral fact beyond that: the operation clears the entire history in a single call (no per-item selection, no filtering). It does not state whether the action is reversible or whether confirmation is required.
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 key scoping word ('whole') is front-loaded. It is efficient, though it is on the terse side for a destructive operation.
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 destruction/idempotency profile, the description supplies the one thing annotations cannot: the breadth of the wipe ('whole history ... at once'). 'Owner' is slightly ambiguous about whose history, but the shape is adequate for a zero-argument destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters (schema coverage 100%, empty object), so there is nothing for the description to document. Baseline 4 applies; the description correctly implies no scoping parameters are accepted.
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 ('Clears') and resource ('the whole history of the owner') with an explicit scope ('at once'), so the agent knows this is a bulk wipe rather than a targeted delete. It does not reference siblings like get_history or chat_history, but the destructive bulk action is distinguishable on its face.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus get_history/chat_history, nor any precondition or warning about the consequences of clearing. The agent must infer usage entirely from the name and the destructive annotation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write to the people behind the product: a question, or a sponsorship/partnership/advertising proposal. One route for a question and for a sponsorship, partnership or ad proposal (tipo, with the placements of GET /api/partners). One message every 10 seconds per network: one that arrives sooner waits its turn and then goes out — no error. The message reaches the team by e-mail, with email as the reply address. For voice, send multipart/form-data: dados is this JSON (up to 32 KiB), and audio is one WebM, Ogg or M4A audio file (up to 2 MB). Audio can replace message. The browser records up to two minutes. Audio is attached to the owner's e-mail.
| Name | Required | Description | Default |
|---|---|---|---|
| fuso | No | Consulting: the IANA time zone, such as `America/New_York`. | |
| name | Yes | What to call the person writing. | |
| pais | No | Consulting: the country of the person asking. | |
| site | No | Website of who is proposing. | |
| tipo | No | Proposal: `patrocinio`, `parceria`, `anuncio` or `consultoria`. Turns on the fields below. | |
| Yes | Where to reply. | ||
| prazo | No | Consulting: when to start (`agora`, `1_mes`, `1_3_meses` or `explorando`). | |
| espaco | No | Placement ids from `GET /api/partners`, up to 6. | |
| duracao | No | Exposure in days: `30`, `90` or `365`. | |
| empresa | No | Who is proposing, when it is a company. | |
| formato | No | Consulting: `projeto` (per scope), `mensal` (monthly) or `assessoria` (advisory). | |
| message | Yes | What you want to say. | |
| projeto | No | Consulting: the kind of project (`llm_privado`, `voz`, `dados_sensiveis`, `gpu`, `integracao` or `outro`). | |
| horarios | No | Consulting: up to 3 times for the call, `YYYY-MM-DDTHH:MM` in that time zone. | |
| No | Optional reply number with country code, such as +5561999999999. | ||
| orcamento | No | Advertising: `ate_100`, `100_500`, `500_2000`, `2000_mais` or `a_combinar`. Consulting, in US dollars: `ate_2000`, `2000_5000`, `5000_10000`, `10000_mais` or `nao_sei`. | |
| pagamento | No | ||
| prefer_whatsapp | No | Request a WhatsApp reply. Requires whatsapp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-read-only, non-idempotent, non-destructive; the description goes well beyond that. It discloses the queueing rate-limit behavior (a message arriving sooner waits its turn, no error), that delivery is by e-mail with `email` as reply address, the multipart/form-data alternate path with exact size caps (32 KiB JSON, 2 MB audio), and accepted audio formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and most sentences carry real information (rate limit, multipart, delivery). There is mild redundancy between the first sentence and the 'One route for a question and for a sponsorship...' sentence, and the mention of `GET /api/partners` as a separate route is slightly disorienting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter tool with no output schema and 94% schema coverage, the description covers behavior well: limits, queueing, delivery, and the alternate voice format. It omits any statement about the success/failure response or authentication, which is a modest remaining gap 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?
Schema coverage is 94%, so the schema carries most parameter meaning (baseline 3). The description adds genuinely non-schema information: the behavior of `tipo` turning on dependent fields, and the entire multipart `dados`/`audio` input format that does not appear in the JSON schema at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Write to the people behind the product', and enumerates the two supported cases (a question, or a sponsorship/partnership/ad proposal). The phrasing is slightly loose ('the people behind the product'), but an agent immediately knows this is the contact/submission tool, and no sibling overlaps with 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?
It explains the selector (`tipo`) that switches between a question route and the proposal fields, and states the rate-limiting behavior (one message every 10 seconds per network, queued rather than errored). It does not give explicit when-not-to-use guidance, but with no competing sibling that gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a personal folder (category). 8 folders at most per owner. The response has the whole updated library, so you do not need to reload GET /api/library.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Folder name, up to 40 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered. The description adds genuinely useful context beyond that: the 8-folders-per-owner cap and the fact that the response returns the whole updated library. It stops short of stating permission requirements or what happens on hitting the cap.
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 with zero waste, front-loading the core action and following with the two constraints an agent actually needs. Nothing could be cut 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?
With only one parameter, full schema coverage, and no output schema, the description supplies what is missing: the creation limit and the fact that the response contains the full updated library, removing the need for a follow-up read. It omits only edge-case behavior when the limit is exceeded.
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 already documents the 40-character limit, so the schema carries the load. The description adds nothing about the name parameter (e.g. uniqueness rules), making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Creates a personal folder") and even disambiguates the terminology by mapping folder to category. However, it does not distinguish this from the sibling create_group, which an agent could easily confuse with folder/category creation.
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 comparison to alternatives such as create_group or get_library. The mention of GET /api/library tells the agent what NOT to call afterward, but that is a return-value note, not selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a tab in a folder. 12 tabs at most per folder. The response has the whole updated library, so you do not need to reload GET /api/library.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tab name, up to 40 characters. | |
| category_id | Yes | Folder that receives the tab, `cat_…`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=false, idempotentHint=false and destructiveHint=false already declared, the description adds real value by disclosing a hard quota (12 tabs per folder) and by stating the response contains the entire updated library. It does not say what happens when the cap is exceeded (error vs silent failure), 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?
Two short sentences, front-loaded with the action and then the two constraints an agent needs (quota, response payload). No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter creation tool with no output schema, the description covers the essential extras: the per-folder limit and the fact that the response already contains the refreshed library, saving a redundant GET /api/library. Only the failure behavior at the quota boundary is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both category_id and name are fully documented in the schema, including the 40-character limit and the cat_… prefix. The description adds no parameter-level information, 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 gives a specific verb+resource ("Creates a tab in a folder") and its scope, which is enough to separate it from the folder-creating sibling create_category. It would be a 5 if it resolved the mismatch between the tool name create_group and the user-facing term "tab".
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 constraint ("12 tabs at most per folder") and the location phrase, but there is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named. The 12-tab cap is the only routing signal an agent gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a guest ipt_…. It asks for no e-mail and no other data. Keep the token: if you lose the token, you lose the library, unless an account already claimed it (POST /api/auth/claim). Then the account keeps what the token saved.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations establish this is a non-idempotent write that is not destructive, and the description adds the critical consequence the annotations cannot express: losing the token means losing the library unless claimed. It also points to the claim endpoint that preserves the data, which is genuinely valuable behavioral context.
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 what is created and what it costs to lose it. The final sentence ('Then the account keeps what the token saved') partially restates the preceding claim condition and is the weakest line.
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 already covering the safety profile, the description supplies the remaining need: the persistence/ownership model around the token. It does not describe the returned token payload, but with no output schema that omission is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description reinforces this by stating no e-mail or other input is required, which is the only parameter-relevant fact available.
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 guest) plus the concrete token prefix `ipt_…`, which lets an agent recognize the artifact it produces. No sibling tool in the list creates guests or tokens, so it is unambiguously 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?
Implies usage context ('asks for no e-mail and no other data' suggests anonymous onboarding) and names the follow-up path `POST /api/auth/claim`, but never states explicitly when to choose this over an account-based flow or what preconditions exist. Usage is inferred rather than instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a comment of the owner. The 404 is on purpose: the API does not confirm that a comment with that id exists when it is not yours.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID, from `Comentario.id`. |
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 bar is lower. The description still contributes real value by warning that a 404 is intentional rather than evidence of a missing comment, and that the API deliberately does not confirm existence of comments the caller does not own — non-obvious behaviour an agent could otherwise mishandle.
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 core action front-loaded and the caveat immediately after it. Nothing is padded and every clause carries information the caller needs before issuing the call.
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 no output schema and full annotation coverage, the description supplies the essentials: what is removed, the ownership scoping, and the intentional-404 error semantics. A brief note on irreversibility or auth requirements would make it fully self-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?
Schema description coverage is 100% and the single id parameter is fully documented as "Comment ID, from `Comentario.id`." The description adds only indirect semantics about ownership affecting the outcome, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Deletes a comment") that clearly separates it from the sibling read/write tools list_comments and post_comment. The qualifier "of the owner" is slightly ambiguous about whether it means the comment author or the authenticated caller, so sibling differentiation is implied rather than spelled out.
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 must infer that this is the removal counterpart to post_comment/list_comments from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a channel from the owner's history.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel to remove from the history, for example `GloboNews.br`. |
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 only that the effect is limited to the owner's history, which is a useful scope detail, but says nothing about whether the removal is reversible or what happens on a repeat call beyond what the annotations imply.
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 verb and scope front-loaded and zero filler. It is efficient, though arguably so terse that it omits routing and side-effect information a caller would want.
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, no-output-schema tool with rich annotations, the description covers the basic operation but leaves the destructive/irreversible nature implicit and does not disambiguate from clear_history or the favorites tools in the sibling list.
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 channel_id already carries a concrete example ('GloboNews.br'). The description contributes no additional format, identifier, or resolution detail beyond the schema, 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 verb ('Removes') and resource ('a channel from the owner's history'), scoping it to a single channel rather than all history. It does not acknowledge the nearby siblings clear_history, get_history, or record_watch, so the agent must infer the difference between forgetting one channel and clearing all 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?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as clear_history for wiping the whole history or remove_favorite for favorites. The agent is left to infer the use case entirely from the name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The country and the language suggested for the caller. When the edge detects no country, it suggests BR with source: "fallback"; detected tells what the edge saw.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context—and it does, disclosing the edge fallback behavior (BR with source: "fallback") and the meaning of the `detected` field. It still says nothing about caching semantics or how long a suggestion stays valid, but the added operational detail is genuinely useful.
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 with the core purpose front-loaded and the edge-case behavior second. The opening clause is a mild restatement of the title, but no sentence 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 carries the burden of describing return values, and it only documents `source` and `detected` indirectly. The likely companion fields (the country and language values themselves) are never named, so an agent knows the fallback story but not the full response shape.
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 (0 required, 0 properties), so the baseline is 4. Nothing in the description contradicts or muddies that, and there is no parameter meaning left to explain.
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 it returns—the country and language suggested for the caller—and explains the fallback case, so an agent understands this is a zero-arg geo resolver rather than a listing tool. It does not explicitly distinguish itself from siblings like list_countries or list_languages, leaving some ambiguity about which geo tool 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?
Usage is only implied: the phrase 'suggested for the caller' suggests this is for resolving the caller's own geo context. There is no explicit when-to-use statement, no preconditions, and no routing guidance naming list_countries/list_languages as the alternatives for enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full record of a channel, with the streams that already point to our hop.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return content (full record and streams), but provides no additional behavioral details such as auth requirements, error conditions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the return content. It could be slightly more direct by using a verb, but it is efficient and avoids waste.
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 getter with one required parameter, no output schema, and annotations covering the safety profile, the description adequately explains what is returned—the full channel record and relevant streams. No important gaps remain for correct invocation.
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 input schema has 100% description coverage, including an example for the id parameter. The description adds no syntax or format details beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (channel) and specifies the return content (full record plus streams that point to the hop), making it distinguishable from guide or search tools. However, it does not explicitly name or contrast with siblings like get_channel_guide 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?
No guidance on when to use this tool versus alternatives. Usage is only implied by the name and the required id parameter, with no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Today's TV guide of the channel (recorded by us): now, next and the list. It is available for the channels with a guide (guide=1) and is valid for up to two days. Check the date of the response; the channel record has the summary in guide_now.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the guide=1 availability constraint, a two-day data freshness bound, and the instruction to check the response date because the channel record carries a summary in `guide_now`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what is returned, then availability and freshness caveats. Slightly dense with backtick field names, but every sentence carries operational information; only the '(recorded by us)' aside is marginal.
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 return-value meaning, and it does sketch the payload (now/next/list) plus the guide_now summary location. It stops short of describing the actual response structure or what happens for a channel without a guide, which is the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single `id` parameter, including a format example (`GloboNews.br`), so the schema does the work. The description adds no new meaning about the id beyond naming related fields (`guide`, `guide_now`) that are not parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: returns today's TV guide for a channel, with the payload enumerated as 'now, next and the list'. However, it never distinguishes itself from close siblings like get_programacao, get_programacao_dia, or list_programacao, so the agent must infer which schedule endpoint applies.
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 real precondition ('available for the channels with a guide (`guide=1`)') and a validity window ('valid for up to two days'), which tells the agent when the call is meaningful. But it names no alternative for channels lacking a guide and does not contrast with the other programacao tools, leaving routing implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The channels that the owner watched. It shows only the channels that are available in the catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Items per page. A value above 50 becomes 50. | |
| offset | No | How many items to skip. Use `next_offset` from the previous response. |
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 genuine behavioral detail — that results are filtered to channels currently in the catalog — but says nothing about pagination behavior, ordering, or empty-history outcomes for a paginated read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource definition and followed by the catalog-availability filter. Nothing is padded, though the second sentence is only marginally useful for tool selection and could be folded in.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only list tool whose annotations cover safety and whose schema fully documents its parameters, the description covers the essentials. The remaining gap is that it says nothing about the shape of the returned data (e.g., channel objects with pagination metadata) since 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?
Schema description coverage is 100%, and both parameters (limit, offset) are fully documented in the schema including the 50-item cap and the next_offset chaining hint. The description adds no parameter-level meaning beyond this, 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 a specific resource — the channels the owner watched — which unambiguously identifies it as a watch-history retrieval tool. The verb is only implied ('get' from the name), and it doesn't explicitly contrast itself with siblings like chat_history or clear_history, but the resource is distinct enough for an agent to select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of the related siblings that would be natural alternatives or complements (clear_history, forget_watch, record_watch, chat_history). An agent must infer usage entirely from the title and name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The whole library of the owner: folders, tabs, channels and the feed URLs of each level.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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's addition—that the result is the *whole* library including nested levels and feed URLs—is useful scope context about completeness rather than a partial view, but no pagination, size, or auth behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the resource front-loaded and the payload enumerated compactly—no filler. It is dense but readable, though the sentence fragments could be marginally cleaner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description carries the burden of describing the return shape, and it does so by naming the nested structure (folders, tabs, channels, feed URLs per level). This is adequate for an agent to anticipate the response, though the exact object shape remains unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 applies. The description correctly implies no input filtering is required to retrieve the full library.
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 (the owner's library) and enumerates its contents—folders, tabs, channels, and per-level feed URLs—so an agent knows what it fetches. The verb is implicit in the name, and while it does not explicitly contrast with siblings like list_favorites or get_channel, the resource scope is distinctive enough to separate it from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no stated prerequisites (e.g., auth/owner context), and no mention of alternatives such as list_favorites or get_channel for narrower lookups. The agent must infer the trigger condition entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The last TV guide available for the channel and up to 20 dates of its history.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The stored slug of the channel, from the collection. | |
| antes | No | Exclusive day to page through the earlier days; use `guia.proximo`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive). The description adds only that it returns the last guide plus history, but says nothing about pagination behavior, ordering, or what happens at the edge of the history window, which matters given the 'antes' paging parameter.
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, front-loaded and free of waste. It is brief to the point of underspecification, but that is a completeness issue rather than a structure problem.
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 guide-retrieval tool with no output schema, the description omits the return structure, ordering, and how the 'history' window relates to the paging parameter, and it does not differentiate from three similarly named siblings. This leaves meaningful gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both slug and antes fully documented in the schema, including the reference to guia.proximo. The description adds no parameter meaning 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?
States a specific resource (TV guide / programacao) for a channel with history scope, but the phrasing is ambiguous and does not clearly distinguish it from siblings get_channel_guide, get_programacao_dia, and list_programacao. An agent cannot tell from the text alone which of these to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no mention of alternatives such as get_programacao_dia or list_programacao, despite three closely named siblings that overlap in function. The reader must infer from the name and the 'history' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The stored TV guide of a channel on one day.
| Name | Required | Description | Default |
|---|---|---|---|
| dia | Yes | Collection day, YYYY-MM-DD. | |
| slug | Yes | The stored slug of the channel, from the collection. | |
| antes | No | Exclusive day to page through the earlier days; use `guia.proximo`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description's only added nuance is the word 'stored,' hinting at a cached/local collection rather than a live fetch, but it says nothing about paging behavior, freshness, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler is structurally clean, but it is terse to the point of under-specification rather than genuinely concise. It is not front-loaded with any actionable content beyond the noun phrase.
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 three-parameter read tool with no output schema, the description should at minimum tie the parameters together (day + channel slug) and place the tool among its many guide-related siblings. As written it leaves the agent to reconstruct the contract from the schema and sibling names alone.
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 required parameters and the optional 'antes' paging parameter are already documented in the schema, including the YYYY-MM-DD format and the pointer to guia.proximo. The description adds nothing on top, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (TV guide for a channel on a single day) but is a bare noun phrase with no verb, and it does not distinguish itself from near-identical siblings such as get_channel_guide, get_programacao, or list_programacao. An agent can guess the scope, but cannot tell from this text alone which of those siblings to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus the other guide/programacao tools, and no mention of the prerequisite of first resolving a channel slug from the collection (only implied in the schema). The description offers 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.
Liveness and the commit that is published now. The smoke test waits for its own deploy here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a modest behavioral detail — that the response reflects liveness and the currently published commit, useful for smoke-test/deploy verification — but says nothing about rate limits, auth, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no padding, and the liveness purpose comes first. However, the second sentence is opaque enough that its brevity reads as under-specification rather than efficiency.
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 return values; "liveness and the commit" gives a partial hint but not the format or possible states. For a simple 0-param read tool this is roughly adequate, but an agent cannot fully predict the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No parameter-related text 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?
"Liveness and the commit that is published now" gestures at what the tool reports, but never states a verb or explicitly what it does (check service health / return current deploy commit). The second sentence about a smoke test is cryptic and does not clarify the resource. It leans on the name/title rather than describing the operation.
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 differentiation from siblings such as channel_health, which an agent could easily confuse with this tool. "The smoke test waits for its own deploy here" hints at an internal usage pattern but gives the agent no actionable condition for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public metadata: the official site of the channel, the stream URL to copy into another player, and the legacy HTTP player. The legacy_url button opens http://legacy.gradetv.net/legacy?stream=ID, with no port in the address. The standalone page accepts lang=pt/en/es/fr/de/hu and theme=light/dark. Playlists go through the HTTPS hop, and the media comes directly from the origin. It does not remove an access refusal or a CORS requirement. It is one indexed read: it does not fetch the origin and does not write to the database.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Public stream ID, including the old IDs for compatibility. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds real substance on top: it is 'one indexed read', does not fetch the origin, does not write to the database, and does not circumvent access refusals or CORS. That is meaningful behavioral context beyond the safety flags, though return structure and pagination are 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?
Front-loads the return contents reasonably, but runs six sentences with implementation trivia (port absence, HTTPS hop, lang/theme on an external page) that does not affect how the agent calls this tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does its job of sketching return contents and confirming the operation is a non-mutating read. Only the exact response fields and error behavior are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'id' parameter, so the schema already carries the semantics; the description's note about old IDs roughly repeats it. The lang/theme mention describes the standalone page rather than a tool parameter and could mislead an agent into thinking those are passable arguments.
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 explains what is returned (official site, stream URL, legacy HTTP player) but never states a clean verb+resource like 'retrieve stream metadata'. It is distinguishable by name and content from list/search siblings, but no explicit contrast is drawn with close relatives such as get_channel, so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no named alternative — nothing tells the agent when to prefer legacy_stream over get_channel or the other stream/health tools. The URL-shape notes are informational rather than selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The cities that have a playable channel. You can filter them by country and by state.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Limits to one country, ISO 3166-1 alpha-2. | |
| subdivision | No | Limits to one state or province. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds a genuinely useful behavioral fact beyond that: the result set is limited to cities that actually have a playable channel, which tells the agent this is not an exhaustive gazetteer. Return shape and pagination are not addressed.
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, with the scope constraint front-loaded ahead of the filter note. Minimal and free of filler, though the opening noun phrase is slightly awkward as a standalone sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-required-param read-only lookup, the safety profile (annotations), parameter formats (schema), and result scope (description) are all covered. The remaining gap is the unstated relationship to list_subdivisions and the state/subdivision naming inconsistency.
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 optional filters are already documented with ISO 3166-1 alpha-2 format guidance. The description confirms both are filters but introduces a terminology mismatch, calling the subdivision filter "state," which could mislead an agent mapping it to the 'subdivision' 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?
Names a specific resource (cities) with a meaningful scope qualifier: only those with a playable channel. That distinguishes it from a generic city lookup, but the description never names the sibling lookups (list_countries/list_subdivisions) it sits alongside, so differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"You can filter them by country and by state" implies usage but gives no when/when-not guidance and no pointer to list_subdivisions, which is clearly the related enumeration tool. The agent must infer the relationship between the city filter and the subdivision param on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The community comments about a channel. When the call has a credential, each of your comments has mine: true; this is how the interface knows what you can delete.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel ID in the catalog, for example `GloboNews.br`. |
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 bar is lower. The description still adds genuinely new behavior: that supplying a credential causes each of your own comments to carry `mine: true`, which explains why the caller would authenticate and how delete-eligibility is determined. It does not cover ordering or pagination, but the added context 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?
Two short sentences, front-loaded with the resource and scope, with no filler. The second sentence is longer but carries real information about credential-dependent output rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description should say enough about the returned comment set, and it only covers the `mine` flag plus the implicit list of comments. Ordering, empty-result behavior, and whether comments are nested or flat remain unstated, so it is adequate but not 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?
Only one parameter (id) and schema description coverage is 100%, so the schema fully documents that the ID is a catalog channel ID with an example. The description adds nothing about the parameter, which is acceptable at this coverage level but earns no extra credit.
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 phrase 'The community comments about a channel' identifies the resource and implies retrieval, matching the list_comments name, but uses no explicit verb and never distinguishes itself from siblings like post_comment or delete_comment. An agent can infer the reading role, but the definition does not state 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?
There is no guidance on when to call this versus get_channel, chat_history, or the comment write tools. Usage is left entirely to inference from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The countries in the catalog, with the playable count and the flag URL (kind=radio counts stations).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | `tv` (default) counts TV channels; `radio` counts radio stations; `all` counts both. | tv |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's value-add is the disclosure that results carry a playable count and flag URL. It adds no ordering, pagination, or caching behavior, so it goes modestly beyond the annotations rather than richly.
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 compact sentence with the resource front-loaded and the enum caveat appended as a parenthetical; nothing is wasted. The parenthetical is slightly disjointed from the main clause, which keeps it just under the top band.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does say what each entry contains. For a zero-required-parameter, single-enum list tool whose annotations already declare safety, that is nearly sufficient; ordering and volume of results are the only unstated details.
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, establishing a baseline of 3. The description's '(kind=radio counts stations)' restates rather than extends the schema's enum semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('The countries in the catalog') plus the payload shape (playable count, flag URL), so the agent knows exactly what comes back. It does not differentiate itself from the sibling metadata listers (list_cities, list_languages, list_networks, list_subdivisions), which keeps it out of the 5 band.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the tool name and the parenthetical about `kind=radio`; there is no statement of when to prefer this over list_cities/list_subdivisions or any prerequisite. Adequate for a trivial read-only list, but no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The favorites of the owner. It shows only the channels that are available in the catalog.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 genuinely new behavioral context: results are filtered to channels available in the catalog, meaning some stored favorites will not appear. It stops short of describing ordering or pagination, but this is a meaningful disclosure 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?
Two short sentences with no filler and the resource stated first. The second sentence, carrying the filtering constraint, is the most valuable part and is placed prominently.
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 list tool with no output schema, the description should say more about what is returned (channel objects, ordering, pagination). It covers the important filtering caveat but leaves the response shape undocumented, which is the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so parameter semantics baseline is 4. Schema coverage is 100% and there is nothing further the description could clarify 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 identifies the resource ("the favorites of the owner") but supplies no verb, so the agent must infer that this is a listing operation. It also does not distinguish itself from the sibling tools add_favorite and remove_favorite, which operate on the same resource. Purpose is inferable but not stated as a specific action.
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 alternatives such as add_favorite/remove_favorite or search_channels, and no prerequisites are mentioned. The only hint is the implied read-only listing, which the annotations already imply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The languages that have a playable channel, with the count of each language.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, idempotent read, so the description's job is smaller. It adds the non-obvious scoping fact that only languages with a playable channel are returned, but it does not say whether counts are all-time or live, or how results are ordered.
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 compact sentence with the scoping constraint up front. No filler, though it could be marginally more direct.
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-param list tool this is close, but the description leaves return ordering and whether counts are static aggregate totals undefined, and there is no output schema to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description correctly adds no parameter detail, but also no return-shape detail; not a deduction.
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 ('languages that have a playable channel') and the returned metric ('count of each language'). It is distinguishable from sibling list_* tools by the playable-channel filter, though the verb is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance, and no alternatives are named. The playable-channel filter implies a purpose, but the agent must infer whether this belongs beside list_countries or get_channel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The networks and broadcasters that have a playable channel, with the count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results are filtered to entries that actually have a playable channel, and a count is included. It does not describe ordering or whether the list is exhaustive, so it falls 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?
A single sentence with zero filler, and the most decision-relevant token (the resource being listed) is front-loaded. Nothing repeats the title or annotations.
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 parameterless enumeration tool this is close to adequate, and the 'with the count' phrase partially compensates for the absent output schema. However, with no output schema the description should say what fields each entry carries (e.g. network id, broadcaster name) so an agent knows how to feed results into downstream calls like get_channel or search_channels. That gap keeps it at minimum-viable.
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 no parameter surface for the description to compensate for, and nothing in the text contradicts the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource returned (networks and broadcasters) and adds a meaningful qualifier, only those with a playable channel, plus the count. That distinguishes it from the sibling list_* tools (list_cities, list_languages, list_tags) without needing to open the schema. The verb 'list' is implied by the name rather than stated, which keeps it 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?
There is no guidance on when to call this versus alternatives such as search_channels, get_channel, or list_cities. The 'playable channel' qualifier hints at a discovery/browse use case, but nothing states the condition under which an agent should prefer this tool. Usage must be inferred entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Channels with a collected TV guide, up to 48 per page.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search in the channel name across the whole collection, up to 80 characters. | |
| depois | No | Exclusive ID of the last row; use `proximo`. |
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 contributes real behavioral context by disclosing the page size cap ('up to 48 per page'), but it says nothing about how to advance pages or what a returned channel entry contains.
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 scope qualifier is front-loaded before the pagination note. It is efficient, though arguably under-specified rather than genuinely 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 carries the burden of explaining what comes back, and it only partly does so ('channels with a collected TV guide'). For a simple two-optional-param read tool this is minimally adequate, but the term 'collected TV guide' and the cursor workflow are left for the agent to reconstruct from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `q` and `depois` are already documented (including the pointer to `proximo`), making 3 the baseline. The description adds no extra meaning about search semantics or cursor 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 the resource (channels) and the scope filter (only those with a collected TV guide), which is a specific verb+resource statement an agent can act on. It does not, however, differentiate itself from near-siblings like search_channels, get_programacao, or list_tags, so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance: nothing says to prefer this over search_channels when browsing guide-capable channels, nor when to reach for get_programacao instead. The only implicit cue is the pagination limit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The different qualities found in the catalog streams (for radio, the codec and the bitrate).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 domain context (qualities belong to catalog streams; radio qualities are codec/bitrate), but says nothing about the shape or grouping of the returned values.
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 key qualifier (radio codec/bitrate) placed up front in the parenthetical. Slightly fragmentary grammar, but nothing 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 and no parameters, the description is the only source of information, and it stops short of describing what a caller receives (a flat list of strings, grouped objects, or values usable for filtering). Adequate for a trivial lookup but with a clear 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?
The tool takes zero parameters, so the schema has nothing to document and the description carries no parameter burden. 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 phrase names the resource ('qualities found in the catalog streams') and clarifies the radio variant (codec + bitrate), but it is a noun fragment with no verb, so it reads as a label rather than a stated action. It also gives no differentiation from the many other list_* siblings (list_tags, list_languages, list_networks), leaving the agent to infer the scope.
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 alternatives, and no statement of what these qualities are for (e.g. populating a filter or validating a quality argument). The agent must guess the call context 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.
The states and provinces that have a playable channel.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Limits to one country, ISO 3166-1 alpha-2. |
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 fully covered by structured data. The description adds one useful behavioral fact – that results are limited to divisions with playable channels – but says nothing about ordering, completeness, or whether the country filter changes the 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 sentence with the scoping qualifier front-loaded; nothing is padded. It is efficient, though it is arguably too terse to carry usage or parameter context.
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 zero-required-parameter list tool with rich annotations and no output schema, the description is adequate. It omits any mention of the optional country narrowing and does not say what a division entry contains, which are the main remaining gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional parameter (country) and schema description coverage is 100%, including the ISO 3166-1 alpha-2 format note. The description does not mention the filter at all, so by the high-coverage baseline this sits at 3.
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 and provinces) and a scoping qualifier (those with a playable channel), which lets an agent distinguish it from list_countries and list_cities reasonably well. It has no explicit verb, but 'list' is implied by the name and the enumerative framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this instead of list_countries, list_cities, or geo. The only hint is the 'playable channel' qualifier, which implies a filtered subset but does not say when that subset is the right lookup versus a sibling list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tags of the playable radio stations, with the count, optionally by country.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many tags to return (100 at most). | |
| country | No | Limits to the stations of one country, ISO 3166-1 alpha-2. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that results include a count, but says nothing about ordering, pagination, or how the 100-tag cap behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the core resource front-loaded and the optional filter trailing. It is a fragment rather than a full sentence, but no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only, zero-required-parameter listing tool with full schema coverage and no output schema, the description conveys scope and return shape adequately. Minor gaps around ordering and limit behavior remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (limit, country) are fully documented in the schema. The description's 'optionally by country' merely restates the country parameter without adding format or interaction 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?
States the resource precisely ('tags of the playable radio stations') and notes the return includes a count. No other tag-listing sibling exists, so differentiation is not an issue; a verb like 'List' is implied but omitted.
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 phrase 'optionally by country' implies when the country filter would be used, but there is no explicit when-to-use/when-not guidance and no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The session account (the cookie that the MCP client passes on): the e-mail and the size of the account library. user.id is the account id, and the account owns the library when there is a session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. Beyond that, the description discloses that the account is derived from the cookie the MCP client passes, requiring no arguments, and that the account owns the library only when a session exists – useful behavioral context the annotations cannot 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?
A single dense sentence that front-loads the resource. The trailing clause about ownership 'when there is a session' repeats the session-conditional idea already implied earlier, costing a little tightness but not much.
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 tool with no output schema, the description usefully enumerates the returned fields (e-mail, library size, user.id). Nothing essential is missing, though it could note behavior when no session 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?
The tool takes zero parameters, so the baseline is 4. The description's reference to `user.id` and the session cookie is framed as identity/return context rather than an argument, which is appropriate and adds clarity without implying a 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 (the session account) and the fields it exposes (e-mail, account library size), which disambiguates the otherwise cryptic tool name 'me'. It does not explicitly contrast itself with the adjacent get_library or contact siblings, 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 explicit when-to-use guidance, no mention of alternatives like get_library, and the only contextual hint ('when there is a session') is a data condition rather than an invocation guideline. Usage 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.
The raw reports of a channel, with the address. Operator only (METRICS_TOKEN). Use it to investigate one channel. In the current reports, the ip field has an identifier calculated from the network and a secret value. The retention period is in retention_days. The public panel does not return this identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | `0` returns only the failures, which is the subset for an investigation. | |
| limit | No | Items per page. A value above 50 becomes 50. | |
| channel_id | No | Limits to one channel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond them: the METRICS_TOKEN auth requirement, the fact that `ip` is a secret-derived identifier, and that the public panel omits this field. It does not cover pagination or return shape, but adds real value on top of the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what the tool is, then layers auth, usage, and field semantics. Each sentence carries information and there is no filler, though it is a fairly dense multi-sentence block.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully explains key return fields (ip identifier, retention_days) and the auth constraint, which are the non-obvious details an agent needs. Return format and pagination behavior are left implicit, keeping it just short of complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (ok, limit, channel_id) are already documented in the schema, establishing a baseline of 3. The description explains output field meanings (ip, retention_days) rather than parameter usage, so it adds little beyond the schema for parameters themselves.
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 ('raw reports of a channel') and clearly frames it as an operator-only investigation tool, distinguishing it from 'the public panel' which returns less data. It does not name a specific sibling tool, but the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit context: 'Operator only (METRICS_TOKEN)' and 'Use it to investigate one channel.' This tells the agent both the audience and the intended use case, though it does not spell out when-not to use it versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comments on a channel (20 per hour at most per owner). Without author, the server makes a nickname that stays the same for the same owner, so the person does not get a different name for each message.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel ID in the catalog, for example `GloboNews.br`. | |
| body | Yes | The comment text. The limit is in `max_length` of the list. | |
| author | No | Nickname to use; without it, the server makes a stable one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so safety is partly covered. The description adds genuinely useful behavioral context the annotations do not: a hard rate limit of 20 comments per hour per owner, and the server-side default that omitting author produces a stable nickname per owner.
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 with the core action and rate limit front-loaded and no filler. The author-default clause is slightly wordy but carries real information, so no sentence 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 mutation tool with no output schema, the essentials (required id/body, rate cap, author default) are present. However, it says nothing about what happens when the hourly limit is exceeded, required auth/permissions, or what the caller receives on success, leaving gaps for a write operation.
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 id, body and author are already documented. The description only elaborates on the author default ('stays the same for the same owner'), a marginal addition, and says nothing new about id or body. 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 specific verb and resource ('Comments on a channel'), making the write action clear and distinguishable from read/delete siblings like list_comments and delete_comment. It stops short of explicitly naming those siblings or clarifying scope, but the action 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?
There is no guidance on when to use this tool versus alternatives such as chat_send or the comment-management siblings, and no stated prerequisites for posting. The rate limit is mentioned, but that is a constraint rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authorized broadcast offer on request: information and contacts for producers. It does not turn on streams; it only gives information and collects interest. To present a project, use contact.form_url in the browser, contact.email by e-mail, or POST /api/contact.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the offer: pt, en, es, fr, de or hu. A missing or unknown value falls back to pt. | pt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely useful context beyond them: it does not start streams and only returns information and collects interest. That negative behavior is exactly the kind of trait an agent cannot infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, purpose front-loaded, no filler. Slightly awkward phrasing ("Authorized broadcast offer on request") but nothing that wastes space or buries the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A low-complexity, single-optional-param read tool with no output schema; the description conveys what the caller gets (information and contacts) and what it does not do. No output schema exists, so return-value detail is not owed, and only minor gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One optional lang parameter with 100% schema description coverage including the enum and fallback behavior, so the schema fully carries the semantics. The description adds nothing about language selection, 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 — an on-request broadcast offer providing information and contacts for producers — plus an explicit negative scope ("It does not turn on streams"). It distinguishes itself from generic contact/info siblings, though the phrase "authorized broadcast offer" is slightly opaque.
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?
Names concrete alternatives (contact.form_url in browser, contact.email by e-mail, POST /api/contact) and the condition that selects them ("To present a project"). No explicit statement of when the agent should prefer this tool itself, 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.
Records a watched channel in the owner's history.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | The watched channel, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/non-idempotent profile is covered structurally. The description adds only that the write lands in the owner's history, but says nothing about whether re-recording the same channel creates duplicates, or whether any auth/ownership scoping applies.
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 front-loaded sentence with zero filler, appropriately sized for a single-parameter tool. It is borderline under-specified rather than padded, which is a different failure than verbosity.
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 low-complexity, one-required-parameter tool with no output schema, the description is minimally sufficient but omits any indication of what a successful call returns or how it interacts with existing history entries. Adequate, with a clear gap in behavioral context.
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 a concrete example ('GloboNews.br'). The description adds no format, casing, or validity 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 states a specific verb and resource ('Records a watched channel') plus the destination ('in the owner's history'), so the agent knows exactly what the call does. It does not, however, distinguish itself from neighboring tools such as forget_watch or get_history, leaving sibling differentiation to inference.
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, no prerequisites, and no mention of the obvious counterpart forget_watch (which removes a watch). The agent must infer that this is the write-side pair of forget_watch purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes the channel from the favorites and gives the point back to the public counter.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel to remove from the favorites, for example `GloboNews.br`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=true), but the description adds a non-obvious side effect: the point is returned to the public counter. That is genuine value beyond structured fields, though it says nothing about permissions or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler; the removal action and its side effect are both front-loaded. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, idempotent mutation the annotations carry much of the burden and the side effect is disclosed. However, no output schema exists and the description doesn't say what the counter change means for the caller or whether the removal is reversible.
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 is fully documented in the schema with an example. The description adds no parameter detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (removes) and resource (channel from favorites) plus a notable side effect. It is clearly the inverse of the sibling add_favorite, though it never names that sibling 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?
No guidance on when to use this versus alternatives (e.g., forget_watch, clear_history), no prerequisites or conditions stated. The only inference an agent can make is from the name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports whether a channel played (ok=true) or not (ok=false with code). The browser and the system come from the User-Agent, and the country comes from the request data; the body cannot change them. The first report of a result on a day returns 201. It counts once per owner, channel, day and result; a repeat returns 200 with reason: ja_relatado_hoje. The reports help to compare results in GET /api/channels/:id/health, but they do not confirm the cause of a failure.
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | `true` when it played, `false` when it failed. | |
| code | No | Failure code, only when `ok` is `false`. A missing or unknown code counts as `outro`. | |
| channel_id | Yes | The channel that you tried to watch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides rich behavioral details beyond annotations: it explains the 201 vs 200 response codes, the deduplication logic with 'ja_relatado_hoje', that browser/system/country are derived from User-Agent and request data, and that the body cannot change them. It also notes that reports aid comparison but do not confirm cause. This is far more context than the annotations (readOnlyHint false, idempotentHint false) 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?
The description is concise yet packed with essential information, front-loading the core behavior (ok true/false with code) and then adding important constraints. Every sentence earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple input parameters, the description covers the essential behavioral aspects: response codes, deduplication, derived fields, and limitations. It is nearly complete, though it could explicitly mention what the failure code enum values mean (though the schema does list them).
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 the three parameters. The description adds meaning about the derived browser/system/country and emphasizes that the body cannot change them, which is useful context for the agent. However, it does not elaborate on the meaning of each parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Reports) and resource (whether a channel played) with the boolean outcome encoded. It clearly distinguishes itself from siblings like record_watch or channel_health by dealing with play reports rather than watching history or aggregated 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?
The description explains when to use it (to report a play result) and implies when not (it does not confirm failure cause). It also mentions the idempotency rule ('It counts once per owner, channel, day and result'), which helps the agent understand that repeated calls are safe but may not produce new entries. However, it doesn't explicitly name alternative tools like play_reports or record_watch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches public channels (filters: q, country, category, language, network, quality, playable; kind=radio for radio stations, tag for a radio tag; sort=score orders by the health that a third party measures, sort=votes by the radio votes; online=1 returns only channels seen online in the last 48 h). This is the main entry point of the product. The response changes with the browser, the system and the country of the caller: each channel has social.your_fails, the result for YOUR environment, so the response is Cache-Control: private.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free text in the channel name and its aliases (full-text search). | |
| tag | No | Radio station tag (free vocabulary, for example `mpb` or `news`); see `GET /api/tags`. | |
| city | No | City, catalog code. | |
| kind | No | `tv` (default) is the TV catalog; `radio` is the radio stations; `all` is both. Without `kind`, radio never appears. | tv |
| sort | No | `score` orders by the health that a third party measures, best first; channels with no measurement go to the end. `votes` orders by the votes recorded for the station (radio). `name` is alphabetical order. | name |
| guide | No | `1` returns only channels with a TV guide (EPG). | 0 |
| online | No | `1` returns only channels that the source saw online in the 48 h before the last catalog reload (`health_ext.online`). When the catalog has not reloaded for more than 48 h, the filter returns no channel. | 0 |
| country | No | Country of the channel, ISO 3166-1 alpha-2. | |
| network | No | Exact name of the network or broadcaster. | |
| quality | No | Exact quality of the stream. | |
| category | No | Category ID from the catalog. | |
| language | No | Language of the channel, ISO 639-3. | |
| playable | No | `0` also includes channels with no known usable stream. | 1 |
| subdivision | No | State or province, catalog code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower. The description goes beyond them with genuinely useful behavior: the response varies by the caller's browser, system and country, each channel carries `social.your_fails` for the caller's environment, and the response is `Cache-Control: private`. That is real context an agent could not derive from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, then three compact sentences. The large parenthetical packing most filters is dense but information-bearing rather than padding, so it earns its space despite being a run-on list.
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 14-parameter tool with no output schema, the description does well to disclose the environment-dependent response and the `social.your_fails` field. It stops short of describing the response shape, pagination, or default result set size, which leaves gaps for a tool of 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?
Schema description coverage is 100%, so the schema already documents all 14 parameters and the 3 baseline applies. The description largely restates filter semantics (q, country, category, language, network, quality, playable, kind, sort, online) that the schema already provides, adding only minor nuance such as sort=score ordering rationale.
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 ("Searches public channels") and positions itself as "the main entry point of the product," which helps an agent distinguish it from single-channel siblings like get_channel. It enumerates the filter vocabulary, but never explicitly contrasts itself with siblings (e.g., get_channel, channel_health), so sibling differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The claim that it is "the main entry point of the product" is a light usage cue, and the note that "without kind, radio never appears" plus the online-filter 48h caveat tells the agent how filters behave. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternative tool for narrower needs (single channel lookup, tag listing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the activation of the TV network by the six-digit code.
| Name | Required | Description | Default |
|---|---|---|---|
| codigo | Yes | The six digits shown on the TV screen. They are valid for ten minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no further behavioral context such as a validation result format or failure behavior, which is a minor gap given the annotations carry the main burden.
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, though slightly terse given the operation's context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-param read-only check, the description is adequate but lacks what a successful or failed activation check returns, and no output schema exists to compensate. It is minimally viable for the tool's 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?
Schema coverage is 100% and the 'codigo' parameter is fully documented there (six digits, ten-minute validity). The description only restates 'six-digit code' without adding syntax or edge-case detail, so it meets the baseline without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Checks the activation of the TV network') with the qualifying mechanism ('by the six-digit code'). This distinguishes it from siblings like list_networks or channel_health, though it doesn't name an alternative 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?
No guidance on when to use this versus alternatives such as channel_health or legacy_stream, nor any prerequisites like where the code originates. The agent must infer the activation-verification context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create and run 24/7 linear TV channels. Import videos by URL; we transcode, schedule and stream.
Search and discover currently playable Nordic cultural recordings.
Manage cloud-hosted 24/7 video streams, playlists, destinations, schedules, media and workspaces.
Control your internet radio from any AI client: listeners, stream, playlists, AutoDJ, DJs, store.
Add one secure layer between your agents and this server.
