FlareWarden

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

Goes beyond annotations by disclosing the quota cost ('Spends one monitor'), the return shape (created check plus id, valuable since there is no output schema), and the idempotency behavior in concrete terms ('the same plan id returns the first result'). This is consistent with idempotentHint=true and destructiveHint=false, and adds substantive context the annotations alone do not convey.

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

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

Four short sentences, each carrying distinct information (precondition, return, cost, idempotency, exclusion). The precondition is front-loaded and nothing repeats structured fields verbatim.

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

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

With no output schema, the description compensates by stating the return value and id; with annotations covering safety, it adds quota cost and idempotency; schema covers both parameters fully. An agent has everything needed to invoke 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 both plan_id and confirm (including the requirement to show the confirm sentence to the user) are already documented in the schema. The description only implies the plan-confirmation prerequisite and adds no format or syntax detail beyond that; 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 action (create the content check from a confirmed plan_content_check plan) and its return (the created check with its id). It is clearly distinguishable from plan_content_check (which produces the plan) and update_monitor (which changes an existing check).

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 ('when the user has confirmed a plan_content_check plan') and an explicit exclusion with the correct alternative ('Not for changing an existing check: use update_monitor'). No inference required.

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 idempotency and non-destructiveness, but the description goes further: it discloses a quota cost ('Spends one monitor'), the exact return payload (ping URL plus crontab, GitHub Actions, Kubernetes CronJob, systemd snippets), and the precise idempotency semantics (same plan id returns the first result and the same URL). That is context an agent cannot get from the annotations 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?

Front-loaded precondition, then payload, then cost, then idempotency, then the exclusion. No sentence is redundant and each carries a distinct decision-relevant fact.

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

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

