Tá Rodando

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

Goes well beyond the annotations: discloses the fan-out side effects (email, Telegram, webhook to subscribers), that status=resolved closes the incident and flips affected services back to operational, that resolved incidents cannot be reopened, and enumerates error conditions (not_found, already_resolved, invalid_body, rate_limited with a concrete 30/hour ceiling). It also warns that the text becomes public and must be confirmed with the user first.

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

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

The core action and its side effects are front-loaded, followed by routing guidance, id sourcing, and errors in a logical order. It is dense but nearly every sentence carries operational value (rate limit, no-reopen rule, confirm-before-publish); the errors list is the only part that could be tightened.

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

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

For a 3-parameter mutation with no output schema, the description covers everything an agent needs: what it mutates, who gets notified, the state transition for resolved, irreversibility, id provenance, and expected failure modes. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning beyond the schema by tying `status=resolved` to concrete consequences (incident closed, services restored) and by explaining where `id` originates. It doesn't add format or length guidance for `mensagem` beyond what the schema already states.

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: posts an update to the PUBLIC incident on the status page and notifies subscribers, mirroring the panel's "Postar update". It explicitly separates itself from publicar_ocorrencia (which creates the incident) and notes that the private occurrence is untouched. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit when-to-use (report progress on an already-published incident, or close it) and when-not-to-use (use publicar_ocorrencia to create from an outage; the private occurrence isn't changed here). It even documents where to obtain the id (listar_ocorrencias, publicar_ocorrencia, ver_conta → statusPage.incidentesAbertos).

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

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

Adds rich behavior beyond annotations: partial-update semantics, null handling for section and keyword, the side effect that section publishes a private monitor onto the status page, url_failing requiring confirmar:true, and 1 MB body read limit. This is exactly the context annotations (idempotentHint, destructiveHint) 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?

Dense but front-loaded with the changed fields, then side effects, then sibling routing. Slightly long with nested clauses, but every sentence carries distinct information.

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

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

For a 7-param mutation tool with no output schema, the description covers partial updates, null semantics, side effects, validation gating, and sibling routing. An agent has what it needs to call correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning over the schema: null clears the field, section publishes a private monitor, and new URL/keyword goes through criar_monitor's validation. These are semantic rules the schema alone does not express.

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

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

States a specific verb (altera) and enumerates exactly which fields change (nome, URL, intervalo, seção, keyword), and explicitly names the sibling estruturar_pagina as the tool for page-level edits. An agent can distinguish it from atualizar_incidente and estruturar_pagina without opening schemas.

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

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

Gives clear context: only sent fields change, and explicitly routes whole-page editing to estruturar_pagina. It also names criar_monitor as the source of validation rules. It lacks explicit when-not-to-use for partial-field cases, but the routing to the sibling is stated.

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

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

Annotations only mark it non-readonly, idempotent, non-destructive; the description adds substantial context beyond that: slug normalization rules, minimum length, the slug_taken/reserved_slug/no_page/page_exists/monitor_not_found failure modes, atomic create-or-nothing on bad monitor ids, old-address redirect + reservation, and that the response flags monitors still checking the old address with no automatic change. Nothing here contradicts 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?

Dense but front-loaded: the core edit action and sibling boundaries come first, then creation semantics, then errors and return shape. The single unbroken paragraph with em-dashes carries a lot of load and would scan faster as short labeled bullets, but no sentence is filler.

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

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

There is no output schema, and the description compensates by describing the return (a nova URL, lista de monitores no endereço antigo, códigos de erro). Combined with the create-vs-update branch and the required-on-create trio, an agent has everything needed to call it correctly on both paths.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema cannot: name/slug/monitorIds become mandatory only on the creation path, monitorIds is the public-visibility control (ids from listar_monitores, "all", or []), and slug normalization plus 3-character minimum is restated as a constraint on the resulting value rather than the input format.

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 (altera) plus the exact resource (status page pública da conta) and enumerates every field it touches (nome, endereço, descrição, links, logo, favicon). It goes further by naming the siblings that own adjacent concerns — estruturar_pagina for sections/monitors and vincular_canal for alerts — so an agent can separate it from those tools without opening a schema.

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

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

