LastPing

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), it discloses the auth requirement (write scope or higher), the append-only nature with no edit/delete path, the 50-note cap, acceptance on closed incidents, and the author value. This is exactly the mutation-behavior context annotations cannot convey.

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

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

Six sentences, each carrying distinct information, with the action and permission prerequisite front-loaded before the behavioral details. No restatement of the name or title 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 two-parameter mutation tool with no output schema, the description covers permissions, mutation semantics, capacity limits, edge cases (closed incidents), and the value proposition of the note. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds one genuinely useful clarification the schema cannot: there is no author argument, so the agent should not attempt to supply one. The remaining parameter meaning (incident_id integer, body content/limits) is already fully documented in the schema.

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

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

The first operative sentence states a specific verb and resource ('Adds a diagnosis note to an incident') and immediately pins down the unique semantics of the operation (append-only, stored with author 'agent'). No sibling tool overlaps with adding notes, so an agent can place this without ambiguity.

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 strong contextual guidance on when this applies: several notes per incident are normal, a closed incident still accepts notes, and a note may record an unfixed failure. It never names an explicit alternative or exclusion, but the write-scope prerequisite and the 'without a note the page shows only the alert' framing make the trigger condition clear.

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

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

Goes well beyond the annotations: it states the required write scope, discloses that earlier traces are NOT backfilled, and documents the specific 409 failure modes (AGENT_EXISTS, ALREADY_ADOPTED) that an agent must anticipate. The idempotency nuance matches idempotentHint=true without contradicting it.

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 permission requirement and the core behavior, and most sentences carry actionable semantics. The closing sentence about `untrusted_fields` names no parameter in the input schema, making it the one item whose placement is questionable.

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

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

For a two-parameter mutation with no output schema, the description covers auth scope, backfill behavior, and error conditions thoroughly. It never says what the call returns (e.g. the adopted or created agent id), and the `untrusted_fields` reference is unexplained, so a small gap 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 already 100%, so the baseline is 3; the description adds value by clarifying the merge-versus-create decision, the 409 AGENT_EXISTS consequence of omitting agent_id, and where a suggested id can come from. It does not add anything about the `id` parameter 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?

Opens with a specific verb+resource+effect: 'Counts a discovered trace source's traces under an agent from now on.' This clearly distinguishes it from register_agent (manual) and list_discovered_agents (read), and the title reinforces the same idea.

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 branches on the primary decision: 'Without agent_id, a new agent named after the source is created' versus 'With agent_id (e.g. a suggested_agent_id), the source merges into that agent,' and it names the alternative source of a suggested id. It further covers re-adoption cases and their outcomes, 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 only cover the safe-write profile (destructive=false, idempotent=false); the description goes well beyond them by disclosing that the plaintext key is shown once and is unrecoverable, that expires_at defaults to 90 days and is capped at the creating key's expiry, and that a scope above the creating key's is refused with the ceiling named in the error.

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 scope prerequisite followed by behavior and the alternative route. Every sentence carries a distinct fact (permission, effect, one-time secret, routing), 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?

There is no output schema, so the description carries the return-value burden and does so by explaining that the plaintext key appears only in this result. Combined with the scope precondition, expiry defaults and 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?

Schema description coverage is 100%, so the schema already documents name, scope, check_id and expires_at in depth (including the 90-day default, the expiry cap, and the ingest/check_id binding). The description largely restates that ("expires_at makes a short-lived key"), adding little semantic meaning the agent could not read from the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Creates an API key") and immediately differentiates it from the sibling create_ingest_key, which mints a narrower single-monitor key. An agent can pick between the two credential-creation tools 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?

"Requires the admin scope or higher" sets the precondition up front, and the closing sentence names the alternative (create_ingest_key) plus the condition that selects it (only the write scope, single-monitor tracing). That is explicit when-to-use and when-to-use-something-else 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?

Goes well beyond the annotations: discloses the 25-destination cap and DESTINATION_CAP_REACHED error, the email verification flow, the 'unrelated fields are ignored' behavior, and the returned channel id. These are exactly the operational facts an agent needs that annotations do not 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-loads the scope requirement, then the core behavior, verification nuance, cap, and return value in four tight sentences. Slightly dense but no wasted clauses.

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

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

Covers auth requirement, kind-dependent behavior, cap/error, and return value — the essential facts for an 11-param creation tool. Missing only minor details like whether the returned id is used elsewhere beyond set_route, but it is essentially 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% and the schema already documents each field per-kind in detail. The description adds the useful 'from the fields of the chosen kind; unrelated fields are ignored' rule, but otherwise defers to 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 and resource ('Creates a notification destination (channel) that monitors can route alerts to') and ties it to siblings like set_route and list_destinations. An agent can immediately distinguish this from update_destination or test_destination.

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

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

Explains prerequisites ('Requires the write scope or higher'), the kind-dependent immediate-vs-verification flow, and mentions set_route as the consumer of the returned id. It does not explicitly name create vs update alternatives, but the routing to set_route gives clear downstream context.

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

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

Goes well past the annotations (which only supply readOnly/destructive/idempotent hints) by disclosing the required write scope, the constrained capability of the resulting key, and the security-relevant fact that the plaintext key is returned exactly once and lands in the conversation. This is exactly the kind of side-effect context an agent needs before invoking a mutation.

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 permission requirement, then the artifact definition, then the use case, then the exposure caveat. Every clause carries distinct information; there is no filler despite the density.

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 describing the return ('the plaintext key appears only in this result'), plus scope, lifetime behavior implied by the schema, and the comparison to the console path. An agent has everything needed to call this safely and 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 name, expires_at and monitor_id are already fully documented with formats and defaults. The description reinforces the one-monitor binding but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource and then defines the artifact precisely ('an ingest-scoped key bound to one monitor, able to send traces, metrics, logs and pings for it and nothing else; every REST call refuses it'). This definition cleanly separates it from the sibling create_api_key without requiring the agent to open 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 when-to-use condition ('For automation that stores the key itself (a CI secret, a deployment's secret store)') and an explicit when-not via the console alternative that keeps the plaintext out of chat. It does not, however, contrast against the sibling create_api_key, so routing between MCP options is left partly 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 cover the safety profile (destructive, idempotent), yet the description adds real value beyond them: the write-scope requirement, the upsert result signaling 'updated', that ci_provider is settable only here, and that the webhook secret is returned only in this result and never readable again.

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 scope requirement and the core upsert behavior, then grouped by monitor type. Dense but every sentence carries information; a slight compression could improve scannability given the sentence count.

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 29-parameter tool with no output schema, the description covers the critical one-time-secret behavior and the upsert result, and the 100%-covered schema plus annotations handle parameters and safety. It could note pagination/return shape, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics beyond any single field: the schedule_kind-to-type mapping and the healthy-response logic when neither probe_expected_status nor probe_expected_body is set. It earns above baseline without fully restating the schema.

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

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

States a specific verb+resource ('Creates a monitor') and precisely extends it with upsert semantics keyed on slug. It is clear what the tool does, but it never explicitly differentiates itself from the sibling update_monitor (e.g. 'use update_monitor to modify without creating'), leaving the boundary to be inferred.

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?

'Requires the write scope or higher' gives a clear permission prerequisite, and it explains which parameters apply per monitor_type/schedule_kind, giving strong context for correct invocation. It stops short of naming the alternative tool (update_monitor) or stating when NOT to use this one.

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

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

Annotations already declare it is a non-readonly, non-idempotent, non-destructive write. The description adds genuinely new behavior: the write-scope auth requirement and the significant side effect that 'public' publishes every monitor name. It does not mention uniqueness/409 behavior or irreversibility, keeping it below 5.

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

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

Three tight sentences, front-loaded with the auth prerequisite, then purpose, then the visibility caveat. 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?