No output schema exists, yet the description summarizes the return value set precisely, and it covers cost, safety, and alternatives. Nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the schema's 'show it to the user first' note covers the confirm gate. The description still adds real meaning to plan_id by explaining the repeat-call behavior, though it says nothing extra about confirm beyond what the schema 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 ('Add the planned cron job monitor') and ties it to a confirmed plan_cron_monitor plan, which uniquely distinguishes it from plan_cron_monitor and update_monitor in the sibling list.

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 precondition ('when the user has confirmed a plan_cron_monitor plan') and an explicit exclusion naming the alternative ('Not for changing an existing job's schedule: use update_monitor'). The routing decision is fully determined.

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 idempotency and non-destructiveness, yet the description adds genuinely new context: it spends one monitor (a quota cost not visible in annotations) and clarifies what idempotency means in practice ('same plan id returns the first result'). It also describes the return payload. It stops short of covering permissions or failure modes, so not 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?

Four tight sentences, front-loaded with the usage trigger, then return value, cost, idempotency, and the sibling exclusion. Every sentence carries distinct information with no 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, and the description compensates by stating what is returned (the dependency with id and watch method). It also covers cost and repeat-safety, so an agent has everything needed to call it correctly and set expectations.

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

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

Schema description coverage is 100%, so both parameters are already documented (including the instruction to show the confirm sentence to the user). The description reinforces that plan_id drives idempotency but adds no new syntax or format detail beyond the schema. 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 action on a specific resource (add the dependency from a confirmed plan_dependency plan) and explicitly separates it from the sibling plan_dependency (planning) and create_site (site-embedded dependencies). An agent can identify the correct tool 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?

Gives an explicit precondition (user confirmed the plan), an explicit exclusion ('Not for a dependency inside a plan_site plan: create_site adds those with the site'), and names the alternative. When-to-use and when-not-to-use are both 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 idempotentHint=true and destructiveHint=false, and the description adds substantive context beyond them: it costs no monitors, repeats with the same plan id return the first result, and it returns the watch with its starting values. It also clarifies that removal/change is not handled here, which is useful boundary information.

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

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

Four short sentences, front-loaded with the trigger condition, then return behavior, cost, idempotency, and exclusions. Every sentence earns its place.

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

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

For a two-parameter tool with full schema coverage and safety annotations, the description covers the key behavioral facts an agent needs: prerequisite confirmation, return content, no monitor cost, idempotent repetition, and the exclusion for removal/change.

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 plan_id and confirm are already documented in the schema. The description adds the useful idempotency detail that the same plan id returns the first result, but it does not add further meaning for the confirm parameter beyond the schema's instructions.

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 (add DNS watch) and immediately ties it to the prerequisite plan_dns_watch plan. It also distinguishes itself from the removal/change path, so an agent can tell it apart from sibling tools 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?

Explicitly says to use this only after the user has confirmed a plan_dns_watch plan, and explicitly excludes removing or changing a watch by naming the alternative (the site's DNS page). This covers when to use it, when not to, and where else to go.

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=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by making the idempotency concrete — an existing site gains only its missing checks, an existing group is not duplicated — and it discloses the return payload. It does not mention permission or ownership requirements, which would be the remaining gap.

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, zero filler, and the usage condition is front-loaded ahead of the return behavior, dedup semantics and the sibling exclusion. Every sentence carries decision-relevant 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, and the description compensates by stating what is returned. All seven parameters are documented in the schema, the mutation nature is covered by annotations, and the idempotent re-add behavior — the most likely source of agent error — is spelled out.

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 goes beyond the per-parameter text by explaining how the parameters interact: the site is returned 'with the checks chosen under it, placed in a group if one is named', which tells the agent that site, children and group compose rather than being independent flags.

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 verb and resource — showing one of the user's sites or a group heading on a status page — and explicitly separates itself from page creation by naming plan_status_page. An agent can tell this apart from the create path without opening either schema.

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

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

It states the trigger condition ('when the user wants another of their sites, or a group heading, shown on one of their status pages') and an explicit exclusion with the correct alternative ('Not for creating a page: use plan_status_page'). That is when-to-use plus when-not-to-use plus a named alternative.

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 say it is a non-read-only, open-world, non-destructive write; the description adds material behavior: it returns a one-time link exposing the signing secret (never in chat), returns a connect page for chat destinations, and requires owner/admin privileges. It also clarifies the chat webhook URL is a credential that is never a tool argument, which is critical for correct invocation.

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 usage condition and the routing decision, and every sentence carries information (event payload contents, secret handling, permissions, doc link). It is on the long side and the event-payload sentence could be trimmed, but nothing is redundant with the 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 explains what the caller gets back (a one-time secret link or a chat connect page), covers authorization level, points to external docs for the format and signature, and rules out the sibling that handles email notifications. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional semantics the schema states only locally: events are required specifically for the custom destination, and the url field must never be a chat provider URL. It stops short of adding anything on sites or idempotency_key beyond what the schema already documents.

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

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

The description opens with a specific verb and resource plus scope: creating a webhook that sends FlareWarden alert events to either a signed JSON endpoint or a chat destination (Slack, Discord, Google Chat, Teams). It also distinguishes itself from the sibling update_my_notifications and from list/update/test webhook tools by naming the exact 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?

It states explicitly when to use it (user wants alert events delivered to their own endpoint or a chat channel) and when not to ('Not for the user's own alert emails: use update_my_notifications'). The custom-vs-chat branch is spelled out as the routing decision an agent must make.

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 destructive and idempotent, and the description adds substantial context beyond them: per-site outcome granularity, partial-failure semantics (a refused resume doesn't block the others), the reason attached to refusals, and the replay behavior ('same plan id returns the first result'). This is exactly the operational detail an agent needs before invoking a destructive, non-reversible-looking action.

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

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

Front-loads the triggering condition, then outcomes, then idempotency, then the alternative — a logical order with no filler. The parenthetical about refused resumes is slightly dense but carries necessary partial-failure information, so it earns its place.

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

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

With no output schema, the description takes on the burden of describing return values and does so (paused, resumed, already so, or refused with reason). Combined with the confirm-gating requirement documented in the schema, an agent has everything needed to invoke this 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 the baseline is 3, but the description adds real meaning about plan_id's idempotent replay behavior and reinforces that the confirm sentence must come from a user-confirmed plan. It does not add further format or syntax detail, so it is not a 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 description makes clear this executes a previously prepared plan_bulk_pause plan and that the effect is pausing or resuming sites, naming the sibling it depends on. The verb (apply/execute) is implied rather than stated outright, so it falls just short of a fully explicit verb+resource statement.

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 timing ('when the user has confirmed a plan_bulk_pause plan'), an explicit exclusion ('Not for deciding which sites'), and the required alternative ('call plan_bulk_pause first'). There is no ambiguity about which tool handles planning versus execution.

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 real context beyond the annotations: no monitor budget is spent, the response is the updated dependency, and repeat calls with the same plan id are non-duplicating. It could go further by stating what happens to components that are dropped from the watch list, since destructiveHint=true signals removal — that specific loss is never spelled out.

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, each carrying a distinct load: precondition, return value, quota cost, idempotency, and exclusion. Usage gating is front-loaded ahead of the exclusion.

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?

Only two fully documented parameters and no output schema, and the description still covers the return value ('the dependency as it now watches') and cost. The remaining gap is the destructive side effect — which components are removed — left implicit against a destructiveHint=true annotation.

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

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

Schema coverage is 100% and both parameters are explained there, including the instruction to show the confirm sentence to the user first. The description only reinforces plan_id idempotency ('the same plan id returns the first result') without adding syntax or format 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?

Names a specific verb+resource ('changes which components of a dependency the site already watches, or how serious each is') and explicitly contrasts with the sibling add_dependency, which handles dependencies not yet watched. An agent can route between change vs. add without opening either schema.

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

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

Gives a hard precondition ('when the user has confirmed a plan_dependency plan'), an explicit exclusion ('Not for adding a dependency the site does not watch yet'), and names the alternative tool to use instead. When-to-use, when-not, and alternatives are all present.

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 beyond the annotations by disclosing the real-world side effect (subscribers are emailed), the return value ('Returns the cancelled window'), and no-op behavior on already-cancelled windows, which corroborates idempotentHint=true. With destructiveHint already declared, only the exact reversibility of a cancellation is left unstated.

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

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

Four short sentences, front-loaded with the trigger condition, then side effects, then the boundary case. Every sentence carries information an agent cannot get from annotations or schema.

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

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

No output schema exists, but the description says what is returned, and it covers idempotency, notification side effects, and the incident exclusion. The only mild gap is how cancelling an entire recurring schedule differs operationally from cancelling one instance.

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 are documented there ('id, name or part of its URL' and 'id from list_incidents with kind maintenance, or its title'). The description's phrase about a 'recurring schedule as a whole' hints at what the maintenance identifier can target but adds no syntax detail beyond the schema, 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 (cancel) and resource (maintenance window), and explicitly scopes it to scheduled, running, or recurring schedules. It reads distinctly from siblings like update_maintenance, draft_maintenance, and schedule_maintenance.

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?

Opening clause names the trigger ('when the user calls off planned work') and the closing sentence names the alternative for the adjacent case ('Not for an incident: use draft_incident_post with kind resolve'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations flag a destructive, non-read-only, idempotent mutation; the description goes well beyond them by disclosing that adding takes effect immediately with no invitation or email, that removal triggers a type-the-site-name confirmation in the client's form, and that only owners/admins may call it. It also warns of the last-site side effect (removing them from the team) which is not captured by destructiveHint 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?

The positive case and the return value are front-loaded, and every sentence carries information; the trailing parenthetical of exclusions is dense but each clause earns its place by preventing a specific misuse. Slightly long and nested, but not padded.

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

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

For a 3-parameter mutation with no output schema, the description supplies the return value (the sites the member can see after the change), permission requirements, immediacy of changes, confirmation behavior on removal, and the edge cases that must be handled elsewhere. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents member identifiers, the sites array (id, name, or partial URL), and the view/edit/remove enum. The description reinforces the single-site removal constraint and the confirmation flow but adds no syntax or format detail beyond the schema, 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 (change which sites a member can see) and enumerates the three concrete outcomes: see more sites, view or edit a site, or stop seeing one. It also names the sibling tools that handle adjacent cases (invite_member, change_member_role), so an agent can distinguish it from them 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 when-to-use (monitor-only member such as a client needing more site visibility) plus explicit when-not-to-use: someone not on the team → invite_member, an account-level member → change_member_role, a member's last site → dashboard. The owner/admin-only precondition is stated. This is close to a complete routing 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?

Annotations already flag destructive/openWorld/non-idempotent, but the description adds valuable context beyond them: the operation emails the member, returns old and new role, and states strict authorization constraints. This is exactly the kind of side-effect and permission disclosure the annotations don't provide.

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

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

Front-loaded with the use case and alternatives, then permission rules. It is a single dense paragraph with little waste, though the sentence run-on about owners/admins is slightly heavy; still efficient overall.

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 mutation tool with no output schema, the description covers when to use it, alternatives, permission gates, side effects (email notification), and return value (old/new role). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already describes the role enum values and the scope enum in detail. The description echoes 'admin, editor or viewer' and the scope idea but adds no format or default semantics beyond what the schema states (e.g., 'Leave out to keep the member's current scope' is already in 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 ('change a member's role'), names the accepted roles, and mentions scope ('cover different monitors'). It explicitly distinguishes itself from invite_member and member removal, so an agent can identify it without opening siblings.

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

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

Explicitly says when to use it ('when the user wants a team member to have a different role') and when not to: inviting (use invite_member) and removing (done in the dashboard). It also spells out permission preconditions (owners and admins only, no self-role changes, no changing the owner, admin changes only by owner).

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

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

Annotations already declare read-only, open-world, non-destructive behavior, but the description adds substantial context beyond them: it explains that results combine the vendor status page and FlareWarden regional checks, show the worse verdict, incidents, response times, and 7/30/90-day uptime. This tells the agent what kind of evidence to expect without contradicting the annotations.

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

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

The description is front-loaded with the primary use case, then explains return contents, coverage, and the explicit sibling alternative. Despite being fairly detailed, every sentence adds decision-relevant information and there is no wasted preamble.

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

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

For a one-parameter read-only status check with no output schema, the description supplies the missing context: what data is returned, how the verdict is formed, coverage scope, and when to use the sibling URL tool instead. Nothing needed to call it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the single service parameter is already fully documented with name, domain, and status-page URL formats plus examples. The description adds useful scope ('hundreds of popular services') but does not materially expand the parameter semantics 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 states a specific verb and resource: checking whether a named third-party service is down, slow, or having an outage. It explicitly distinguishes this from the URL-specific sibling and gives concrete service examples, so an agent can select it confidently.

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

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

It gives clear when-to-use conditions: user asks whether a third-party service such as Stripe, AWS, GitHub, Slack, OpenAI, or Cloudflare is down or why a dependent system is failing. It also states the exclusion explicitly: 'Not for a specific URL or the user's own website: use check_service_status_url.'

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

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

Beyond the annotations (readOnly, openWorld, non-destructive), the description discloses the six probe regions, the four possible per-region outcomes (up, down, blocked, inconclusive), that status codes and timings are returned, that no page content is ever returned, and a 5-minute-per-host cache with the age of a repeated result. That caching note is especially valuable because idempotentHint=false would otherwise leave the repeat-call behavior ambiguous.

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 trigger condition is front-loaded, followed by what the call does, then behavioral caveats, then exclusions in descending order of importance. Although longer than one line, every sentence carries decision-relevant information and none restates the tool name or schema.

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

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

With no output schema, the description fully compensates by enumerating the returned fields (per-region result, status code, timings, overall verdict). Combined with the rate limit, silent caching, and scope exclusions, an agent has everything needed to call this correctly and 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?

There is a single parameter and schema coverage is 100%, so the schema already explains the URL format and that query strings are ignored. The description adds only scope (host-level, not path-level) and no format or normalization guidance beyond the schema, which is the baseline for a fully documented single parameter.

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

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

The description states a specific verb and resource — request a URL once from six named regions and return per-region status plus an overall verdict. It explicitly separates itself from check_service_status (named third-party vendors) and diagnose_site (FlareWarden-monitored sites), 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?

It opens with an explicit trigger ('when the user asks whether a specific website, URL or API endpoint is down, unreachable or slow') and gives verbatim user phrasings. It also names two exclusions with the exact alternative tool for each, so both when-to-use and when-not-to-use 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?

Goes well beyond the annotations: it discloses quota consumption ('spends the monitors the plan priced'), partial-success behaviour ('anything left out because the plan filled up'), and the exact idempotency semantics ('the same plan id returns the first result'), which is more precise than the bare idempotentHint flag.

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 triggering condition, then return shape, then cost, then idempotency, then the exclusion. Every sentence carries distinct information; nothing is redundant with the schema 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?

There is no output schema, but the description enumerates what comes back (created sites with ids, page checks, dependencies, omissions, next steps) and covers the mutation's cost and repeatability. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented there and the baseline would be 3. The description adds a real semantic constraint on plan_id — reuse returns the first result — and ties confirm to a user-visible confirmation step, which meaningfully extends the schema.

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

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

States a specific action — creating the sites described by a confirmed plan_site plan — and immediately distinguishes it from the planning sibling by requiring a confirmed plan. An agent can tell this apart from plan_site without opening either schema.

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

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

Explicitly names the precondition ('user has confirmed a plan_site plan and its cost'), the alternative (show them plan_site's summary first), and the exclusion ('not for a plan the user has not seen'). No routing inference is required.

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 past the annotations: it warns that the page is public the instant it is created (a side effect the openWorldHint flag alone doesn't convey), details the idempotency contract (same plan id returns the first result, never a second page) rather than merely asserting idempotentHint, and states the return payload. No contradiction with the declared write/idempotent/non-destructive profile.

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 triggering condition, followed by return value, safety side effect, idempotency, and the anti-pattern in separate short sentences. Each sentence 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?

No output schema exists, and the description compensates by describing what is returned (the public address and page content). For a 2-parameter write tool with full annotation coverage, this leaves nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented including the 'show it to the user first' instruction for confirm. The description adds meaning beyond the schema by tying plan_id to the idempotency behavior, which explains why reuse is safe. Modest but real added value on top of a fully documented schema.

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

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

States a specific verb and resource ('create_status_page') and immediately scopes it to a confirmed plan_status_page plan. It distinguishes itself from the same-family siblings plan_status_page, get_status_page and update_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 precondition ('when the user has confirmed a plan_status_page plan, including publishing it') and an explicit exclusion with the alternative named ('Not for changing an existing page: use update_status_page'). Both when-to-use and when-not-to-use 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?

Adds substantial context beyond annotations: a rate limit of 10 per hour per site, a repeat-within-a-minute cache behavior, and the fact that page content is never returned. It also details the diagnostic output (per-region timings, failure stop point, certificate info), which annotations cannot convey. No contradiction with readOnlyHint=true.

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?

Although long, it is front-loaded with the trigger scenario, then examples, then behavior, then exclusions. Every sentence adds actionable information; there is 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?

With no output schema, the description fully explains the return shape (per-region results, timings, failure point, certificate data, summary finding). Combined with rate-limit and exclusion details, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the single parameter 'site' is fully described by the schema. The description reinforces scope by saying it must be one of the user's own sites and accepts id/name/URL, but adds no new syntax or format detail beyond the schema 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 action (diagnose a site from every region) and enumerates exactly what is returned: per-region status code, DNS, connect, TLS, first-byte times, failure point, certificate issuer/expiry, and a one-line finding. It is immediately distinguishable from siblings like get_incident or check_service_status_url.

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

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

Explicitly says when to use it (site down, failing from some places, slow, alerting, wants a check from everywhere) with concrete user phrasings. It also names when NOT to use it and the exact alternative siblings: get_incident or review_noise for past outages/noise, and check_service_status_url for sites outside the account.

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 explains the actual effect (the anomaly no longer counts and is excluded from future baselines), states that 'dismissed: false' restores it, and says the tool returns the anomaly's new state. This meaningfully clarifies why destructiveHint=true is set while the action remains reversible.

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

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

Four short sentences, front-loaded with the trigger condition, then effect, then the alternative. Nothing is padded and each sentence carries a distinct decision-relevant fact.

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 4-parameter mutation with no output schema, the description covers the trigger, the state effect, reversibility, and the return value, and the schema already documents every parameter. An agent has everything needed to call this correctly and to know what changes.

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 site, event, note and dismissed are all documented in the schema, and the description's 'dismissed false restores it' largely restates the schema's own wording. It adds little parameter-level information beyond that 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+resource (mark/dismiss an anomaly as expected) and anchors it to a concrete user situation (deploy, sale, migration). It also explicitly distinguishes itself from set_anomaly_detection, so an agent can separate the two without opening either schema.

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

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

Gives an explicit trigger ('when the user says an unusual response or run time was expected') and an explicit exclusion with the alternative named ('Not for turning anomaly detection off: use set_anomaly_detection'). Both the when and the when-not 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?

Adds real context beyond the annotations: the suppression is per-member, spans every assistant's conversations, and does not touch the dashboard's own prompts. With destructiveHint=true already declared, the remaining gap is that it never says whether/how the dismissal can be undone or re-enabled.

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 tight sentences: trigger first, scope/return second, exclusion last. Every clause carries information; nothing is repeated from the schema or title.

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, non-open-world tool with no output schema, the description covers trigger, persistence scope, and return value. Only the reversibility/undo story is missing, which matters because the annotations flag it as destructive.

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

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

Schema coverage is 100% and the enum values are self-describing; the description's prose list ('a status page, an alert channel, inviting a teammate, cron monitoring, subdomains or anomaly detection') maps one-to-one onto the enum but adds no syntax, format, or sourcing detail beyond what the schema already 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 outcome is stated concretely ('Returns which suggestion is off', 'It stays off for this member'), so the effect of the tool is clear even though the verb is framed as a usage trigger rather than an action. It does not differentiate from the sibling dismiss_anomaly, and in fact lists 'anomaly detection' as one of the suggestions it dismisses, which blurs the boundary between the two tools.

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

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

Explicit trigger ('when the user says not to suggest something again'), explicit exclusion ('Not for declining once: leaving a suggestion unanswered is enough') with the alternative behavior named. An agent can decide without opening the schema.

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

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

Annotations only cover the generic safety flags; the description adds the crucial behavioral fact that this persists a draft but publishes nothing, no subscribers are emailed yet, and it surfaces conflicts such as an already-open incident. It also previews exactly what the return payload contains, which is essential since no output schema exists.

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 tight sentences: trigger first, then the return preview, then the exclusion. No repetition of the schema and 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?

For a 9-parameter mutation tool with no output schema, the description covers the trigger, the three modes, the side effects (draft saved, nothing posted, no emails), and the shape of the response including conflicts. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the enum params already explain themselves, so the schema carries the load. The description adds only a light touch of meaning, e.g. that an existing open incident on the site is the conflict case tied to the incident parameter. 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 (draft a status page incident post) and enumerates the three concrete modes it covers: declare, update, resolve. It also names a sibling it is not (get_incident), so an agent can distinguish it 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 trigger ('when the user wants to tell customers about a problem on one of their sites') plus an explicit exclusion routing reads to get_incident. The clause 'Saves the draft and posts nothing' implicitly signals publish_incident_post as the next step, but that sibling is never named outright, leaving one routing 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 declare non-read-only, non-destructive, non-idempotent behavior; the description adds important context beyond them: a draft is saved, nothing is scheduled, and the return includes the window in the user's time zone, next recurrence occurrences, affected status pages, subscriber email count, and a draft id. It does not cover draft persistence, visibility, or notification timing, but it is substantially more informative than the annotations 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?

Three sentences, front-loaded with the trigger and exclusion, followed by return and draft behavior. Every sentence adds selection or behavioral value, with no restatement of the title or schema.

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

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

For a 12-parameter tool with no output schema and complex recurrence options, the description covers the trigger, draft-only semantics, and key return fields. It leaves out some possible details such as draft expiry, where the draft is stored, or whether subscriber notification is sent now or only counted, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, with every parameter documented inline, including enums and defaults. The description's phrases like 'once or on a schedule' and 'next occurrences of a recurring one' provide framing but no syntax or format detail beyond what the schema already gives, so baseline 3 is appropriate.

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

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

States a specific verb and resource (draft a maintenance window) plus the exact scope: planned work on a site, once or on a schedule, optionally notifying subscribers. It also distinguishes itself from draft_incident_post for outages already in progress, so an agent can tell sibling tools apart.

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 triggering situation (user plans a deploy, upgrade, or migration and wants it marked as maintenance) and the exclusion (not for an outage already happening; use draft_incident_post instead). The note that it 'saves the draft and schedules nothing' also implicitly routes scheduling use cases to schedule_maintenance.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructive false), and the description adds real value beyond them by disclosing the shape of the return: features with what each does, when it helps, how it works, limits, plus plans with prices and limits. Nothing contradicts the annotations, though it doesn't say anything about result size or paging.

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 trigger is front-loaded and the return shape follows immediately, with the parameter note last. The mid-sentence feature enumeration (SSL expiry, DNS changes, heartbeats, dependencies, SLA reports, maintenance windows, Slack alerts) is long, but it functions as query-matching vocabulary rather than 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, yet the description fully specifies what comes back and how the single optional parameter changes that. For a zero-required-parameter read tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by stating the actual filter semantics: passing topic narrows to matching features, omitting it returns everything. That behavioral contract is not expressed by the schema's 'what the user asked about' wording.

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 pairing: it returns a catalogue of FlareWarden features plus plans with prices and limits. The trigger examples ("what does a status page cost?", "can FlareWarden watch cron jobs?") make the tool's domain unmistakable and separate it from siblings like search_help or get_account_overview.

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

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

Gives a concrete when-to-use condition — the user asking about capabilities or pricing — and explains the topic/no-topic branching. It stops short of naming a nearby alternative such as search_help and saying when that one is preferred, so the routing gap remains.

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/openWorld=false/destructive=false, so the description's real added value is the auth behavior: an unsigned connection triggers FlareWarden sign-in, which an agent needs to anticipate. It also previews the response composition. It does not address the idempotentHint=false oddity on what is a read, and gives no pagination or truncation behavior for the incident/attention lists.

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 use case, then the auth prerequisite, then the return inventory, then exclusions — a sensible ordering with no filler sentences. The return inventory is a long comma-list but each item corresponds to distinct content an agent must know.

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 correctly carries the return-value burden by enumerating what comes back and in what order (attention list worst-first, at most three suggestions). Combined with the sign-in prerequisite and the exclusions, nothing material for correct invocation 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 the baseline is 4 and there is nothing for the description to disambiguate. No argument-related guidance is needed.

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

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

Names a concrete verb and resource (account overview) and enumerates the specific payload: identity/plan/role/permissions, monitor capacity, sites by status, open incidents with confirmation, worst-first attention list, and up to three suggestions. It distinguishes itself from siblings by explicitly excluding check_service_status and the no-account case, so an agent can pick it without opening another 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 trigger conditions ('starting any conversation about the user's own account', 'what is wrong / needs attention / what to set up next') plus two explicit exclusions with a named alternative ('use check_service_status' for another company's service status). When-to-use, when-not-to-use, and the alternative are all present.

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 this is a safe read-only operation, and the description adds substantial context about what evidence is returned: confirming regions, first failure, false alarms, rolled-up checks, updates, notifications, and external dependency status. It does not discuss data freshness, size, or rate limits, but the return-content disclosure is strong.

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

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

The description is front-loaded with the triggering scenarios and then enumerates the returned evidence. It is long but structured, and nearly every clause adds useful scope; minor verbosity keeps it from 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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly. An agent can understand what will be returned and when to call this tool instead of list_incidents.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('get_incident') and immediately distinguishes it from the sibling list tool by saying it returns the incident with its evidence. The opening use-case sentence makes the tool's 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?

Explicitly names the user questions that should trigger this tool and ends with a clear exclusion: 'Not for listing incidents: use list_incidents.' This gives both when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description's marginal value is what it returns: most recent records, newest first, with runs/durations/late-or-failed flags. It doesn't mention pagination behavior or the 90-day plan history limit except indirectly, which keeps it off a 5.

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

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

Three sentences, front-loaded with the usage trigger, followed by return shape, then the exclusion. No filler and no repetition of schema field types.

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 convey return values – it does, specifying newest-first ordering and the fields carried for cron runs. Combined with the fully documented schema, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100%, so all six parameters are already documented, including the from/to window and the range enum. The description adds only the semantic gloss on the `check` filter (content check, dependency or cron job, omitted for the site's own uptime checks), so the schema does the heavy lifting – baseline 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?

States a specific verb and resource ('Returns the most recent checks'), enumerates the entities it can cover (site, content checks, dependencies, cron jobs), and explicitly contrasts with get_report. An agent can distinguish it from the ~60 siblings 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?

Opens with an explicit trigger ('Use this when the user asks what a site's recent checks, response times or failures looked like') and closes with an exclusion plus named alternative ('Not for uptime percentages or totals over a range: use get_report'). Both the when and the when-not are stated.

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

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

Annotations already establish this as a read-only, non-destructive operation. The description adds valuable behavioral detail by enumerating the returned switches and their meanings, including edge cases like DNS failure coverage and anomaly detection. It stops short of describing the exact response object or any authorization requirements, so it is strong but not exhaustive.

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

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

The description is front-loaded with usage guidance and then lists returned fields in one dense but purposeful sentence. The enumeration is long, but it carries real semantic value because there is no output schema to document those fields.

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 a zero-parameter, read-only tool with no output schema, the description is complete enough to call correctly: it explains when to use it, when not to use it, what account-specific values are returned, and what each switch means.

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

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

The tool takes no parameters, and the schema is empty. The description reasonably does not discuss parameter syntax because there is nothing to pass, matching the baseline for zero-parameter tools.

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: it 'Returns their own switches for this account' for alert emails. It also distinguishes the tool from siblings by naming list_webhooks for other alert channels and implying update_my_notifications is a separate 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?

It gives explicit when-to-use guidance ('when the user asks which alert emails they get... or before changing them') and an explicit when-not-to-use case with an alternative ('Not for webhooks or Slack... use list_webhooks'). This leaves little 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, non-destructive, idempotent=false), but the description adds real semantic context beyond them: it defines what 'downtime minutes' and 'degraded minutes' mean, notes that unmeasured time is reported as unknown, and lists certificate/domain expiry as part of the payload. It stops short of mentioning any limits on compute time for large windows, but the data-semantics disclosure is well above the bar.

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?

Content is front-loaded with the usage condition and the sibling exclusion last, and nearly every clause carries information. However, it is delivered as one long run-on sentence with a dense middle enumeration of return fields that would be easier to scan as a 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?

With no output schema and six parameters, the description steps up by enumerating the returned metrics and the per-site extra breakdown, so the agent can predict results. The remaining gap is that conditional parameter requirements (e.g. 'site' being needed when scope=site, 'group' when scope=group) are only implied via the schema descriptions rather than restated here.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful mapping: 'range' is glossed as week/month/quarter, 'group' is defined domain-specifically as 'an agency's client', and scope is tied to the report's coverage. It does not explain the precedence or interaction between range and from/to 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 ('get an uptime, SLA or incident report') and enumerates the three scopes (site, group, whole account) plus the time granularities. This is clearly distinguishable from siblings like get_incident or list_incidents, which cover single incidents rather than aggregate reporting.

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?

Opens with an explicit trigger condition ('Use this when the user wants...') and closes with an explicit exclusion plus the alternative to use instead ('Not for the latest checks: use get_monitor_history'). The agent knows both when to pick this tool and when to route elsewhere.

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, non-destructive, closed-world), so the description correctly spends its words on content: the response carries status and last check, child content checks/dependencies/cron jobs with last and next runs, SSL and domain expiry, anomaly detection, maintenance in the next 7 days, and open incidents. It does not mention cost, latency, or size of the payload, which is the main remaining gap for a detail endpoint that fans out into children.

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 usage condition and the exclusion are front-loaded, which is the right order. The middle sentence is a long semicolon-chained inventory of return fields; it earns its place because no output schema exists, but it is dense enough to be slightly hard to scan.

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 takes on the full burden of explaining what comes back and does so in detail, including how the include sections modify the payload. Combined with the readOnly annotations and the routing guidance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, and the schema already defines 'site' (id, name, or partial URL) and each include enum value. The description restates the include behavior with a little extra color (which issuers the site expects) but adds no syntax or format guidance beyond the schema, so the baseline of 3 applies.

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

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

The description names the resource (one site) and enumerates the concrete questions it answers: is it up, why is it down, what is checked, when the certificate or domain expires. It also explicitly separates itself from get_monitor_history and get_report, so an agent can route 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?

It gives an explicit trigger condition ("Use this when the user asks about one of their websites or APIs") and an explicit exclusion with named alternatives for the out-of-scope case ("Not for past checks or uptime over a range: use get_monitor_history or get_report"). 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 readOnly/destructive=false, but the description goes well beyond them by enumerating the returned payload: ordered components with the ids the component tools consume, public URL, subscriber count, and custom-domain DNS/verification/certificate state. With no output schema present, this disclosure is exactly the missing 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?

Two dense sentences: trigger conditions first, return contents second, exclusion last. Every clause carries information and nothing is repeated from the schema 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?

A single-parameter read tool with no output schema, so the description must carry return-value burden — and it does, covering components, URL, subscribers, and domain health. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is documented as 'The page's id or name', so the baseline is 3. The description does not add resolution semantics the schema lacks, such as what happens with an ambiguous or unknown name, or whether lookup is case-sensitive.

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 and resource ('what one of their status pages shows, which sites and checks are on it') with a clear scope boundary against list_status_pages and list_incidents. An agent can distinguish this from every sibling 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?

Names three concrete triggering user intents (what the page shows, which sites/checks are on it, why the custom domain is broken) and an explicit exclusion with the alternative tool ('Not for incidents posted on it: use list_incidents'). Both when-to-use and when-not-to-use are stated.

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

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

Annotations already declare readOnly=true and destructive=false, so safety is covered; the description adds the substantive behavioral detail that it returns a quota breakdown with used/allowed/left across several resource classes. It does not say whether values are real-time or tied to the current billing period, which is a minor remaining gap.

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

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

Three sentences, front-loaded with the use condition, then the return payload, then the routing exclusion. The long return enumeration earns its place because no output schema exists.

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

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

With no output schema and no parameters, the description carries the burden of describing return values and does so concretely (used/allowed/left, seats, webhooks, retention, fastest interval). An agent has everything needed to call it and 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?

Zero parameters, so the baseline of 4 applies. The description correctly implies no input is needed by framing the tool purely around a question the user asks.

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 ('Get plan usage and limits') plus an enumeration of exactly what is returned: monitor pool, status pages, seats, webhooks, subscribers, history retention, check interval. It is clearly separable from siblings like list_sites or get_account_overview.

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 trigger conditions ('when the user asks how many monitors they have left, what their plan includes, or why they cannot add more') and an explicit exclusion routing to get_account_overview or list_sites for downtime questions. Both when-to-use and when-not-to-use 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?

Goes beyond the destructiveHint/openWorldHint annotations by disclosing the concrete destructive semantics: re-inviting the same address replaces the pending invitation of the same kind (site invitations only when the site set matches exactly) and re-sends the email, and the tool returns exactly who was emailed. Authorization constraints are given. It stops short of describing what happens to the replaced link or delivery failures.

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 use-case trigger, then mode, then side effects, then permissions, then the exclusion. Some sentences are long, but every clause carries decision-relevant information, including the replacement rule that would otherwise be a surprise.

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, open-world, no-output-schema tool with 7 parameters, the description covers trigger, modes, return value ('returns exactly who was emailed'), side effects, authorization and the sibling alternative. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mode-selection logic the schema only implies: role/scope for an account invitation versus sites/level/site_checks for a monitor-only invitation. That distinction is the main thing an agent can get wrong, and it is stated in prose.

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?

A specific verb and resource ('invite a person to their FlareWarden account') with both operating modes spelled out: a teammate at a role, or a client with a monitor-only invitation on selected sites. It explicitly excludes the nearest sibling ('Not for changing the role ... use change_member_role'), so an agent can pick it without reading other 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?

Opens with an explicit when-to-use trigger ('Use this when the user wants to give a person access'), states prerequisites (owners and admins only, an admin cannot invite an admin) and names the alternative tool for the adjacent case. The only gap is it doesn't point at revoke_invitation for the inverse operation, which is a minor omission.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that: results are newest-first and resolved incidents include how each was confirmed, plus the fact that kind selects incident vs maintenance windows. It does not mention result truncation or that the effective history window is the plan's limit, which keeps it off a 5.

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

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

Three short sentences with the usage trigger front-loaded, the return shape in the middle, and the sibling exclusion last. No restatement of the tool name or wasted clauses; every sentence 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?

There is no output schema, and the description compensates by describing what comes back: incidents (open or resolved, with confirmation method) or maintenance windows, ordered newest first, scoped to a site/group/account. Combined with 100% parameter documentation and read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter, its enums and defaults — the baseline is 3. The description adds a small but genuine semantic layer by framing site/group/account as the three scoping modes the filters implement, which helps an agent understand how site and group relate rather than treating them as independent filters.

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 (lists incidents and maintenance windows), names the returned scope (one site, a group, or the account), and explicitly distinguishes itself from the sibling get_incident. An agent can route between the two without opening either schema.

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

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

Opens with concrete user-intent triggers ("what went down", "anything down now", "what happened last night", "what maintenance is planned") and ends with an explicit exclusion plus the alternative to use instead (get_incident for one incident's evidence). Both when-to-use and when-not-to-use 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value beyond them by disclosing the returned field set and that results are filtered and paged. It stops short of describing pagination flow or result ordering, which keeps it at 4 rather than 5.

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

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

Three sentences: trigger conditions first, return payload second, sibling exclusion last. No filler, and the most decision-relevant information is front-loaded.

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 compensates by naming the returned fields, and it covers filtering and paging behavior. Nothing an agent needs in order to pick and call this list tool 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%, including an enum on status and bounds on limit, so the schema carries parameter meaning fully. The description only brushes the parameters with "filtered and paged" and adds no filter syntax or combination guidance, 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 (list monitored sites) and then enumerates exactly what each result carries: status, last check, response time, 24-hour uptime, group, interval and SSL days left. It also distinguishes itself from the nearest sibling by name, so an agent can separate it from get_site without opening either schema.

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

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

"Use this when the user asks which websites or APIs they monitor, which are down, slow or paused, or what is in a group" gives concrete trigger phrasings, and "Not for one site's detail: use get_site" supplies the explicit exclusion plus the alternative. Both when-to-use and when-not-to-use are present.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds what the agent otherwise would not know: the exact return payload (public URL, custom domain state, component and subscriber counts, plan page limit), which is valuable because there is no output schema. It stops short of noting cost, auth scope, or empty-list 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?

Three sentences, front-loaded with the trigger, then the return contents, then the exclusion. Every sentence carries distinct information and none restates the tool name or title.

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's enumeration of return fields is what closes the gap, and it does so thoroughly. Combined with the read-only annotations and the zero-parameter schema, an agent has everything needed to select and invoke this tool correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly avoids inventing filter or pagination arguments that the schema does not support.

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 ('list_status_pages' / 'their public status pages') and immediately enumerates the user questions it answers (which pages, addresses, subscriber counts, custom domain status). It also names the sibling it is not (check_service_status) for the adjacent-but-different case.

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?

Opens with an explicit trigger ('Use this when the user asks about their public status pages') and closes with an explicit exclusion plus the correct alternative ('Not for another company's status: use check_service_status'). Both when-to-use and when-not-to-use are stated, not inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the description earns credit for the extra context it adds: the owner/admin-only authorization gate and the fact that last-active is tracked both on the website and through an AI agent. It stops short of disclosing pagination or result-size limits, which matter for a roster that can be large.

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

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

Three sentences, front-loaded with the usage trigger and ending with the exclusion and alternative. The middle sentence is a long run-on enumerating return fields, which is dense but every clause corresponds to a real output field, so no content 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?

There is no output schema, so the description carries the full burden of describing return values, and it does so comprehensively for both the members array and the invitation/seat data. Combined with the permission gate and the sibling routing, an agent has everything needed to call this 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter guidance and instead spends its words on return content, which is the right allocation here.

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

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

States a specific verb and resource (list the team) and immediately enumerates the exact information it surfaces: members with role, scope, shared sites, join and last-active times, pending invitations, and seat counts. It also names the resource it is NOT (incident alert recipients), 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?

Opens with concrete user-intent triggers ('who has access', 'what roles', 'who was invited', 'how many seats are left') and closes with an explicit exclusion plus the correct alternative ('Not for who was alerted about an incident: use get_incident'). It also states the access precondition ('Owners and admins only').

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, and the description adds genuine value beyond them: it enumerates what each delivery contains (event, timestamp, arrival, HTTP status, latency, attempt number, short failure reason) and, importantly, states what is NOT returned (payload, endpoint response body). Not stated: that results are capped/truncated and there is no pagination cursor, which matters given 'latest deliveries'.

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

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

Three sentences, front-loaded with the usage trigger before the return description, then closing with the negative routing. The middle sentence is dense but each item is a distinct fact. Minor cost: the return-field enumeration is a long comma list that could be trimmed.

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

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

With no output schema, the description carries the burden of describing return values and does so concretely, including the explicit absence of payload and response body. For a two-parameter read tool, an agent has everything needed to call it correctly and set expectations.

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

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

Schema coverage is 100%, so both parameters are documented by the schema itself, including that the limit defaults to 20. The description does not add syntax or behavior for the webhook identifier beyond what the schema says (id from list_webhooks or name). Baseline 3 applies since the schema does the work here.

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

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

Names a specific verb and resource (list a webhook's deliveries) and immediately states the scope: latest deliveries, newest first, for one webhook. It also clearly distinguishes itself from list_webhooks (all webhooks) and retry_webhook_delivery (resend), 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?

Gives an explicit triggering situation ('user asks whether a webhook or chat channel got a particular alert, why one is failing, or what was sent') plus two explicit exclusions naming the correct siblings. Nothing is left to inference about when to call this versus alternatives.

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

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

Annotations declare readOnlyHint=true with no contradiction, and the description adds context the annotations cannot: output is redacted to host only because the full URL often carries a credential, and the caller must be an owner or admin. That redaction and permission gating are exactly the behavioral facts an agent needs before summarizing results to a user.

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

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

Four sentences, each load-bearing: trigger, scope of destinations, returned shape plus the redaction rationale, then the exclusion. The trigger and the return description are front-loaded before the edge cases, so an agent skimming the first line already knows whether to 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?

With no parameters, no output schema and no nested objects, the description carries the full burden and does so: it explains what is listed, what each record contains, why one field is truncated, who may call it, and where to go for the adjacent need. Nothing required to invoke or 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?

Zero parameters, so the baseline is 4 and the description correctly spends no words on argument semantics. Its enumeration of return fields (host, events, sites, active/paused, delivery health) is a bonus rather than a substitute for parameter documentation.

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 webhooks') and enumerates the destination types covered (webhooks, Slack, Discord, Google Chat, Teams), plus what is returned for each. It is clearly distinguishable from the sibling get_my_notifications, which it explicitly names as the wrong tool for email alerts.

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

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

'Use this when the user asks where FlareWarden sends alerts besides email' gives an explicit trigger, and 'Not for the user's own alert emails: use get_my_notifications' gives an explicit exclusion with the alternative. It also states the access constraint (owners and admins only), which lets an agent rule the call out in advance.

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 that the call saves a plan and changes nothing in the account, and it describes exactly what the result reports (which sites would change, which are already in the target state, which cannot be changed and why). That correctly resolves the apparent tension between readOnlyHint=false and 'changes nothing', clarifying that the only write is the plan object itself. It stops short of noting whether plans expire or must be applied immediately via apply_bulk_pause.

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

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

Three dense sentences: purpose and scope first, then the return contract, then the exclusions. Every clause carries information an agent needs, and the routing information is front-loaded rather than buried.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the outcome categories and the plan id. Combined with a fully documented six-parameter schema including the nested answers object, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real targeting semantics by framing group / sites / all as alternative selection modes and clarifying that 'every site' means every site the user can change. The answers/plan_id decision-resolution flow is left entirely to the schema.

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

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

States a specific verb and resource ('pause or resume several sites at once') plus the accepted scopes: a group, a list, or every site. It names the sibling tools it is not (set_monitor_paused, draft_maintenance) with the condition that selects them, so the agent can distinguish it 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 explicit when-to-use with a concrete scenario ('during a migration or a move to a new host') and explicit when-not-to-use, naming both alternatives and their distinguishing conditions. 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?

Adds real provenance beyond the annotations: the check is evaluated against the live page at plan time, similar existing checks are surfaced, monitor cost is compared to remaining quota, and open decisions are returned for the user. 'Saves the plan and changes nothing in the account' correctly reconciles with readOnlyHint=false/destructiveHint=false. Idempotency and any auth requirements are unaddressed.

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 correctly with the trigger condition, but the return-value sentence is a five-clause semicolon run-on ('...or the automatic checks that hold there when no check is named; any check of the site...; its cost in monitors...; and the decisions...') that is hard to parse on one pass. Length is defensible given 13 params and no output schema, but the packaging costs readability.

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 13 parameters, no required params, and no output schema, the description carries the full burden of explaining returns — and it does: pass/fail of the live trial, text locations, automatic checks when none is named, duplicate-check detection, quota cost, and outstanding decisions. An agent has enough to select and 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%, including a very thorough selector description and an enum for check_type, so the schema already carries the parameter burden. The description adds only partial meaning — the severity/interval/name decision ids behind `answers` are hinted at ('the decisions to put to the user: how serious a failure is and how often to check') but no parameter is explained directly. 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 object ('plan/watch what a page says or shows') and enumerates the concrete check families (text/button presence, error absence, price range, change detection). It explicitly distinguishes itself from the nearest sibling: 'Not for whether the site is up: plan_site watches that.'

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

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

'Use this when the user wants FlareWarden to watch...' gives a clear triggering condition, and the closing clause rules out plan_site. It also covers the revise path ('plan_id ... to change it or answer its decisions') and the delegate path ('accept_recommended'). What it omits is routing to add_content_check for actually creating the check — the plan/apply relationship is implied by 'Saves the plan and changes nothing in the account' but never named.

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

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

Given readOnlyHint=false, the highest-value disclosure is that this 'Saves the plan and changes nothing in the account', which resolves the apparent write/read ambiguity an agent would otherwise face. It also discloses a hard constraint ('Cron expressions are read in UTC: there is no time zone setting') and previews the returned content. It does not address idempotency despite idempotentHint=false, e.g. whether re-running with the same inputs creates a second plan.

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 trigger condition is correctly front-loaded and the exclusion is placed at the end as a clean sign-off. The middle sentence about return values is a long, semicolon-chained run-on ('when the job runs, if the schedule given could not be read; then how late is too late...') that takes a second read to parse, which costs a point.

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

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

There is no output schema, yet the description still covers what comes back (schedule with next five runs in local time, monitor cost against remaining plan room, and open decisions), plus the UTC constraint and the no-account-change guarantee. For a six-parameter planning tool with nested `answers`, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump because it explains the decision loop behind the opaque `answers` object — the decisions are grace period, longest normal run and severity, and each has an id the user answers. It also clarifies `plan_id` semantics ('an earlier plan_cron_monitor plan, to change it or answer its decisions') beyond the schema's terser phrasing, though it adds little new on `schedule` formats.

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

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

The description opens with a concrete trigger — 'the user wants to know if a scheduled job, backup, queue worker or other background task stops running, runs late or fails' — naming the resource and the failure modes it detects. It also explicitly excludes the nearest wrong tool ('Not for checking a website or API endpoint: use plan_site'), so an agent can separate it from plan_site and plan_dependency 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?

Both directions are stated: the positive when-to-use condition up front and the negative case with a named alternative ('use plan_site'). It further indicates the resume path, since plan_id lets it amend an earlier plan or answer its decisions, which is the kind of routing guidance that prevents duplicate plans.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description resolves the apparent conflict by saying it "Saves the plan and changes nothing in the account". It also discloses that credentials are entered via a secure link and never in chat — a genuinely important behavioral caveat not in annotations. It stops short of describing idempotency or what happens on re-invocation with plan_id, so not a 5.

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

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

Front-loaded with the trigger condition, which is exactly where an agent looks first. It is dense and long, and the return-value sentence partly restates the status-page/plain-HTTP point made two sentences earlier, so a little trimming is possible — but virtually every clause carries new 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 9-parameter, nested-object tool with no output schema, the description supplies what's missing: what it returns (integration or HTTP check, monitor cost against plan headroom, then a sequence of decisions), the credential flow, and the no-account-change guarantee. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaning the schema doesn't: the interval defaults to the recommended value unless the user names another, decisions are answered "one step at a time" in a stated order (regions, components, severity), and accept_recommended never covers credentials. That is real added semantics for the answers/accept_recommended parameters, but several parameters (component_query, integration) get no extra treatment.

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 — planning a monitored dependency for a site — and covers both the new-site and existing-site cases. It explicitly routes the agent away from check_service_status("Not for checking whether a service is down right now"), so the boundaries against the most confusable sibling are clear 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 an explicit trigger ("Use this when the user wants FlareWarden to watch a third-party service a site relies on"), the two valid contexts, and a named exclusion with the alternative tool. The catalogue-listed vs. status-page vs. plain-HTTP handling is also stated as a condition, not 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 non-destructive, non-idempotent, open-world behavior, but the description adds context annotations cannot express: watches consume no monitor quota, a site is capped at 20, and the call saves a plan while changing nothing in the account. It also previews the return content (today's values plus the decisions to surface), so the agent knows what to do with the result.

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 trigger condition, and every sentence carries usable information (scope, return shape, quota cost, side effects, exclusion). It is dense—the return sentence crams values and decisions together—but there is 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?

With no output schema and a nested 'answers' object, the description carries the burden well: it describes what comes back, how the decision loop works across calls, and what side effects to expect. An agent can sequence this call and the follow-up without further information.

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 genuine meaning: omitting record types means 'see them all and decide,' and the 'answers by decision id: record_types, alert_on' semantics are explained in prose as the two questions to put to the user. That goes beyond the schema's one-line parameter notes.

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 (plan a DNS watch) and immediately scopes it with concrete examples: MX, _dmarc, SPF, and the CNAME a subdomain points at. It also explicitly separates itself from the site-uptime/DNS-health/certificate territory, which an agent could otherwise confuse with track_subdomain_certificate or diagnose_site.

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 opening clause gives a clear triggering condition ('when the user wants to know if DNS records change or stop resolving'), and the closing sentence gives an explicit when-not with a named alternative surface (FlareWarden's existing uptime/DNS health/cert checks). What is missing is a named next step for committing the plan (add_dns_watch), which the agent must infer from the plan_id/answers flow.

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 real context beyond the annotations: it persists a plan but changes nothing in the account, discovery is done from the site's DNS and page (explaining the openWorldHint), and the whole flow is two-phase. It does not discuss latency, failure modes, or what happens to a saved plan that is never answered, which keeps it off a 5.

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

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

Front-loads the trigger, then the return shape, then the side-effect contract, then the exclusion. The sentences are long and clause-heavy, but each carries distinct information; no filler or restatement of the name.

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

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

With 9 params, nested objects, no output schema and non-read-only annotations, the description supplies what is otherwise missing: the contents of the returned plan, the two-step confirm loop, and the guarantee that nothing in the account is mutated. An agent can call it correctly and know what to do next.

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 model-level meaning: url/urls are the one-vs-many split, plan_id drives the re-read/answer round trip, answers map to decision ids, and from_workspace entries are pre-selected and attributed to the assistant pending user confirmation. That goes beyond per-field text in the schema.

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

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

Names a specific verb and resource ('plan monitoring for a website or API', up to 50 at once) and immediately scopes it against the sibling family that handles single checks on already-monitored sites. An agent can distinguish plan_site from plan_dependency/plan_content_check/plan_cron_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?

Gives an explicit trigger ('when the user wants FlareWarden to monitor a website or API they run'), an explicit anti-trigger ('Not for adding a check to a site already monitored'), and names the three alternative tools to use instead. It also states the follow-up pattern: call again with the plan id and the user's answers.

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 declaring readOnlyHint=false but destructiveHint=false, the description resolves the apparent tension directly: 'Saves the plan and changes nothing in the account', i.e. it persists a plan artifact but mutates no account state. It also discloses return content (address suggestions with fallbacks, branding, components, plan limits, pending decisions) and that accept_recommended never publishes. It stops short of saying whether plans expire or how an earlier plan_id is superseded.

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 usage trigger and tightly packed, with no filler sentences. However the middle is a single very long clause chain listing return fields, which makes it harder to scan than two or three shorter sentences would be.

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 enumerating exactly what the call returns and what decisions come back to the user. Combined with 100% schema coverage on seven parameters, 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?

Schema coverage is 100%, so baseline is 3; the description goes further by spelling out the decision set the 'answers' object carries ('the address, which of the site's services to show, and whether to publish') and the fallback behaviour of the slug. It doesn't explain the precedence between top-level name/slug and the same keys inside answers, which is the one genuinely ambiguous relationship.

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 ('plan' / 'public status page for their customers, made from one of their sites or empty') and covers both input modes. It also separates itself from two neighbours: 'changes nothing in the account' distinguishes it from create_status_page, and check_service_status is named as the tool for another company's status.

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 first clause gives an explicit trigger ('when the user wants a public status page for their customers'), and the last sentence gives an explicit exclusion plus the alternative tool ('Not for another company's status: use check_service_status'). The publish-confirmation rule ('that needs the user's yes') is stated as a usage constraint.

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 beyond annotations by naming the actual side effects (status page publication, emails to subscribers/members/webhooks recorded on the draft) and the idempotency semantics ('same draft id posts once and returns the first result'), which annotations only flag abstractly as openWorld/destructive/idempotent. Missing only failure behavior or required permissions.

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

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

Four short sentences, front-loaded with the triggering condition, then effects, then idempotency, then the exclusion. 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?

For a 2-parameter destructive publish with a full schema and no output schema, it covers precondition, blast radius, idempotency, and return value ('Returns the incident'). Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so both draft_id (pl_ prefix, from draft_incident_post) and confirm (plan's confirm sentence) are already fully documented in the schema. The description adds no parameter-level 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 action (publish a drafted incident post) and characterizes it precisely against the dashboard's Incidents tab. Explicitly distinguishes itself from draft_incident_post with 'Not for changing the text: make a new draft.'

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 precondition ('when the user has approved a draft_incident_post draft's exact text and recipients') and an explicit exclusion routing agents to draft_incident_post for text changes. Both the when and the when-not are present.

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 read-only/open-world/non-destructive; the description goes well beyond by disclosing that it fetches from six regions, needs no sign-in, stores nothing about the user, and caches results per site for a day. Those are exactly the operational facts (privacy, freshness, cost) an agent cannot infer 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 trigger conditions, then behavior, then exclusions, then a doc link — a sensible ordering with essentially no filler. It is a single dense paragraph of considerable length, though, and would scan faster split into use/not-for/behavior lines.

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 itself and does so thoroughly: recognized services with per-service evidence and current status, certificate expiry, DNS summary, current uptime, viable page checks, and a per-plan monitor count. Combined with the caching and no-sign-in notes, an agent has everything needed to set expectations before calling.

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

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

There is a single parameter at 100% schema description coverage, which already documents accepted forms like 'https://example.com or example.com'. The description adds no further input guidance such as whether paths, ports, or non-HTML endpoints are accepted, so it neither helps nor hurts beyond the schema 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 (recommend what to monitor for a website) plus the concrete inputs it inspects (DNS records, home page, certificate) and the outputs it produces. It explicitly names the siblings it is not (check_service_status_url, and the signed-in plan/create tools), so an agent can distinguish it 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?

Opens with the exact user phrasings that should trigger it ('what should I monitor', 'what could take their site down', 'which third-party services a site depends on') and adds the pre-signup evaluation case. It also gives explicit exclusions with named alternatives: check_service_status_url for a bare up/down check, and the account plan/create tools once signed in.

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 flag destructiveHint and idempotent, but the description supplies the actual blast radius: a site takes its content, dependency and cron rows with it; a group alone moves its items to top level unless group_contents=remove; the underlying sites and checks stay monitored. That is exactly the context the destructive flag 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-loaded with the selection trigger, then consequence, then return value, then exclusion — a sensible order. Four dense sentences with no filler, though the group_contents sentence partially duplicates the schema's own description.

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

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

No output schema exists, and the description compensates by stating 'Returns what was removed and the page's components after.' Combined with scoping rules and the monitoring-continues caveat, an agent has everything needed to call this safely on a destructive 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 coverage is 100%, so the baseline is 3, and the schema already spells out group_contents in detail. The description still adds value by explaining the consequence of each component kind (site carries rows, group alone relocates items, check is just removed), but its group_contents wording largely restates 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?

Starts with a specific verb and resource: 'a site, check or group heading taken off one of their public status pages.' It also enumerates the three component kinds, which lets an agent distinguish this from update_status_page_component and add_status_page_component without reading 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 when-to-use ('when the user wants ... taken off a public status page') and explicit when-not ('Not for deleting a site, a check or the page itself, which is done in the dashboard'). It also supplies the side-condition that monitoring continues, which prevents an agent from reaching for a delete tool instead.

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 real context beyond the annotations: owner/admin authorization requirement, the fact that it returns the old and new name, and that it behaves the same as the Account page. It does not address the destructiveHint=true implication directly (that the previous name is replaced, even though it is echoed back) or idempotent behavior, but the authorization and return-value disclosures are substantive.

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

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

Three sentences, front-loaded with the trigger, then the effect and return value, then the exclusions. Every clause carries information; nothing is repeated from the annotations or schema verbatim.

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?

Single-parameter mutation with no output schema, yet the description covers the trigger, the authorization gate, the return value, and the disambiguation from the two nearest siblings. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description earns an extra point by giving the `name` field real semantics — it is the member-visible account name used in the sidebar, switcher, and invitations, which the schema's "new name, 1 to 100 characters" 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+resource (rename the FlareWarden account) and pins down exactly which name is affected: the one members see in the sidebar, account switcher, and invitations. It explicitly names what it is not for (a site's name, a status page's name) and routes to the correct siblings.

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

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

Opens with an explicit trigger ("Use this when the user wants the FlareWarden account's own name changed") and closes with two named exclusions plus the alternative tools to use instead (update_monitor, update_status_page). An agent can route correctly without opening any schema.

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

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

Adds real context beyond the annotations: it retries the same event as a new attempt, returns whether it arrived plus the HTTP status, and requires owners/admins. This corroborates idempotentHint=false rather than contradicting it. It stops short of mentioning rate limits or what happens on repeated retries, so it is not exhaustive.

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 tight sentences, front-loaded with the triggering scenario and ending with the exclusion. A small deduction for the slightly garbled phrasing 'a delivery a webhook or chat channel missed sent again', which takes a reread.

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

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

For a 2-parameter mutation with no output schema, the description covers the trigger, the alternative, the auth requirement, and return values. Nothing an agent needs to invoke or 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%; both params already explain where the id comes from (list_webhooks, list_webhook_deliveries). The description adds no parameter-level detail such as whether a name or id is preferred or how ambiguity is resolved, 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 (send again) and resource (webhook delivery), and explicitly distinguishes itself from the sibling test_webhook. The 'as the Webhooks page's Retry does' framing anchors the semantics for an agent familiar with the UI.

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

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

Gives the triggering condition ('user wants a delivery a webhook or chat channel missed sent again, once the endpoint is fixed') and an explicit exclusion with the correct alternative ('Not for a test event (use test_webhook)'). Both when-to-use and when-not-to-use 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 cover readOnlyHint and destructiveHint, but the description adds real context: 'Changes nothing in the account', the dismissal affordance via dismiss_suggestion keys, and notably the background DNS/home-page read for stale sites explained by 'a later call includes what that finds' — which justifies the non-idempotent hint. This is disclosure beyond structured fields; only the lack of ordering/pagination detail 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?

The usage trigger and the alternative are front-loaded, and every sentence carries information. The long enumeration of gap categories is dense but earns its space as the only place the return contents are described.

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 specifies the return shape — gaps worst-first, each paired with the fixing tool and an optional dismiss_suggestion key — plus the latency caveat about background reads. An agent has everything needed to call 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?

Schema description coverage is 100%, so both parameters are already documented as filters. The description adds no syntax or scoping semantics for site/group beyond implicitly framing results as account-wide. Baseline 3 is appropriate since the schema carries the 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 ('review') and enumerates the exact gaps returned: unwatched services, certs expiring in 30 days, sites on no status page, thin alerting, long-paused monitors. It explicitly distinguishes itself from get_account_overview, so an agent can separate it from siblings 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?

Opens with an explicit trigger list ('when the user asks what they are not monitoring, what could break without them knowing...') and closes with a hard exclusion plus the named alternative: 'Not for what is down now: use get_account_overview.' Both when-to-use and when-not 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?

The description adds substantial context beyond the readOnly/destructive annotations: it says changes nothing, defines the 7- and 30-day windows, states the results are worst-first, and enumerates the kinds of noisy-monitor findings returned with suggested changes and follow-up tools. Since no output schema exists, this return-value detail is especially valuable.

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

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

The description is dense but front-loaded: it opens with the user situations that select the tool, then summarizes results, then states the no-change behavior, then closes with exclusions. Every sentence carries useful selection or behavioral 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 read-only review tool with no output schema, the description sufficiently explains scope, time windows, ordering, result categories, and recommended follow-up tools. The only minor omission is parameter filtering detail, but that is fully covered by 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 the site and group filters are already fully documented in the input schema. The description does not add further meaning about how site or group filtering interacts with the results, so the baseline 3 is appropriate.

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

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

The description states a specific purpose through clear user questions: why a site keeps alerting, which monitors are noisy or flapping, and whether alerts were false alarms. It also distinguishes the tool from siblings by naming get_account_overview, diagnose_site, and review_coverage with their respective roles.

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 explicit trigger scenarios and example user questions, then names alternatives for adjacent needs: get_account_overview or diagnose_site for current outages, and review_coverage for unmonitored resources. This provides both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior: the emailed link stops working, nobody is emailed, the operation is restricted to owners and admins, and it reports back which invitation was cancelled.

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 short, front-loaded with the trigger, and every sentence carries useful information. The trailing clause 'and the result gives the link' is slightly redundant with the earlier statement that it returns which invitation was cancelled, which is the only reason it falls short of 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 one required parameter, no output schema, and full annotation coverage, the description still states the return value, the authorization requirement, and the side effects. Nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents that the parameter is an invitation id from list_team or an invited email address. The description adds no syntax, format, or disambiguation beyond that, 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 states a specific verb and resource ('withdraw an invitation that has not been accepted yet') and explicitly scopes out the adjacent case of removing someone who already joined, directing that to the dashboard. An agent can distinguish this from invite_member, change_member_access, and list_team 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?

It gives an explicit trigger ('when the user wants to withdraw an invitation'), an explicit exclusion ('not for removing someone who already joined'), and names where that other case belongs (the dashboard). This is a complete when/when-not/alternative statement.

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 externally visible side effects: the window shows on status pages and subscribers are emailed only if the draft said so — the email blast is the highest-risk behavior here and annotations say nothing about it. It also states the return shape and clarifies the idempotentHint with a concrete mechanism ('the same draft id schedules once'), rather than relying on the flag 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?

Front-loaded with the trigger condition, then behavior, then return, then the negative routing case — the most decision-relevant facts come first. Four tight sentences with no filler; even the return-shape clause earns its place because 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?

For a 2-parameter mutation with no output schema, the description covers precondition, external side effects, return value, retry semantics, and the routing alternative — everything an agent needs to call it correctly. 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 description coverage is 100%, so both parameters are already documented, and the description adds no format or origin detail beyond the schema's own note that draft_id comes from draft_maintenance. Baseline 3 applies since the schema carries the semantic load for confirm and draft_id.

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: it takes an approved draft_maintenance draft and schedules it as a maintenance window. The description also names the counterpart tools (draft_maintenance as the source, update_maintenance as the alternative), so an agent can distinguish it from the ~60 siblings without opening the schema.

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

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

Explicit precondition ('when the user has approved a draft_maintenance draft') and an explicit exclusion with the correct alternative ('Not for changing a window already scheduled: update_maintenance moves, extends, renames or ends it'). The repeat-safety note ('the same draft id schedules once') tells the agent what to do on retry.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds substantive non-annotation context: an authorization constraint ('Owners and admins only'), result ordering ('newest first'), and the shape of returned fields including the AI-agent 'via' attribution. It stops short of stating default time scope or result-set limits, so it is strong but not complete.

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

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

Three compact sentences: trigger, returned data, exclusions. The routing condition is front-loaded and the sibling exclusions close it out, with no redundant restatement of the title or name.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does: ordering, time, member, action, changed object, and 'via' for AI-agent changes. Combined with the permission note and sibling routing, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so every one of the six parameters is already documented with format hints (YYYY-MM-DD dates, 25-per-page paging, action naming like monitor.pause). The description adds no parameter-level syntax or constraints beyond what the schema provides, which is the baseline-3 case.

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

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

States a specific verb+resource (search the audit log) and frames it with the exact user intent it serves: 'who changed something in the account and when,' backed by concrete examples (who paused a site, who invited someone, what an AI agent did). Sibling tools are named by contrast, 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?

Explicit when-to-use is front-loaded, and exclusions are precisely named with alternatives: 'Not for monitoring history or incidents: use get_monitor_history or list_incidents.' Both the positive trigger and the negative routing condition are present, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered and the description is free to add value — which it does by disclosing the external doc source and that results come back as passages plus page links, information absent from any structured field. Minor gaps: no mention of behavior when nothing matches or of documentation coverage 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?

Two sentences: the trigger condition with illustrative examples comes first, the mechanism and return shape second. No preamble, no restatement of the title, nothing removable.

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 tool with full schema coverage and annotations but no output schema, the description supplies the trigger, the data source, and the shape of results. Only the no-results/edge-case behavior is unaddressed — a small gap given everything else already provided.

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 both `query` ('The question or keywords, in the user's words') and `limit` (default 5, max 10) documented inline, so the baseline is 3. The description's example queries loosely illustrate how to phrase `query`, but it adds no constraint or format guidance beyond the schema.

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

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

States a specific verb (searches) and resource (documentation at flarewarden.com/docs) and even describes the return shape ('best-matching passages with links to their pages'). It does not differentiate from the plausible sibling explain_features, so an agent must still infer which of the two answers conceptual vs. procedural questions.

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

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

'Use this when the user asks how to do something in FlareWarden' gives a clear trigger condition, reinforced by five concrete task examples (custom domain, Slack alerts, cron heartbeat, probe IPs, inviting a teammate). It stops short of naming alternatives or when-not-to-use cases, so there is no explicit boundary against explain_features.

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 this is a non-destructive, non-open-world read, so the safety profile is covered. The description adds result-level behavior the annotations can't: matching services come back with category and status page, plus FlareWarden's own public status page when one exists. It stops short of describing match semantics (exact vs. partial) or empty-result behavior, which keeps it below a 5.

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

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

Three sentences, each doing distinct work: trigger, return shape, and exclusion. The trigger is front-loaded, so an agent can decide on the first sentence alone, and there is 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?

There is no output schema, so the description carries the return-shape burden and does so concisely (matches + category + status page). For a single-parameter lookup tool with full annotation coverage, that is near-complete; only ambiguity around partial matching and no-match results remains.

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%, including an example value ('such as Stripe or AWS'), so the parameter is fully self-documenting. The description contributes only the indirect hint that matching is non-exact ('Returns matching services'), which is marginal added meaning over 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?

The description states a specific verb and resource ('search the services FlareWarden can watch') and frames the exact user intent it serves: 'whether FlareWarden can watch a third-party service their site depends on'. It enumerates concrete service kinds (payment provider, cloud, CDN, email, auth), which makes it instantly distinguishable from catalog-adjacent siblings like check_service_status.

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

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

It gives an explicit trigger ('Use this when the user asks whether FlareWarden can watch...') and an explicit exclusion with the correct alternative named ('Not for whether a service is down now: use check_service_status'). That is the when/when-not/alternative pattern at full strength.

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 the quota cost ('costs one monitor; turning it off frees it'), the 3-day learning period before reporting, and the return payload. It leaves one gap relevant to destructiveHint=true: whether turning detection off discards the learned baseline, which an agent would want to warn the user about before disabling.

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

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

Four compact sentences, front-loaded with the trigger and exclusion, followed by cost and learning-period caveats. No filler and no repetition of the schema.

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

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

For a mutation toggle with no output schema, it covers trigger, exclusion, quota cost, learning latency and return values — close to complete. The remaining unknown is state loss on disable, which matters given destructiveHint=true.

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 explains site, check, enabled and the sensitivity enum in detail. The description only lightly reinforces that enabled=true doubles as the sensitivity-change path; it adds no format or scoping detail beyond the schema.

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

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

States a specific verb and resource (turn FlareWarden anomaly detection on/off or adjust sensitivity) covering both the site-response-time and cron-runtime variants. It explicitly demarcates itself from ordinary up/down alerts, so an agent can distinguish it from update_monitor or set_monitor_paused without reading either schema.

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

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

Gives a clear triggering condition ('when the user wants ... to alert on unusual response times ... or to stop doing so or change how sensitive it is') plus an explicit exclusion ('Not for ordinary up or down alerts'). It stops short of naming the sibling tool to use instead for static thresholds, so the routing is implied rather than complete.

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 past the annotations (destructiveHint=true, idempotentHint=true) by disclosing the actual blast radius: checks, content checks and dependencies stop, DNS watch alerts are held, open automatic incidents resolve, and cron jobs keep alerting until individually paused. It also states the non-obvious constraints that pausing frees no plan room and resuming must fit the plan's active monitors — exactly the side effects an agent needs before committing a destructive 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?

Front-loaded with the usage trigger before the behavioral detail, and nearly every clause carries distinct information. It is a single dense sentence chain, and the lead-in 'Returns the new state and what it means' is slightly awkward phrasing for what follows, but there is 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?

Only 3 flat parameters at full schema coverage and no output schema, so the description's job is behavioral and it covers it fully: preconditions, cascade effects, what cron monitors do, plan-capacity implications, and explicit pointers away from the tool. Nothing an agent needs to call this destructive, idempotent operation correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the semantic difference between the site-level and check-level scope (site pausing cascades to checks and dependencies, cron jobs are separate). It does not add matching/format hints beyond the schema's 'id, name or part of its URL', but the cascade semantics are real added meaning.

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

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

States a specific verb pair (stop/restart) on a specific resource (checks of a site or one of its checks) and immediately scopes it against siblings: 'Not for scheduling maintenance windows or deleting a monitor.' An agent can distinguish this from update_monitor, apply_bulk_pause, and schedule_maintenance 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 a concrete triggering condition ('when the user wants to stop or restart checks... for example during planned work') plus explicit exclusions (maintenance scheduling, deletion) redirected to the dashboard. It stops short of naming the in-product sibling apply_bulk_pause or schedule_maintenance as the alternative for bulk/planned-work cases, which would have made routing unambiguous.

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