Explicit routing: sections and monitor list belong to estruturar_pagina, alert recipients to vincular_canal, and 'esta tool não mexe em alertas' closes the ambiguity. It also states the when-not-yet-exists path (statusPage null in ver_conta) and the preconditions that then apply, plus a 'Só os campos enviados mudam' partial-update rule.

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

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

Far beyond what the annotations say (readOnlyHint=false, destructiveHint=false, idempotentHint=false). It discloses the non-obvious outcomes: non-account emails return connected:false until the recipient confirms by link, telegram returns connectUrl/connectGroupUrl and stays disconnected until someone taps Start, the link expires in 24h and requires delete+recreate, and the 20-channel-per-account 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?

Purpose is front-loaded in the first clause, followed by kind-specific rules in roughly schema order. It is dense but nearly every clause carries operational information; the telegram and email sentences are long run-ons joined by semicolons, which slightly hurts scannability.

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 3-parameter mutation tool with no output schema, the description covers what an agent needs: required vs kind-dependent params, the disconnected-then-confirmed lifecycle, how to check state afterward, how monitors get attached, and the account limit. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the target must be a publicly reachable webhook URL and is ignored for telegram, and label is capped at 100 characters — a constraint the schema does not encode. It does restate the kind→target mapping already present in the schema, which keeps it below 5.

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

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

The first sentence states a specific verb and resource ("Cria um canal") and its purpose: delivering monitor down/recovery alerts to the team. Within the sibling set (listar_canais, remover_canal, testar_canal, vincular_canal) it is unmistakably the creation operation, and the per-kind rules make the scope concrete.

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?

Guidance is strong: which kinds take an email vs a public webhook URL, that telegram omits target entirely, and that the new channel starts with no monitors — binding is done via vincular_canal, and state is verified via listar_canais. It never states when not to use it (e.g., reusing/vouching for testar_canal or remover_canal in the 24h-expiry case beyond the recreate instruction), so it falls just short of full when/when-not coverage.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false, idempotent=false. The description goes well beyond: check cadence, ~30s retry after failure, down-marking on the 2nd consecutive failure, default private visibility with default-channel alerting, TLS expiry warnings at 14/3 days, pre-save URL validation with rejected addresses, and plan-limit errors. Rich 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?

A single dense paragraph, but the purpose is front-loaded and each sentence carries distinct information (alerting, keyword, TLS, pre-save checks, plan caps). Long relative to typical descriptions, though justified by the tool's behavioral complexity.

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

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

No output schema exists, so the description must cover return behavior — and it does, naming url_failing, plan_limit, and certExpiresAt. Combined with alerting and validation behavior, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including keyword semantics, section conditions, confirmar, and intervalMin values. The description reinforces these but adds little syntax or meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ("Cria um monitor HTTP para uma URL pública") and scope is precise. It is clearly distinguishable from siblings like atualizar_monitor, ver_monitor, and testar_url. The agent can tell what the tool creates without opening the schema.

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

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

Explains the conditions under which url_failing occurs and that confirmar:true is required, plus when section takes effect and how plan limits surface as plan_limit. It does not explicitly route to siblings (e.g., testar_url for a pre-check), but the built-in URL test makes that unnecessary. Clear context, no explicit exclusions.

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

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

Goes well beyond the annotations by disclosing real side effects: sections not included are deleted, monitors left in no section become private, the operation is all-or-nothing, and specific failure codes are returned (invalid_structure, no_page). It also points to listar_monitores as the source of the current structure. (Note: the deletion/reassignment semantics sit in mild tension with destructiveHint=false, but the effects are irreversible only at the page-config level and are fully disclosed, so the agent is not misled.)

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

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

Purpose and alternatives are front-loaded in the first two sentences with no filler, and each remaining clause carries needed rules. It is a dense single block, though, and would read better as structured points given the number of distinct rules it packs 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?

No output schema exists, and the description compensates by naming the error outcomes (invalid_structure, no_page) and the all-or-nothing guarantee. Combined with the 100%-covered input schema, an agent has everything needed to build a valid payload and interpret failures.

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

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