For a 4-param mutation tool with full schema coverage and annotations but no output schema, the description supplies prerequisites and side effects an agent needs. Return-value expectations are the only real gap, which is minor 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 description coverage is 100%, so all four parameters are fully documented in the schema (slug rules, title, check_ids cross-project constraint, visibility semantics). The description adds no parameter detail beyond what the schema already provides, so the baseline 3 applies.

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

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

Specific verb+resource, and it goes beyond the name by defining what a status page is: a page showing current status and recent history of chosen monitors, aimed at people who cannot log in. This is clearly distinguishable from create_monitor or update_status_page.

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?

States the prerequisite 'Requires the write scope or higher' and gives the key decision context (private vs public visibility and its exposure consequence). It does not explicitly name alternatives like update_status_page, so it falls short of a 5.

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

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

Beyond the annotations it discloses a lot: the required write scope, the grading consequence (a success failing any criterion is logged as a failed run with cause 'assertion' regardless of exit code), immutability and one-declaration-per-rid, and the dependency on the /start ping. This is exactly the behavioral context annotations cannot convey.

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

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

Front-loads the scope requirement, then behavior, then constraints and usage in a few dense sentences, each earning its place. Slightly long/compound sentences keep it from a 5, but there is no wasted 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 declaration tool with no output schema, the description covers scope, timing, semantics, immutability and a pointer to an example, which is nearly everything needed to invoke it correctly. It does not describe the success response or error surface beyond the conflict case, a minor gap.

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

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

Schema description coverage is 100% and the schema already exhaustively documents rid, check_id and assertions (kinds, ops, limits, malformed handling). The description adds framing ('criteria its success ping body is judged by') but no parameter syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: it 'Declares, at the start of a run, the criteria its success ping body is judged by when the run closes.' An agent can immediately tell this is a run-scoped assertion-registration tool, distinct from siblings like get_run, list_runs or get_ping_instructions.

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

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