Schema description coverage is already 100%, so the schema baseline is met. The description still adds semantics beyond it: the ordered-list shape, id-vs-name matching for existing sections ('reconhecida pelo `id` ou, sem id, pelo nome'), and the empty-list meaning, all of which clarify how `sections` behaves.

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 with scope: 'Reorganiza a status page inteira: seções, ordem e quais monitores aparecem em cada uma'. It explicitly contrasts itself with siblings ('atualizar_monitor com `section` é mais simples; nome, endereço e links da página são configurar_status_page'), so an agent can distinguish it without reading any schema.

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

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

Gives explicit when-to-use conditions ('montar ou reorganizar várias seções de uma vez, renomear seção ou tirar monitores da página') and names the alternatives with the exact condition that selects them (single monitor reassignment → atualizar_monitor with `section`; page name/address/links → configurar_status_page).

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

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

With annotations already covering the read-only/idempotent/non-destructive profile, the description goes well beyond them: webhook URLs are masked to host only because they are credentials, Telegram returns target null plus connected/connectUrl semantics, and email shows connected:false until the recipient confirms. These are exactly the surprising return behaviors an agent needs and would otherwise misinterpret.

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

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

The purpose leads, followed by the three non-obvious return caveats (masked webhook URL, Telegram connected/connectUrl, email pending confirmation). Dense but each sentence carries information that substitutes for the missing output schema; only the run-on structure of the last two clauses costs it.

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

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

There is no output schema, so the description must carry the return contract, and it covers the tricky parts (masking, connected flags, connectUrl, linked monitor ids) well. It still omits the general per-channel field shape (id/name/type), which a caller assembling a vincular_canal request would want.

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

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

Zero parameters, so the baseline is 4; there is nothing to document and the description correctly spends its words on return semantics instead. No misleading parameter language is introduced.

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 ("Lista os canais de alerta da conta") and enumerates the channel types covered (email, Slack, Discord, Google Chat, webhook, Telegram), so the agent knows exactly what is returned. It does not explicitly differentiate from siblings like criar_canal/remover_canal, but the verb alone separates it from every mutating sibling.

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

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

Usage is implied rather than stated: the mention of linked monitor ids hints this is how you discover channel/monitor relationships before vincular_canal, but there is no explicit 'use this when' or exclusion versus ver_conta or testar_canal. An agent can infer the context but has to do so itself.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on genuinely non-obvious behavior: retention rules per window, that 30d/90d omit latency, that the 90d % matches the public status page, and the key anti-misinterpretation that an empty window on a paused monitor is not a downtime. This is exactly the context structured fields cannot supply.

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 shape and then packs retention, paused semantics, and pagination into one dense but well-ordered paragraph with no filler. Slightly telegraphic and compressed, but every clause earns its place.

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

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

For a five-parameter, no-output-schema tool, the description fully covers what is returned (per-check fields and window aggregates), the retention constraints on those values, and the pagination loop. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so all five parameters are already documented in the schema. The description adds only a restatement of cursor-based pagination and the window concept, without new semantics for periodo, limite, or apenasFalhas, so baseline 3 is correct.

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

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

States a specific verb and resource ('checks anteriores de um monitor') plus the exact return shape (horário, ok/falha, latência, erro, resumo da janela), so an agent knows precisely what it gets. It is clearly historical data, implicitly distinct from status_monitor's current state, but it never names a sibling explicitly, which is what a 5 would require.

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

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

Gives clear context for use: it explains the retention window (8 days for individual checks, summary-only for 30d/90d), the paused-monitor case, and how to paginate with cursor. It does not name alternatives or explicitly state when not to use this tool, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real behavioral context: no pagination (the whole account is returned), plus exact semantics for `state` values including what counts as down and what `failing`/`awaiting` mean at the moment of the 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?

Dense but front-loaded: purpose and routing come first, then field semantics, then the no-pagination note. Slightly long, but each sentence (state values, empty `channels` = nobody, null `statusPage` = private) carries distinct 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly — enumerating state values, channel semantics, and page/section fields. An agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. Instead of parameters, the description spends its words documenting the returned fields (`state`, `status`, `channels`, `statusPage`, `section`), which is useful but outside the parameter dimension.

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

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

States a specific verb+resource (list all monitors of the account) and immediately scopes its output (current state, who is alerted, where each appears). It explicitly distinguishes itself from siblings ver_monitor (why a monitor failed) and listar_checks (history/uptime %).

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

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

Gives concrete when-to-use triggers ("o que está fora agora?", finding the `id` other tools require) and names the two alternatives with the exact condition that selects each. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds much beyond them: the 90-day retention window, the sort order, the privacy constraint, the episode open/close semantics, and the meaning of an empty avisos list ('ninguém foi avisado'). This is exactly the extra 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?

Front-loads scope and ordering before the definition and the field inventory, so the most decision-relevant facts come first. The long field enumeration is dense and slightly run-on, but each clause (duration single-source, empty list meaning, null incidente_id) carries non-obvious 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?

There is no output schema, so the description absorbs that burden by enumerating every returned field with semantics (duracao_seg as the single source of duration, avisos channels with enviado/falhou/pendente, incidente_id null = unpublished). Nothing an agent needs to interpret the result is missing.

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

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

Schema description coverage is 100%, with abertas and monitor both documented inline, and the description does not restate or extend those parameter semantics. Baseline 3 applies when the schema carries the full parameter burden.

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 (listing occurrences) plus precise scope: monitor occurrences in the last 90 days, most recent first. Defines the domain term 'ocorrência' (opens on the 2nd consecutive failure, closes on recovery or pause), which lets an agent distinguish it from both public incidents and from sibling ver_ocorrencia's single-item view.

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

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

Gives clear context for when this is the right tool: it is the PRIVATE team-only view, explicitly 'not the public incident of the status page', and incidente_id=null signals not-yet-published (implying publicar_ocorrencia). It lacks an explicit routing statement toward ver_ocorrencia for a single occurrence's detail, so it is clear context without full exclusions.

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

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

Goes well beyond the annotations by disclosing concrete side effects: history is preserved, checking stops, no notifications are sent, a plan slot is freed, and the status page shows 'Pausado'. These are exactly the behavioral details an agent needs and are not derivable from destructiveHint=false alone.

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

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

Two tight sentences with the core effect front-loaded and the sibling reference last. Every clause carries distinct information with no padding.

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

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

For a single-parameter state-change tool with no output schema, the description covers all relevant effects (history retention, notification suppression, plan-limit impact, status-page state) and the resume counterpart, leaving nothing an agent needs 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?

Only one parameter (id) and the schema already documents it at 100% coverage, including where to obtain the value (campo `id` de listar_monitores). The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Pausa um monitor') and immediately distinguishes it from the sibling retomar_monitor by naming the counterpart action (resume checking). An agent can tell this apart from retomar_monitor and remover_monitor without opening any schema.

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

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

Explicitly names the alternative retomar_monitor and its opposite effect, giving clear context for choosing between the two pause/resume tools. It stops short of stating prerequisites or when-not to use it (e.g. versus removing), so it is clear but not fully exhaustive.

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

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

Annotations only declare the write/non-idempotent/open-world profile; the description adds the genuinely non-obvious behaviors: dry-run by default returning a draft, notification of page subscribers, retroactive publication of already-closed occurrences, and a cap of one incident per occurrence. It is consistent with destructiveHint=false since later edits/closures are routed to another 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?

Front-loaded with the core action and the publish gate, then prerequisites and the sibling handoff. Every sentence carries information, though the enumeration of draft fields plus the retroactive and one-incident rules make it denser than ideal.

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

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