Gives clear timing ('right after the run's /start ping') and points to 'get_ping_instructions' expectations_how_to' for a worked example, which is strong routing context. It stops short of an explicit when-not-to-use or alternative-tool exclusion, so it falls just below the top band.

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

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

Adds substantial context beyond the destructiveHint/idempotentHint annotations: the required scope, the irreversibility ('cannot be undone'), and the non-obvious cascading behavior that monitors survive, become unowned (agent_id null), and keep running with history intact. That cascade is precisely what an agent needs before calling a destructive tool.

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

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

Two dense sentences with zero filler: authorization and irreversibility lead, then the monitor-survival consequence and the tools that handle survivors. Nothing is repeated or padded.

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

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

No output schema exists, and the description nevertheless explains the post-deletion state of dependent resources and which tools act on them. For a one-parameter destructive tool, 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% for the single 'id' parameter, and the schema already documents that it is an agent UUID from register_agent or list_agents. The description adds only 'by UUID', so the schema does the heavy lifting and 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 ('Permanently deletes an agent from the registry by UUID'), which cleanly separates it from get_agent, update_agent, and list_agents. The 'permanently' qualifier also distinguishes it from reversible mutations like update_agent.

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 prerequisite ('Requires the write scope or higher') and routes the agent for the follow-on case, naming update_monitor and delete_monitor for surviving monitors. It never explicitly says when not to use this tool (e.g. prefer update_agent to merely change an agent), so it falls just short of 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantially more: the write-scope auth requirement, irreversibility ('cannot be undone'), and the crucial consequence that routing removal causes silent non-notification with no incident. That silent-failure warning is exactly the kind of behavioral context annotations cannot convey.

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

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

Four tight sentences, front-loaded with the scope requirement, then consequence, then alternative. No sentence is filler; each adds auth, risk, or routing context.

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

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

For a destructive one-param tool with no output schema, the description supplies everything needed: permission level, reversibility, blast radius, silent-failure risk, diagnostic sibling, and a non-destructive alternative.

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

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

Schema coverage is 100% for the single `id` parameter, which the schema itself documents as a Destination UUID from list_destinations. The description adds no syntax or format detail 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?

States a specific verb (permanently deletes) and resource (notification destination/channel), with a parenthetical clarifying what a destination is. It is distinguishable from siblings like delete_route, update_destination, and set_route 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 routes the agent to alternatives: get_monitor's `routes` to inspect what points at the destination, and set_route to change routing without deleting. It implies when to delete versus re-route, though it never states an explicit 'when to use this' or an exclusion case.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes well beyond them by enumerating the exact cascade: pings, run steps, traces, incidents, routes, alert templates, assertions, delivery history, plus bound ingest keys that stop working. That is precisely the 'what gets destroyed' context an agent needs before calling a destructive tool.

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

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

A single dense sentence pair with zero filler; the permission prerequisite and irreversibility warning are front-loaded, and the cascade list is the longest part because it carries the most decision value.

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

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

For a single-param destructive tool with no output schema, the description covers permissions, reversibility, and full cascade impact, while annotations cover the safety profile. Nothing an agent needs in order 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 description coverage is 100% and the single parameter is already documented as 'Monitor UUID.' The description only restates 'by UUID,' adding no format, source, or lookup guidance beyond the schema - baseline 3 is appropriate.

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

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

States a specific verb and resource ('Permanently deletes a monitor by UUID') with the scope of the operation made explicit. This cleanly separates it from the other delete_* siblings (delete_agent, delete_route, delete_destination, delete_status_page) without needing to name them.

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

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

Gives the prerequisite ('Requires the write scope or higher') and a strong irreversibility warning, which implies caution before use. However, it never addresses the obvious less-destructive alternatives in the sibling set - pause_monitor, snooze_monitor, or update_monitor - which an agent should consider before a permanent delete.

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 and idempotentHint, and the description adds real context beyond them: the required auth level ('write scope or higher'), exactly what is destroyed (routing for one event type, alerts going nowhere), and what is explicitly left untouched (every other event type's routing). It also documents the failure response text, which annotations cannot convey.

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

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

Three dense sentences with no filler, each carrying distinct information (auth, effect, alternative, error). It is slightly back-loaded: the leading permission note delays the core purpose statement, which would be stronger 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, yet the description covers auth requirements, the exact destructive scope, the unaffected state, the alternative tool, and the error surface. Combined with annotations covering idempotency, an agent has everything needed to call this correctly and safely.

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

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

Schema description coverage is 100% and the event_type enum is fully documented in the schema, so the baseline is 3. The description does add semantics by framing the pair as the monitor/event-type key into a routing mapping and by explaining what a missing route means, but it adds no format or value-level 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 with precise scope: 'Stops routing one event type of a monitor to any destination.' It clearly distinguishes itself from set_route by contrasting scope (whole event type vs. a single destination), so an agent can select it without opening the sibling 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 the alternative explicitly ('set_route with the remaining ids drops a single destination instead') and describes the no-op/error condition ('An event type with no routing answers "route not found"'). It lacks an explicit when-to-use scenario (e.g., permanently stop alerting for an event type), but the routing between the two tools is unambiguous.

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, it discloses that deletion is permanent and irreversible, that the public URL stops working immediately, and that monitors continue running and alerting. It also states the required write scope, giving the agent a complete behavioral picture for a destructive operation.

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 four short sentences with no waste, front-loading scope and permanence before side effects and the alternative. Every sentence carries actionable information.

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

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

For a simple, one-parameter delete tool with annotations and full schema coverage, the description supplies the missing behavioral context: auth scope, irreversibility, URL impact, monitor impact, and the safer alternative. No output schema exists, so return values do not need explanation.

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

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

Schema coverage is 100%, and the single id parameter is already documented in the schema as coming from list_status_pages. The description adds no further parameter meaning, which is acceptable given the high schema coverage but does not raise it above the baseline of 3.

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

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

The description states a specific verb (permanently deletes) and resource (status page), clearly distinguishing this tool from list_status_pages, create_status_page, and update_status_page. It also names the sibling update_status_page as the non-destructive alternative, so an agent can route correctly without opening 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?

It explicitly gives the alternative: update_status_page with visibility 'private' stops sharing without deleting. This tells the agent when to choose deletion versus a reversible change, and the required scope is stated up front.

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 (idempotentHint, destructiveHint=false) by spelling out that no existing monitor is deleted, paused, or edited, that hand-tuned values stay intact, that orphaned sources keep running/alerting, and that there is no delete path. It also discloses the source_ref stability trap that silently creates duplicates.

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 scope requirement and the core action, and every sentence carries information. It is dense to the point of being a wall of text, and some tz detail sits awkwardly after the kind list, but nothing is truly wasted.

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

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

For a single-parameter tool with no output schema, the description supplies the return contract (created/existing/orphaned) and the safety profile an agent needs. Batch limits live in the schema and the destructive/idempotency picture is fully covered, leaving no material gap.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning the schema lacks: source_kind+source_ref as the diff key, the stability requirement on source_ref, the enumerated kind values, and the local-time vs UTC firing rules per kind.

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: turning a scan of a repo/host into monitors, creating one per unmonitored source. It distinguishes itself from single-target siblings like create_monitor by describing the batch diff/reconcile semantics and naming list_monitors for the read-side view.

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

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

Gives clear context (after a repository/host scan) and the recommended cadence (a scheduled re-run is safe drift detection), plus the write-scope prerequisite. It stops short of explicitly naming when to prefer create_monitor instead, so no explicit exclusion is provided.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by disclosing that secrets are omitted and surfaced as Terraform variable references, and that import blocks exist to adopt rather than recreate resources — real behavioral context an agent could not infer.

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; the permission prerequisite is front-loaded, followed by scope, then the secret-handling caveat. No filler and 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?

With no output schema, the description compensates by characterizing the return (HCL plus import blocks, secrets replaced by variable references) and the auth requirement. Nothing essential to 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?

Schema description coverage is 100%, so tag, include, and monitor_slug are fully documented in the schema. The description contributes no additional parameter semantics beyond what the schema already states, making the baseline 3 appropriate.

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

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

Specific verb (Exports) plus enumerated resources (monitors, destinations, routes, alert templates, status pages) and the output format (Terraform HCL). No sibling tool does export, so it is trivially distinguishable from the create/update/list/delete family.

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?

States a prerequisite ('Requires the read scope or higher') and frames the intended outcome (adopted rather than recreated). It does not name when-not to use it or point at a sibling alternative, but for a unique export capability that guidance is largely unnecessary.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful non-obvious context: the required read scope, the field shape including live status rollup and usage_24h, and especially the semantics of `untrusted_fields` explaining provenance. That last detail is behavioral context an agent couldn't infer from the schema.

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

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

Three sentences, front-loaded with the permission requirement, then the return shape, then the untrusted_fields caveat. Efficient and each sentence carries distinct information, though the untrusted_fields sentence is denser than needed.

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

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

For a single-entity read with full schema coverage and full annotations, the description adds the return-shape summary and the provenance caveat, which is more than most tools at this level. Without an output schema the untrusted_fields note is particularly valuable. Missing only explicit guidance on when to prefer get_agent_usage/get_agent_dependencies.

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

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

Schema description coverage is 100% and the single param is documented ('Agent UUID, from register_agent or list_agents'). The description repeats the UUID-source hint but adds no format or validation details. 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 ('Gets one agent by UUID') and names the field set it returns, which ties it to list_agents. It distinguishes itself from get_agent_usage and get_agent_dependencies by mentioning those fields inline, but doesn't explicitly rule out those siblings as alternatives.

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

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

The description implies usage ('gets ONE agent by UUID' vs list_agents' plural) and notes the UUID comes from register_agent or list_agents. But it doesn't explicitly state when to use this vs get_agent_usage or get_agent_dependencies, which likely return overlapping subsets of the same data.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the 50-row cap with a `more` counter, that `operations` are sampled from the ten newest traced runs (up to five span names per row), the p95 floor caveat above 60s, and that `untrusted_fields` marks externally-written `data`. These are exactly the operational traits an agent needs and cannot get from annotations.

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

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

Front-loads the scope requirement and is dense but earns most of its length by enumerating return fields in the absence of an output schema. The single long clause-list is efficient, though 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 carries the full burden of describing return values and does so thoroughly: field list, metric semantics, sampling, truncation, and data-provenance caveats. Combined with the auth requirement, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so `id`, `range` (with default and UTC-day overlap behavior) and `direction` are fully documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource and scope ('What one agent calls, heaviest first, from its traces'), so an agent knows this is a per-agent dependency listing rather than a global one. It implies the singular scope that separates it from list_dependencies, but never names that sibling explicitly.

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

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

Provides the access precondition ('Requires the read scope or higher'), which is genuine usage guidance, but gives no when-to-use/when-not framing or routing to alternatives like list_dependencies or get_agent_usage. Usage is implied rather than stated.

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

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

Annotations only cover the read-only/idempotent safety profile, yet the description adds substantial non-obvious behavior: cost_source enumeration, origin traces/metrics being never summed, the by_project vs. per-agent cost mismatch, project_scope traces_only, and the meaning of untrusted_fields.

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

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

The permission requirement is front-loaded, but the remainder is a single semicolon-chained wall of text that is hard to parse. Every clause carries information, yet the lack of segmentation hurts scanability.

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 carries the burden of explaining the return shape: the field list, cost_source values, origin semantics, by_agent/by_project structure, and untrusted_fields. Nothing essential for correct interpretation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining interactions the schema omits: project narrows days and by_project but not by_agent, and id scopes to one agent's usage (traces only) versus the project's.

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

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

States a specific verb and resource with its granularity: 'Model usage, one row per model per UTC day', then enumerates the exact returned columns. An agent can tell this apart from get_agent or list_agents immediately.

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 precondition ('Requires the read scope or higher') and the branching behavior of id vs. no id, plus the project scoping rule. It does not explicitly name a sibling alternative, but the conditional scoping guidance is unusually clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds real value beyond that: the auth scope requirement, the exact return structure, and crucially the semantics of an empty result ('every alert uses the built-in plain-language defaults'), which is a diagnostic insight an agent cannot get from the schema or annotations.

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

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

Front-loads the auth requirement, then the return shape, then the key enumeration, then the empty-result meaning. The key list is long but each enumeration maps directly to a possible template key, so it earns its space. Slightly dense, but no wasted sentence.

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

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

With no output schema, the description fully compensates by explaining the return value as a key-to-template-string map, enumerating the valid keys and cause format, and describing the empty-result case. An agent has everything needed to interpret the response without opening anything else.

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

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

Schema description coverage is 100% with a single fully-documented parameter ('id': 'Monitor UUID.'), so the schema carries the parameter burden. The description adds no extra meaning about the id beyond what the schema already says, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Gets a monitor's custom alert message templates') and immediately defines the concrete return shape as a map of event-type keys to template strings. It is clearly distinguishable from the sibling set_alert_template, which is the write counterpart.

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

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

The description gives a prerequisite ('Requires the read scope or higher') but never states when to call this versus set_alert_template or update_monitor, nor any when-not condition. Usage is implied by the tool name and the read-only nature of the operation rather than being spelled out.

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

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

Beyond the readOnly/idempotent annotations, the description discloses non-obvious behaviors: the required read scope, the fact that run_* events are matched on the run id captured at opening (so absence means no run was recorded), that delivery error text is deliberately omitted, and that untrusted_fields flags data LastPing did not write. These are exactly the kind of gotchas annotations cannot carry.

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

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

Front-loaded with the precondition, then purpose, then behavioral caveats; every sentence carries information. The mid-sentence enumeration of timeline event types is dense but earns its place by telling the agent what to expect in the response.

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 itself must describe the return shape, and it does: the ordered event vocabulary, the destination/attempts detail, the alerts-only caveat, and the untrusted_fields semantics. An agent has enough to call and interpret 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?

A single parameter with 100% schema coverage, so the schema already documents incident_id and even its source (list_incidents, list_open_incidents, add_incident_note). The description adds no format or edge-case meaning for the id, so the baseline of 3 applies.

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

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

States a specific verb and resource — 'Gets one incident and its ordered timeline' — and enumerates the timeline event types, which separates it from the run-history siblings like get_run and get_run_history. It never names a sibling explicitly, so the differentiation is inferable rather than stated.

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

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

The framing 'For what the run was doing, who was paged and what was tried' implies the investigative use case, and the read-scope prerequisite is stated. However, there is no explicit when-to-use guidance versus list_incidents, list_open_incidents, or get_run, leaving the agent to infer which tool answers which question.

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 useful context beyond annotations: it mentions the read scope requirement, the exact fields returned (assertions, guards, routes), their semantics, and the fact that they are absent when empty. It also notes how update_monitor and set_route interact with these sets, which helps understand read-before-write patterns. Annotations already cover read-only, idempotent, non-destructive, so the bar is lower, and this adds meaningful detail.

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

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

Front-loaded with the core action and scope requirement. The description is dense but information-rich, with no obvious filler. Slightly longer than necessary but each sentence contributes useful context.

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

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

Given a simple read tool with one parameter, full schema coverage, and annotations covering safety, the description is nearly complete. It explains the returned fields and their relevance to update operations. It does not describe output format (no output schema), but for this read tool that is a minor gap, hence not a 5.

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

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

Schema coverage is 100% and the single parameter id is fully documented in the schema as 'Monitor UUID.' The description does not elaborate on the id parameter beyond what the schema provides, so baseline 3 is correct.

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

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

States a specific verb+resource: 'Gets one monitor by UUID with its full configuration.' This distinguishes it from list_monitors, create_monitor, update_monitor, etc. However, it does not explicitly name sibling alternatives for comparison, so it falls short of a 5.

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

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

Clearly implied when to use: when you need a monitor's current configuration by UUID. It also implicitly contrasts with update_monitor and set_route by noting that those replace whole sets while this returns current sets, which helps an agent decide whether to read first. No explicit exclusions or prerequisites beyond scope requirement.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context: the read-scope auth requirement, the conditional return of hook_install (only when `tool` is set, otherwise hook_install_note), the hook_install_note fallback, and the headerless /v1/traces POST endpoint. This is exactly the extra context annotations cannot carry.

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

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

The auth requirement is front-loaded, but the body is a dense wall of nested parentheticals and semicolon clauses that is hard to parse in one pass. Most content is informative, 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?

There is no output schema, so the description must carry the return-value burden, and it does: it enumerates ping URLs, the snippet names, the three reporting mechanisms, and auxiliary fields (failure_inbox_how_to, expectations_how_to, tracing_how_to, otel_env_lines, docs_url). An agent can act on this without further context.

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

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

Schema description coverage is 100%, and both params (including the `tool` enum) are documented in the schema itself, so the baseline is 3. The description largely restates the schema's conditional `tool` behavior ('hook_install is returned only when this is set') rather than adding new parameter meaning.

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

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

The description states a specific resource: the reporting instructions a monitor needs (ping URLs, snippets, and three reporting mechanisms) and ties it to wiring up a new monitor. It is clearly distinct from read-side siblings like get_monitor or list_monitors, though it never explicitly contrasts itself with them.

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

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

It gives clear context ('for wiring up a new monitor') and routes the agent onward by naming get_trace_setup for tracing detail and declare_run_expectations for expectations. It does not state when NOT to call it or name a competing alternative for basic monitor inspection.

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 safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: scope requirement ('read scope or higher'), hard caps of 200 events / 2,000 spans with corresponding *_truncated / spans_dropped flags, the six outcome values with the 'unfinished' definition and 'never pages' note, span ordering rules, and the presence-only-on-GenAI-calls condition for gen_ai. This is rich disclosure an agent cannot infer elsewhere.

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 scope requirement and primary purpose before the detail. It is, however, a single very long run-on block where low-frequency details (untrusted_fields, span caps) are buried at the end, slightly hurting scannability, but nearly every clause carries factual weight.

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 full return-value burden and does so thoroughly: event types, assertion verdicts, terminal output excerpt, CI metadata, OTLP spans, outcome enumeration, and the untrusted_fields caveat. Nothing an agent needs to interpret or call the tool correctly appears 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 both parameters (id = Monitor UUID, rid = run id) are already documented in the input schema. The description adds only the indirect hint that id+rid are 'found elsewhere', not new per-parameter semantics, 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: 'Gets one run's full timeline' with an enumerated content list. It distinguishes itself from siblings by scoping to the single-run detail ('For the detail behind a run (id + rid) found elsewhere'), which separates it from list_runs. An agent can identify the 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?

The line 'For the detail behind a run (id + rid) found elsewhere' clearly implies the caller obtains id/rid from list_runs first, giving real usage context. However, it never explicitly excludes alternatives (get_run_history, get_trace_diagnostics) or states when-not-to-use, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: the exclusion rule ('a ping with neither ci_meta nor a rid is excluded'), the distinction between duration_ms and CI's duration_s, and the meaning of untrusted_fields. This is well past the lowered bar annotations set.

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

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

Dense and front-loaded: the auth requirement and scope come first, then the returned shape. It is long, but nearly every clause carries non-obvious information (field lists, exclusions, duration semantics), so little is wasted.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly — base fields, CI-only fields, the exclusion rule, and untrusted_fields. An agent has what it needs 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 coverage is 100% with only id and limit, both documented in the schema (monitor UUID; default 20, max 100). The description adds no syntax or format detail for either parameter, so the baseline 3 applies; its field-level detail describes returns, not inputs.

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

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

Opens with a specific verb and resource ('Gets a monitor's run history') and immediately bounds the scope ('from pings, CI and agent runs alike'), explicitly excluding trace-only runs and pointing to list_runs. An agent can distinguish this from get_run and list_runs 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?

States the prerequisite ('Requires the read scope or higher') and names the alternative for a related case ('trace-only runs are in list_runs'), plus the 'no filters' constraint. It stops short of a full when-to-use-this-vs-that rule for the common case, but the routing context is clear.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds substantial non-obvious behavior: the required read scope, a 7-day / 20-attempt retention window, the full outcome taxonomy, per-code meanings, and what untrusted_fields signifies. This is exactly the kind of context the annotations cannot carry.

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

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

The scope requirement and the purpose statement are front-loaded before the detail, which is correct. The long fragmented enumeration of rejection/drop codes is dense but largely earns its place because there is no output schema and the agent needs to interpret the returned reason values.

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 carries the burden of explaining returns: it lists each attempt's fields (outcome, reason, span_count, bytes, protocol, user_agent, signal) and enumerates the possible outcome/reason values. Nothing an agent needs to call or interpret this 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?

Only one parameter (monitor_id) and the schema already documents it at 100% coverage, including its source (create_monitor or list_monitors). The description adds no additional meaning about the parameter, so the baseline 3 for schema-covered params 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 (get trace diagnostics) and immediately defines scope: the newest 20 ingest attempts, last_accepted_at, and the newest traced run's summary. An agent can distinguish this from setup siblings like get_trace_setup or get_ping_instructions without opening any schema.

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

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

Gives concrete trigger conditions: 'For checking a test span, or telemetry sent with nothing showing.' That tells the agent when this tool is the right pick, but it never names an alternative (e.g. setup instructions) or states when not to use it, so it stops short of the top band.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered; the description adds real value beyond that by naming the required scope and disclosing credential handling (the tracing key the user creates on the Connect page). It stops short of describing failure modes or rate limits.

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

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

Front-loads the permission requirement, then purpose, then return shape; every sentence carries information and nothing is padded. It is a single dense paragraph, so scannability is slightly reduced but not wasteful.

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

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

With no output schema, the description compensates by spelling out the returned blocks and their fields (`files`, `key_line`, `bang_script`/`bang_command`), so an agent knows exactly what it will get. Combined with the stated prerequisite and tool-targeting behavior, nothing needed 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%, so both parameters are already documented (including the 'Omitted: every block' behavior for `tool`), which sets the baseline at 3. The description's detail about `prompt`, `key_line` and `bang_script` describes return fields rather than adding parameter semantics.

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

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

States a precise verb and resource: 'Returns the steps that make a tool send OpenTelemetry traces to one monitor,' then enumerates the content (what to write and where, how to verify, limits). This is clearly distinguishable from adjacent tools like get_ping_instructions or get_trace_diagnostics without opening a schema.

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

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

Gives explicit usage context ('For setting up tracing, observability or telemetry') and a prerequisite ('Requires the read scope or higher'), which tells the agent when this tool applies. It does not name an alternative or state when-not to use it, so it falls short of a 5.

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

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

Goes well beyond the readOnly/idempotent annotations: it explains that status is rolled up live from monitors, gives the full worst-first ordering and the meaning of each status value, notes that usage_24h is null with no model call, specifies top_dependencies is the five heaviest, and discloses untrusted_fields provenance. This is exactly the behavioral context an agent needs to interpret results.

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 scope requirement and purpose, then spends its sentences on field semantics that the agent cannot get elsewhere. Reasonably sized and every sentence carries information, though the status enumeration is dense.

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

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

With no output schema, the description carries the return-shape burden and does so by enumerating fields including usage_24h, top_dependencies, and untrusted_fields. Minor gaps remain (e.g., format of monitor_count/last_seen), but it is largely complete for a zero-parameter list tool.

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

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

The tool takes no parameters, so the baseline is 4. The schema is empty and the description correctly focuses on output semantics rather than inventing parameter behavior.

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 ('Lists the project's agents') and enumerates the returned fields, so the purpose is unambiguous. It does not, however, distinguish itself from siblings like get_agent, get_agent_usage, or get_agent_dependencies, which cover overlapping data for a single agent.

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

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

The only usage signal is the prerequisite 'Requires the read scope or higher.' There is no statement of when to call this versus get_agent (single agent) or versus the dedicated usage/dependency tools, even though list_agents appears to inline usage_24h and top_dependencies. No exclusions or alternatives are given.

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

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

Annotations already declare readOnly/destructive-free/idempotent, and the description adds substantive context beyond them: the admin-scope requirement, the guarantee that plaintext secrets are never returned, the cascade rule that revoking a key revokes every key minted below it, and the caveat that last_used_surface is derived from a caller-controlled User-Agent header and is 'a hint, not proof of identity'. That last point is exactly the kind of trust caveat an agent needs and cannot get from annotations.

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

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

Front-loaded and dense: the auth requirement and the no-plaintext guarantee come first. The long middle sentence carries heavy parentheticals (created_by_key_id, last_used_surface) that are informative but make the structure slightly harder to scan than a shorter enumeration would.

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

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

There is no output schema, so the description must document the return shape, and it does: prefix, scope enum values, created_by_key_id with its cascade semantics, last_used_at, and last_used_surface with its source and trust caveat. Combined with the auth prerequisite and secret-redaction guarantee, nothing material is left 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?

With zero parameters and 100% schema coverage, the baseline is 4. The description does not need to explain inputs, and instead spends its space on return-field semantics, which is appropriate 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 ('Lists the project's API keys') and immediately narrows scope with 'without plaintext values', which cleanly separates it from create_api_key, revoke_api_key and regenerate_api_key among the siblings. An agent can identify the operation 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 a concrete precondition ('Requires the admin scope or higher'), which tells the agent whether it is even eligible to call the tool. There is no explicit when-not-to-use or named alternative, but the list-only nature and the permission gate make the usage context clear.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds genuinely new context beyond them: the meaning of each status value (pending/delivered/dead/suppressed), the 30-day retention window, newest-page-only pagination, and an explanation of `untrusted_fields` as data LastPing did not write. This is exactly the behavioral detail the annotations cannot carry.

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

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

Front-loads the scope requirement, then the resource, then status semantics, then coverage limits. Dense and largely waste-free, though the parenthetical status glosses and the untrusted_fields sentence make it longer than strictly necessary.

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

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

With no output schema, the description still conveys the row shape (incident event + destination), the possible outcome values, and the retention/pagination envelope, and it flags the untrusted_fields caveat. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose enriches the semantics of the `status` filter by defining what dead ('per-channel attempt ceiling reached') and suppressed ('destination's rate cap dropped it') actually mean, and explains the row grain the limit/status/monitor filters operate over.

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 ('Lists recent alert deliveries across the project's monitors') with the row grain made explicit — one (incident event, destination) outcome. This is clearly distinguishable from siblings like list_incidents, list_monitors, or list_destinations.

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?

States an access prerequisite ('Requires the read scope or higher') and scopes usage in time and pagination ('Covers 30 days and returns only the newest page'), pointing to the dashboard's delivery log for the archive. It doesn't explicitly contrast with sibling list tools (e.g. list_incidents), so it stops short of full when/when-not routing.

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

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

Adds substantial context beyond the annotations: the required auth scope (read or higher), a hard row cap of 50 with a `more` overflow count, and the meaning of `untrusted_fields` (data fields LastPing did not write). Annotations cover the safety profile, and the description layers on the operational constraints that matter for calling it correctly.

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

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

Dense but front-loaded: the ordering, scope, and auth requirement come first, followed by pagination and untrusted-field notes. Each sentence carries information, though the passage is longer than strictly necessary for a two-parameter read tool.

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

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

With no output schema, the description carries the return-shape burden and does so: per-dependency figures, the nested agents breakdown with call counts, the 50-row cap, and untrusted field notice. Nothing an agent needs to interpret results 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 both enums are already documented (kind omitted = all, range default 7d with the UTC-day overlap note). The description does not add format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (dependencies the project's agents call) and an explicit scope distinction from the sibling get_agent_dependencies ('same figures as get_agent_dependencies plus agents'). An agent can tell it apart from the per-agent variant 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 concrete usage contexts ('which agents call postgres or use a model') and implicitly routes per-agent needs to get_agent_dependencies by contrasting the two. It stops short of an explicit when-not-to-use-this statement, so it lands just below the top band.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds non-redundant context: the required read scope (an auth constraint not exposed in annotations) and the exhaustive set of destination kinds returned, so the agent knows nothing is filtered 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?

Three short sentences, each earning its place: scope prerequisite, what is listed (with kinds), and how the result is consumed. The permission constraint is front-loaded and nothing is padded.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers purpose, permission, scope, and downstream use adequately. Only minor gaps remain, such as whether results are paginated or what fields each destination carries, which the absence of an output schema leaves slightly open.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies an unfiltered full listing rather than misrepresenting an absent filtering capability.

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 the project's notification destinations (channels)') and enumerates all covered kinds (webhook, telegram, discord, slack, ntfy, pushover, msteams, googlechat, email). This clearly separates it from the sibling mutators create_destination, update_destination, delete_destination, and test_destination.

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

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

Clearly signals the access prerequisite ('Requires the read scope or higher') and states the downstream purpose ('Their ids are what set_route takes'), which is genuine when-to-use context linking it to set_route. It stops short of naming explicit alternatives or exclusions, but an agent knows exactly why and when to call it.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond them: the required read scope, a hard cap of 200 results, the most-recently-seen ordering, and an explanation of what untrusted_fields means (fields LastPing did not write). That is real context an agent cannot get from the annotations.

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

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

Front-loaded with the auth requirement and then the resource definition, and every clause carries information. Slightly penalized for the broken fragment about 'traces that arrive while no agent shows them', which adds words without adding clarity.

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

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

For a zero-parameter, no-output-schema tool, the description does the heavy lifting: it defines the resource, the returned fields, the cap, the ordering, and the untrusted-field caveat. Only the muddled usage sentence and the absence of any pagination/continuation guidance keep it from a 5.

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

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

With zero parameters declared, the baseline is 4. The description compensates by documenting the shape and semantics of the response payload, including the meaning of suggested_agent_id and untrusted_fields, which is more than the empty schema supplies.

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+resource and narrows scope precisely: 'Trace sources that sent spans but match no registered agent', which cleanly distinguishes this tool from list_agents and the rest of the sibling list. It even enumerates the returned fields (id, source_name, first/last seen, span_count, suggested_agent_id), so an agent knows exactly what it gets.

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 references the alternative ('adopt_discovered_agent counts a source under an agent') and gestures at the operational context, but the pivotal sentence — 'For traces that arrive while no agent shows them' — is a fragment that never states a clean when-to-use condition versus list_agents. Usage is implied rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the auth scope requirement, the ordering guarantee, and the closed_at=null open-incident convention. It also explains what untrusted_fields means, which is genuine behavioral context beyond the annotations, though pagination/truncation behavior with limit is not discussed.

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?

Compact and front-loaded with the access prerequisite, then the core behavior, then the untrusted_fields note. Every clause carries information, though the last clause is somewhat densely packed and mixes a return-field concept into a description that leads with invocation requirements.

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

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

With no output schema, the description usefully compensates by explaining the closed_at=null convention and the meaning of untrusted_fields in the returned data, and it states the auth requirement. What is missing is any note on ordering/pagination interaction with limit or how many incidents constitute a page.

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

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

Schema description coverage is 100%, so both id and limit are already fully documented with defaults and max. The description adds nothing about parameter syntax or interaction (e.g. behavior at the 200 cap), 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 ('Lists a monitor's recent incidents') with useful scope detail: newest-first ordering and the closed_at=null convention for open incidents. It does not name or contrast the obvious sibling list_open_incidents, so an agent must infer the boundary itself, which keeps it out of the top band.

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

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

The description gives one concrete prerequisite ('Requires the read scope or higher'), which is real usage guidance. However it never says when to choose this over list_open_incidents or get_incident, and gives no exclusions, so the routing decision is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that with the auth scope requirement and the concrete return fields, but says nothing about result limits, ordering, or pagination for a tool that returns 'every monitor'.

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 with no filler, and the access prerequisite is front-loaded before the behavior and the filter. Every sentence carries distinct information.

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

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

With no output schema, the description usefully compensates by enumerating the returned fields, and the auth requirement is stated. The only gap is the absence of pagination, result-size, or ordering details for a list-everything tool, which is minor for a project-scoped listing.

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 sole parameter 'tag' is fully documented in the schema. The description's note that 'tag narrows the list to monitors carrying one tag' largely restates the schema rather than adding syntax, matching behavior for multiple tags, or error conditions.

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 every monitor in the project') and enumerates the fields returned (id, name, slug, status, ping_url), which makes the bulk-listing behavior unmistakable. It never names a sibling, so the contrast with get_monitor for a single monitor is left implicit rather than stated.

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

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

The description supplies a real prerequisite ('Requires the read scope or higher') but no explicit when-to-use guidance or when-not-to-use exclusions relative to siblings like get_monitor or list_discovered_agents. Usage is only implied by the word 'Lists every monitor in the project'.

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

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

Annotations cover the read-only/idempotent profile, and the description still adds the auth requirement ('Requires the read scope or higher'), the field-level semantics of the return payload, and an important caveat that a missing field is 'no evidence, not none, normal or a clean exit.' It also flags `untrusted_fields` as data LastPing did not write -- meaningful context not present in structured data.

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

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

Purpose and auth are front-loaded, but the body collapses into a dense run-on field reference spanning failure_signature, exit_code, duration_vs_normal, cause and untrusted_fields with little structural separation. Length is partly justified by the absent output schema, but readability suffers.

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 only two params, the description carries the return-value burden thoroughly: ordering, per-field meaning, numeric codes (137 vs 1), sample sizes, and cause categories are all explained. An agent has enough to interpret results 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% with both parameters fully documented, including defaults and max. The description only echoes this ('an agent's failure inbox', 'newest first') without adding format or syntax beyond the schema, so the baseline 3 applies.

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

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

Opens with a concrete verb+resource and precise scope: 'Returns an agent's failure inbox: every open incident on the monitors it owns, newest first.' The 'open' qualifier implicitly separates it from list_incidents, though no sibling is named explicitly, keeping it short of a 5.

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

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

'For learning, at a run's start, what broke meanwhile' gives a clear usage context and timing. It stops short of naming alternatives (list_incidents, get_incident) or stating when not to use it, so no exclusions are provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. Beyond that, the description discloses auth scope, default ordering, inclusion of trace-only runs, pagination, per-outcome count narrowing, and detailed failure_cause/untrusted_fields semantics—substantial behavior not covered by annotations.

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

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

The description is dense but front-loads the verb and scope, and nearly every clause carries necessary return-field or filtering information absent from any output schema. It is long and could be sectioned better, but there is little 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 17-parameter, zero-required list tool with no output schema, the description covers purpose, auth, return fields, outcome/failure semantics, filtering, and pagination. An agent has enough to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for the outcome enum (defining 'unfinished' and its pagination behavior) and notes how filters combine to narrow per-outcome counts. It does not add per-parameter syntax beyond that.

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 (Lists) and resource (runs) plus scope (across every monitor in the project), ordering (newest started first), and an inclusion rule (traced-only runs). This clearly separates it from single-run siblings like get_run.

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

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

The description gives a prerequisite ('Requires the read scope or higher') and filter/pagination mechanics, implying usage, but never states when to choose this over get_run, get_run_history, or other list tools. No exclusions or explicit alternative routing are provided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context — and it does, disclosing the required auth scope and the fact that the returned monitor set reflects the current state that update_status_page would replace. It omits pagination or rate-limit behavior, keeping it short of a 5.

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

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

The scope prerequisite is front-loaded and the field list is dense and useful. The explanatory sentence defining what a status page is borders on filler, but it supports disambiguation and the whole entry stays short.

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 zero parameters, the description carries the burden of describing the return payload — and it does so field by field, plus the auth requirement and cross-tool relationship. 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?

The tool takes no parameters, so the baseline of 4 applies; there is no parameter meaning for the description to add or omit.

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?

Opens with the exact verb+resource ('Lists the project's status pages') and then enumerates the returned fields (id, slug, title, monitors, visibility, public URL), so the agent knows precisely what it gets back. It also differentiates itself from update_status_page by contrasting this read result with that tool's mutation of the monitor set.

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?

States the prerequisite ('Requires the read scope or higher') and clarifies the tool's role relative to update_status_page. It does not give an explicit when-not-to-use case or name an alternative lister, but there is no competing status-page list tool among the siblings, so the guidance is adequate.

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

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

Annotations cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new operational context: the required write scope, and the non-obvious behavior that pings continue to arrive while alerting stops. That effect (reversible, non-destructive silencing) is not derivable 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?

Two short sentences with no filler. The permission prerequisite is front-loaded, followed by the effect, which is the order an agent needs to evaluate before calling.

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

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

For a single-id idempotent mutation with an existing safety annotation set and no output schema, the description supplies the auth prerequisite and the operational consequence of pausing. Only the relationship to sibling state-changing operations (resume/snooze) is absent, which is a minor gap.

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

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

There is a single parameter (id) with 100% schema description coverage, so the schema already documents it as the monitor UUID. The description adds no parameter-level detail beyond that, which is the expected baseline for a fully covered single-param tool.

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

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

States a specific verb and resource ("Pauses a monitor") and clarifies the resulting state with "paused=true". It is clearly distinguishable from delete_monitor or update_monitor, but it never names the closely related siblings resume_monitor or snooze_monitor, so the boundaries between those operations are left implicit.

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

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

Usage is only implied: an agent can infer you pause when you want alerts silenced. There is no explicit when-to-use guidance and no differentiation from snooze_monitor, which is the natural alternative an agent would want compared against pause_monitor.

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 destructive/non-idempotent, and the description goes well beyond them: the old key dies immediately (even the calling key), expiry semantics are spelled out (no-expiry stays, expiring gets a fresh 90 days capped at the caller's expiry), no cascade to child keys, and the auth failure mode with the max_scope error. Full behavioral disclosure for a destructive mutation.

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

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

Dense but every clause carries distinct operational information with no filler. Mild penalty for front-loading the auth prerequisite ahead of the action statement, which delays the core purpose by one sentence.

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

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

For a single-param destructive mutation with no output schema, the description covers prerequisites, side effects, expiry rules, cascade behavior, error handling, and the fact that the plaintext key is returned only here. Nothing an agent needs to call this safely 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?

Only one parameter and schema coverage is 100%, so the schema already explains api_key_id as a UUID sourced from list_api_keys. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb (replaces/regenerates) on a specific resource (an API key's secret) and spells out the resulting object identity: a new key with a new id but the same name, scope and monitor. An agent can distinguish this from create_api_key (new key) and revoke_api_key (removal) purely from the text.

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 prerequisite ('Requires the admin scope or higher') and an explicit when-not case ('Refused (403, with max_scope) for a key scoped above the caller's'). It never names sibling tools like create_api_key or revoke_api_key as alternatives, so routing is inferred rather than stated.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write; the description goes well beyond them with the auth scope requirement, the idempotency-adjacent uniqueness rule (same derived slug → 409), concrete error codes (400 UNKNOWN_AGENT, 409), and the shape of the response (id, slug, wire-up steps) despite there being no output schema.

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

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

Four tight sentences with the scope requirement front-loaded, then purpose, then conceptual model and monitor relationship, then uniqueness/error behavior. No sentence is redundant and each adds a fact an agent needs to call this correctly.

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

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

Complete for a two-parameter, no-output-schema write tool: auth, return payload, relationship to monitor tools, failure modes, and duplicate-name behavior are all covered, leaving nothing material for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the consequence of slug derivation (duplicate names are refused rather than creating a second agent) and how the returned id/slug are consumed downstream by agent_id. It still doesn't elaborate on the optional description field, which the schema already covers.

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 ('Registers an autonomous agent in the project's agent registry') and even names the created artifact and return values (id, slug, wire-up steps). It distinguishes itself from siblings by explaining that this is not an implicit create path (agent_id pointing at a missing agent is a 400, not a create), separating it from create_monitor/update_monitor which only attach monitors to an existing agent.

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 prerequisite ('Requires the write scope or higher') and clear when-to-use context: call this to create the agent, then use create_monitor/update_monitor to attach monitors via agent_id. It also states when NOT to expect creation (unknown agent_id is never an implicit create) and that re-registering an existing name is refused with 409.

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: a required authorization scope ('write scope or higher') and the alerting behavior ('alerting resumes from the next missed ping'), which tells the agent about downstream effects. The annotations already cover idempotency and non-destructiveness, so this is a solid supplement rather than a full behavioral spec (no error behavior if already active).

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

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

Two short sentences with no filler, and the authorization requirement is front-loaded. The '(paused=false)' parenthetical is slightly redundant but compact and clarifies the state transition.

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 toggle with no output schema, the description covers the authorization prerequisite, the state change, and the alerting side effect. It is nearly complete, missing only failure/already-active behavior.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents the monitor UUID. The description adds no parameter-specific syntax or format detail, so the baseline 3 applies; 'paused=false' describes the resource effect, not the 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?

States a specific verb (resumes) and a specific resource (a paused monitor), plus the resulting state (paused=false). This is unambiguously the inverse of the pause_monitor sibling, so an agent can select 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?

The phrase 'Resumes a paused monitor' implies the precondition (the monitor must be paused), which is useful implied usage guidance. However, it never names pause_monitor as the counterpart or states what to do if the monitor is not paused, leaving routing inference to the agent.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds materially more: the recursive reach into child keys, that all of them stop authenticating immediately, the irreversibility, and the required privilege level. That is the kind of consequence disclosure a destructive tool needs.

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

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

Three dense clauses with zero filler, ordered by what the agent must know first (permission), then effect (recursive, immediate), then consequence (irreversible). Every sentence earns its place.

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

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

For a one-parameter destructive tool with no output schema and full safety annotations, the description covers authorization, blast radius, timing of effect, and irreversibility — everything needed to call it safely. Nothing material 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 fully documented in the schema, including its source (list_api_keys). The description adds no syntax or format detail about api_key_id, so baseline 3 applies; the cascade information is about tool scope, not the parameter itself.

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 (revokes) and resource (API key) plus the recursive scope, which clearly separates it from regenerate_api_key, delete_agent and other mutation siblings. An agent can identify this as the destructive key-removal 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 the precondition up front ('Requires the admin scope or higher') and points at list_api_keys as the place the id comes from, plus created_by_key_id to preview the cascade. It stops short of explicit when-not-to-use vs regenerate_api_key, but the context is clear.

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

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

Goes well beyond the annotations by disclosing the write-scope auth requirement, the read-modify-write semantics ('every other template is kept'), pre-save validation of allowed variables, and the reset-to-default behavior on empty input. It also usefully clarifies that the destructiveHint applies only to the single targeted entry, not the whole template set.

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?

Auth requirement and behavior are front-loaded, followed by validation, reset semantics, and event types. The trailing 'The template argument lists the variables' sentence is largely redundant with the schema's parameter descriptions and is the one line that does not fully earn 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 mutation tool with no output schema, the description covers everything an agent needs: auth scope, idempotency implications, partial-write behavior, validation failure mode, default-reset behavior, and the enumerated event types. Nothing essential to 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?

Schema description coverage is 100%, so the schema already documents every parameter including the variable list and cause overrides. The description's 'The template argument lists the variables' merely points back at the schema rather than adding format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Sets or clears one alert message template on a monitor') and scopes it to a single entry. It is clearly distinguishable from the sibling get_alert_templates reader 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?

Explains when behavior applies: empty string resets to built-in default, cause omitted means event-type-wide, and the write-scope prerequisite is stated. It does not explicitly name get_alert_templates as the read counterpart or state when not to use this tool, so it stops short of routing-level 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the exact destructive semantics: the whole destination set is replaced, unlisted destinations stop receiving, including ones configured by others, and an empty string clears all routing. It also states auth (write scope) and precondition (destinations must be verified and enabled) details the annotations do not carry.

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

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

The prerequisite is front-loaded, followed by purpose, destructive semantics, and practical guidance. Sentences are dense but each earns its place — 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?

For a destructive replace operation with no output schema, the description covers prerequisites, replacement behavior, empty-value behavior, destination verification requirements, and pointers to related tools. An agent has everything needed to invoke it correctly and safely.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: channel_ids is a wholesale replacement set rather than an additive list, and an empty value removes routing. This clarifies the mental model of the parameter beyond the schema's plain 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?

The description states a specific verb and resource: it 'Routes a monitor's alerts for one event type to a set of destinations (channels).' This is a distinct, unambiguous purpose that any agent can distinguish from siblings like delete_route or list_destinations 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?

It gives clear operational context: the write scope requirement, that adding a destination means sending existing ids plus the new one, and that an empty channel_ids removes all routing. It also points to get_monitor and list_destinations for supporting data. It stops short of explicitly naming when to prefer this over delete_route for clearing a route, so it is strong but not fully exhaustive.

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

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

Goes well beyond the annotations by spelling out what is suppressed (deadline incidents, HTTP failing probes), the exact exception semantics ('a site still failing afterwards opens one on its next failure'), and what is explicitly still notified (fail pings, queued blocked pages, runaway ping rate, routed note/started/success/every-run events). That is the behavioral detail an agent needs to predict side effects before mutating state.

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 auth requirement and the core action, and every sentence carries non-redundant content. The second sentence is a dense run-on with nested parentheticals (the blocked_timeout_s aside, the probe-counting clause), which costs readability but not correctness.

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

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

For a mutation tool with no output schema, the description is complete: authorization requirement, valid parameter combinations, suppression scope, notification carve-outs, and post-window failure behavior are all present. 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 each parameter is already documented with its format (RFC 3339, Go duration string), so the schema carries the burden. The description only reinforces the mutual-exclusivity rule with 'exactly one', adding marginal semantics over the per-parameter 'One of duration, until or clear' 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 ('sets or clears') and resource ('a maintenance window on a monitor'), so an agent knows exactly what state it manipulates. It does not, however, distinguish itself from the closely related pause_monitor/resume_monitor siblings, which an agent could plausibly confuse with a suppression mechanism.

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 real preconditions ('Requires the write scope or higher') and a hard selection rule ('Takes exactly one of duration, until or clear=true'), which tells the agent how to shape the call. It stops short of saying when to prefer this over pause_monitor or resume_monitor, so alternative selection 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 cover the safety profile (destructive=false, openWorld=true), and the description adds value beyond them: the required write scope, what actually gets delivered ('LastPing test alert'), and the important side-effect clarification that a test alert does not verify an unverified email or let it join a route.

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 permission requirement, then the default behavior, then the alternate mode. No filler; each clause carries invocation-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?

For a two-parameter action tool with no output schema, the description covers auth, payload semantics, both modes, and the key side-effect caveat. It stops short of describing the response an agent should expect, but that is a minor gap given the thorough coverage elsewhere.

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: it explains the default send behavior versus the resend_verification=true path and why you would choose the latter. It complements rather than repeats the schema.

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

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

States a specific verb+resource ('Sends something through a destination now') and immediately qualifies it as a synthetic test alert rather than a real notification. This clearly separates it from create_destination, update_destination, and delete_destination without naming them.

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

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

Gives explicit when-to-use for both modes: the default for confirming a new destination's credentials, and resend_verification=true for when a confirmation link never arrived or expired. It does not name alternative tools or state exclusions, but the context for invoking it is unambiguous.

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

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

Annotations cover the safety profile (destructiveHint, idempotentHint, openWorldHint), and the description adds substantial context beyond them: merge-patch semantics, that renaming never changes the slug, slug uniqueness constraints, the downstream impact on links/Terraform/trace sources and past runs, and that monitors stay attached. These are exactly the side effects an agent needs before invoking a destructive mutation.

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 permission requirement and the action, and every clause carries information. The final slug-consequence sentence is dense and long, but none of its content 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?

For a destructive, idempotent mutation with no output schema, the description covers auth scope, update semantics, uniqueness constraints and all downstream side effects. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining merge-patch behavior (supplied fields change, omitted ones keep their value) and the cross-parameter consequence of changing slug on the name field's matching semantics.

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

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

States a specific verb (Updates), resource (an agent), identified by UUID, and enumerates the mutable fields (name, description, slug). An agent can distinguish it from register_agent, get_agent and delete_agent 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 clear prerequisite ('Requires the write scope or higher') and describes update semantics, so the agent knows the context in which it applies. It does not, however, explicitly name an alternative tool or a when-not-to-use condition.

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 idempotent/destructive/not-read-only, and the description adds substantial context on top: the required write scope, that only supplied fields are mutated (partial update, a real behavioral trait), that 'kind' is immutable, and that supplying a new email resets verification and triggers a confirmation email.

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 scope requirement, then update semantics, then the immutability constraint, then the side effect. No filler; each sentence contributes a distinct operational 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 mutation tool with no output schema, the description covers auth, mutation semantics, constraints, and side effects well. It stops short of describing the response shape or what the updated destination returns, which is the only notable gap.

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

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

Schema coverage is 100%, so per-parameter documentation is already carried by the schema (baseline 3). The description adds cross-parameter semantics the schema does not: partial-update behavior ('only the supplied fields change') and the kind-immutability constraint tying config changes to the existing kind.

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 ('updates a notification destination's name and/or config in place') with field-level scope, and explicitly carves out what it is not: the kind cannot change. An agent can distinguish it from delete_destination/create_destination 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 a clear prerequisite ('Requires the write scope or higher') and names the alternative path when the change isn't supported ('delete and recreate instead'). It doesn't broadly contrast with create_destination for new destinations, but the routing guidance is concrete.

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 behavior beyond the annotations: write-scope requirement, merge-patch survival of omitted fields, whole-set replacement semantics for tags/assertions/guards (the destructive behavior destructiveHint flags), which causes the sets catch, and that slug and ci_provider are immutable. This is exactly the context an agent needs before mutating a monitor.

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

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

A single dense paragraph that front-loads the scope requirement and the merge-patch rule before the details. Every sentence carries weight; the only cost is density that could be broken into list form for scanning.

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 29-param mutation tool with no output schema, the description covers the dangerous cross-cutting semantics well while the fully-populated schema handles per-field detail. It does not restate return behavior, which is acceptable given no output schema, but a note on what a successful update returns would round it 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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot: omitted-vs-present-vs-null handling, merge-patch interaction, and the immutability boundary of slug/ci_provider. It meaningfully reduces misuse risk for a 29-parameter tool.

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

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

States a specific verb and resource ('Updates a monitor by UUID') and names the exact semantics (merge-patch). An agent can distinguish this from create_monitor, delete_monitor, pause_monitor, and snooze_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 the precondition ('Requires the write scope or higher') and the operational context: supplied fields change, omitted fields keep their stored value, and get_monitor returns the current sets for tags/assertions/guards. It stops short of explicitly naming when to prefer pause_monitor/snooze_monitor over a field update, so it is clear but not a full when/when-not routing.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true; the description goes well beyond them by disclosing merge semantics (a read-and-merge, so omitted fields are never blanked), the whole-set replacement of check_ids, the irreversible link breakage a slug change causes, and the fact that going 'public' publishes every monitor name. Those are exactly the side effects an agent must weigh before 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?

Three front-loaded sentences: the permission requirement first, then the mutation semantics, then the two highest-risk caveats (whole-set replacement, URL breakage). Every clause carries distinct 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?

For a destructive update tool with no output schema, the description covers permissions, merge behavior, validation failure modes and the user-visible consequences of public/slug changes. Combined with the annotations' safety profile, 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 description coverage is 100%, so the per-field semantics (omitted = unchanged, 409 on taken slug, 400 on cross-project ids, 403 on second public page) are already documented in the schema. The description's 'reads the page and merges' framing adds a useful holistic view but largely restates 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 ('Updates a status page') and enumerates the mutable fields (title, slug, visibility, monitor set), which cleanly separates it from create_status_page, delete_status_page and list_status_pages. An agent can identify the tool's job 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 prerequisite ('Requires the write scope or higher') and routes the agent to sibling tools for inputs: list_status_pages for the check_ids, list_monitors implicitly for monitor UUIDs. It does not spell out when to choose this over create/delete_status_page, but the context is clear enough that no exclusion rules are needed.

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