Covers trigger conditions, dry-run vs. real write, side effects on subscribers, edge cases (closed occurrence, non-status-page monitor, duplicate incident), and post-publication routing. With no output schema, the description also describes what the non-publishing call returns, closing 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining the draft's contents (título, serviço, início, severidade, status, mensagem) that confirmar returns when false, and by framing titulo/mensagem/severidade/status as overrides to the draft. That workflow-level meaning is not derivable from the schema alone.

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 ('Transforma uma ocorrência em incidente PÚBLICO na status page') and immediately flags the subscriber-notification side effect. It also names the sibling that takes over afterwards (atualizar_incidente), so an agent can distinguish it from related tools without opening any schema.

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

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

Explicit about the confirmar gate (draft vs. real publication), the precondition that the monitor must appear on the status page, the retroactive/resolved case for closed occurrences, the one-incident-per-occurrence limit, and the handoff to atualizar_incidente for later updates. Nothing about when to use it is left to inference.

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

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

Annotations already flag destructiveHint=true, but the description adds substantive context beyond them: what exactly is destroyed (monitor links, including panel-created ones), the non-obvious downstream effect (monitors keep checking but stop alerting; a monitor with only this channel ends up with empty `channels`), irreversibility, and the required confirmation step.

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

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

Dense but front-loaded: the destructive consequence comes first, then alternatives, then safety protocol. Every sentence carries information, though the confirmation instruction makes it a touch long for a single-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?

No output schema, but the description discloses the return value ("Devolve `removed` com o id"). Combined with the destruction semantics, confirmation protocol, and alternative routing, an agent has everything needed to invoke this safely.

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

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

Schema coverage is 100% and the schema already documents `id`, so baseline is 3. The description adds value by telling the agent where to source the value ("campo `id` de listar_canais") and that the user should be shown label+destination from listar_canais when confirming.

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?

Specific verb+resource ("Apaga um canal de alerta de vez") with explicit scope: it removes the channel AND all its monitor links. Clearly distinguished from siblings like testar_canal (check) and remover_monitor (different resource).

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

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

Explicit when-to-use ("Use só quando o usuário pedir pra remover o canal") and names the alternative for the adjacent need ("pra conferir se ele funciona, use testar_canal"). Also prescribes the confirmation flow before invoking.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds what annotations cannot: exactly what is destroyed (check history plus status-page presence), that the action is irreversible, and that the agent must echo the monitor name and URL and seek user confirmation first. It also states the return payload ('removed' with the id).

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

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

Four tight sentences, front-loaded with the destructive scope, then the alternative, then the irreversibility/confirmation requirement, then the return value. Every clause carries distinct decision-relevant information with no filler.

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

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

Despite having no output schema, the description discloses the return value, the destruction scope, the irreversibility, the safer sibling, and the pre-call confirmation requirement. For a single-parameter destructive tool this covers everything an agent needs to invoke it safely.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented as coming from listar_monitores, which the description repeats verbatim. The added confirmation workflow (repeat name and URL) is process guidance rather than new parameter semantics, so this sits at the high-coverage baseline.

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

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

States a specific verb and resource ('Apaga um monitor de vez') and immediately scopes it against the sibling 'pausar_monitor', so an agent can distinguish a permanent delete from a temporary pause without opening either schema. It also names the side effects (check history gone, service removed from the status page) that define 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?

Explicitly gives the when ('Use só quando o usuário pedir pra remover'), the when-not with the concrete alternative for temporary stops ('deploy, manutenção, use pausar_monitor, que guarda o histórico'), and a required confirmation procedure before invoking. Nothing is left to inference.

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

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

Annotations only declare idempotent/non-destructive hints; the description goes further by disclosing the latency consequence ('próximo ciclo do worker, até 30 min') and the plan-limit failure mode (returns plan_limit and the monitor stays paused). This is exactly the kind of operational context annotations cannot carry.

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

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

Three short sentences, zero filler: action first, then timing, then failure behavior. Each sentence delivers distinct information an agent needs.

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

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

For a single-parameter state-change tool with no output schema, the description covers the trigger, the async timing, and the error/limit outcome — nothing material is missing 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?

Only one parameter (id) and schema description coverage is 100%, with the schema already explaining that id comes from listar_monitores. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Retoma um monitor pausado') and explicitly names the inverse operation pausar_monitor, letting an agent distinguish it from siblings such as pausar_monitor, criar_monitor or status_monitor without opening any schema.

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

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

The precondition is clear — the monitor must have been paused via pausar_monitor — and the counterpart tool is named, which gives strong routing guidance. There is no explicit 'when not to use' statement (e.g. what to do if the monitor is already active), so it falls just short of a 5.

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

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

Goes well beyond annotations: documents rate limits with the exact wait (60s), a per-account daily cap, and a full error taxonomy (send_failed, not_connected, provider_error) with per-channel semantics (Telegram bot blocked, missing connectUrl, unconfirmed email). This is exactly the behavioral context an agent needs to interpret outcomes.

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 action, then packs rate limits and errors compactly. Dense but every clause carries information; only the error catalog runs long, yet it stays useful.

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-param test tool with no output schema, the description covers the operation, rate limits, and every failure mode, which is more than enough for correct invocation and result interpretation.

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

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

Schema coverage is 100% and the single `id` param is already documented in the schema (including the "campo `id` de listar_canais" reference). The description adds no further parameter detail, so baseline 3 applies.

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

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

States a specific verb and resource: "Manda a mensagem de teste do painel pelo canal." This clearly distinguishes it from sibling testar_url (which tests a URL, not a channel) and from criar_canal/listar_canais. An agent can tell exactly what it does.

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

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

Implies usage (test a configured channel) and adds operational constraints (1 test/minute, daily email ceiling), which shape when it can be called. It doesn't explicitly name alternatives or exclusions, but the context is clear for a single-purpose tool.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing exactly what is NOT mutated (history, monitor state, status page, notifications), the evaluation semantics that mirror the worker (only 2xx is ok, redirect = failure, 10s timeout, 2xx without keyword text = failure), the failure payload shape (reason, message in PT-BR, location for redirects), and a hard rate limit of 10 tests/minute with the rate_limited error and wait time in 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?

Front-loaded with the core behavior and consequences before the routing advice, and every sentence carries information. It is on the long side and re-explains keyword/2xx failure rules that the schema already states, which is the only mild 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?

For a stateless test tool with no output schema, the description still covers the return shape (reason/message, location on redirect) and the rate-limit error, so an agent knows what success and failure look like plus the downstream state implications.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by clarifying precedence and semantics beyond the schema: passing `id` exercises the monitor's URL and keyword together, `url` is for ad-hoc public https addresses, and the keyword argument overrides the monitor's keyword only for this single test.

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

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

The opening sentence states a precise verb+resource+scope: run an HTTP check once, now, return the result and persist nothing. It explicitly distinguishes itself from siblings by naming criar_monitor for ongoing monitoring and listar_checks for history, so an agent can route correctly without opening any schema.

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

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

Gives concrete when-to-use triggers ('depois de um deploy ou de uma correção', 'antes de decidir monitorar') and explicit alternatives with the condition that selects them ('Pra começar a vigiar, use criar_monitor; pro histórico, listar_checks'). Also states the selection rule between the two entry parameters.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: how remaining slots are derived (`monitors.limit` − `monitors.active`), that `statusPage: null` means no page exists, that `identityChosen: false` means default name/address, and that `incidentesAbertos` carries ids usable with atualizar_incidente.

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 purpose and the call-ordering rule before the field inventory, and every sentence carries information. It is dense and long-ish, but the length is justified by the absence of an output schema; a slightly tighter field list would earn a 5.

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

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

With no output schema, the description fully compensates by documenting the return shape field by field (`plan`, `monitors`, `statusPage`, `onboarding.steps`, `upgradeUrl`) plus the semantics of sentinel values. Nothing an agent needs to interpret the result or decide the next call is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description's field-level detail concerns the return payload, not 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?

States a specific verb and resource ('Resumo da conta no Tá Rodando') and enumerates the exact contents (plano, vagas de monitor, intervalos permitidos, status page, primeiros passos). It also explicitly distinguishes itself from listar_monitores for monitor state, so an agent can route without opening a schema.

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

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

'Chame primeiro, antes de criar monitor ou página' gives an explicit ordering rule, and it names the alternative for a related need ('Pro estado dos monitores, use listar_monitores'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes beyond them by explaining the failure lifecycle (first failure does not alert, worker re-checks in ~30s, only the 2nd consecutive failure becomes major_outage), which is genuine domain behavior an agent should know. It does not cover auth requirements or rate limits, keeping it short of a 5.

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

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

Purpose and usage come first, then return-value detail — properly front-loaded. The return section is dense but each clause (state semantics, lastCheck fields, lastFailure enums, ocorrenciaAberta) carries information not available elsewhere; only the parenthetical PT-BR aside is slightly expendable.

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 takes on return documentation and does it thoroughly: monitor/state, lastCheck (ok, latency, error, timestamp), lastFailure (reason enum values, httpStatus, message), and ocorrenciaAberta with null semantics. An agent has everything needed to interpret 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?

Only one parameter and the schema already documents it at 100% coverage, including the pointer to listar_monitores. The description adds no syntax or format detail for `id`, so this sits at the baseline 3 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?

States a specific verb+resource — detail of a monitor — and enumerates what is returned (configuração, estado, último check, motivo da falha). It distinguishes itself from siblings by naming testar_url and listar_checks as the tools for other jobs, so an agent can route correctly without opening any schema.

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

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

Gives an explicit trigger ('quando listar_monitores mostrar um monitor fora do ar ou failing e o usuário quiser saber por quê') and names two alternatives with their conditions: testar_url for running a check now, listar_checks for history. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: the timeline composition (falhas, início, aviso, volta, encerramento, publicação) and — crucially — the 8-day retention limit on individual failure entries, which no annotation or schema conveys.

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

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

Front-loaded with the core purpose, then usage, alternatives, return shape, and one caveat — each sentence carries distinct information. Slightly dense, but no filler or repetition.

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

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

No output schema exists, so the description compensates by describing the return shape (listar_ocorrencias fields plus linha_do_tempo with en/ate/tipo/texto) and the retention caveat. For a read-only single-param tool this is complete enough to call correctly.

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

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

Only one parameter with 100% schema coverage, where the schema already states the id comes from listar_ocorrencias. The description repeats that mapping but adds no format or syntax detail beyond the schema, so baseline 3 is appropriate.

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

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

Names a specific resource (uma ocorrência / monitor downtime) and states the scope: the detailed timeline view. It explicitly distinguishes itself from listar_ocorrencias (list/filters) and publicar_ocorrencia (publish to status page), so an agent can route correctly without opening any schema.

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

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

Gives an explicit when-to-use trigger ('explain a specific downtime') and names two alternatives with the conditions that select them — listar_ocorrencias for lists/filters, publicar_ocorrencia for publishing. Nothing is left to inference.

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

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

Goes well beyond the annotations: it discloses additive merge semantics ('Soma aos vínculos que já existem; repetir não duplica'), reinforcing idempotentHint with concrete behavior. It also scopes the operation ('Só mexe em quem é avisado') and explains the 'all' snapshot semantics, which annotations cannot express.

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

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

The purpose is front-loaded in the first clause, and each following sentence carries distinct, useful information (sequencing, scoping, param semantics, return). It is information-dense but slightly run-on in a few places, keeping it just short of pristine.

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 correctly states the return ('Devolve os monitores vinculados agora'), and it covers usage sequencing, exclusions, idempotent add behavior, and parameter sources. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains where each id comes from (id from listar_canais, monitorIds from listar_monitores) and clarifies that 'all' means all of today's monitors, with a monitor created later not joining automatically—a nuance the schema does not convey.

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

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

States a specific verb and resource ('Liga um canal de alerta a monitores') and immediately describes the effect: alerts route through the channel when monitors go down or come back. It also distinguishes itself from siblings that touch the status page (configurar_status_page/estruturar_pagina), so an agent can tell it apart without opening schemas.

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

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

Explicit sequencing guidance: 'Use depois de criar_canal (o canal nasce sem monitores) ou pra passar a avisar um canal existente.' It names the prerequisite tool and the two situations that select this tool, plus an exclusion that redirects to the correct sibling for status-page display.

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