LastPing

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

Beyond the annotations, the description discloses append-only behavior, no edit/delete routes, the database refusing edits, author forced to 'agent', and the 50-note cap. It also explains that closed incidents still accept notes, which is surprising and essential.

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

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

The description is a long wall of text with redundant explanations and emphatic repetition. Append-only and the 'send a note even if you didn't fix it' point are repeated across several sections, and the rationale is given extensively. A more structured layout with headings would make it easier to scan while preserving the essential warnings.

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 there is no output schema and minimal annotations, the description covers every operational aspect: authentication, append-only, maximum note count, behavior on closed incidents, and the forced author attribution. It leaves very little for an agent to wonder about when calling this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing what a proper body looks like (plain words, not a stack trace), and by clarifying that an oversized body is rejected, not truncated. The guidance to source incident_id from list_open_incidents is already in the schema, but the extra textual context on content quality elevates it.

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 explicitly states what the tool does: write a diagnosis note to an incident, with a concrete example and a clear instruction to use the note. It differentiates this from read-only tools like list_open_incidents by its action and references the actual use case. The purpose is unmistakable.

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

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

It gives explicit usage rules: send a note whether or not you fixed the problem, never edit or delete, and use incident_id from list_open_incidents. It also covers the edge case of closed incidents, which is not obvious and is critical for an agent to know when to call this.

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 mark it non-readonly, non-idempotent, non-destructive but do not convey prerequisites or irreversibility. The description adds substantial value: the admin-scope prerequisite, that the plaintext key is returned once and cannot be retrieved, and the inheritance-ceiling behavior. These are behaviors the annotations cannot express.

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

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

Three tight sentences, prerequisite front-loaded, the security-critical warning about the one-time plaintext key is prominent. Slightly abrupt ordering (prerequisite before the action verb) but 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?

Covers the critical operational facts an agent needs: auth requirement, one-time secret exposure, and expiry semantics. No output schema, but the description handles the main return-value concern (plaintext returned once). Missing only sibling-level routing and any mention of scope-ceiling error handling, which the schema covers.

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 baseline 3 applies. The description's note about expires_at for short-lived keys and the scope prerequisite marginally complements the schema, but the schema already documents each parameter in detail. No meaningful additional syntax or format is added.

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

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

States a specific verb and resource ('Create a new LastPing API key'), and clearly distinguishes from sibling list_api_keys and revoke_api_key. An agent can tell this mints a credential rather than listing or revoking one.

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?

Mentions when to use expires_at ('for a short-lived key') and implies scope selection, but offers no explicit when-to-use vs siblings like list_api_keys or revoke_api_key, nor a clear statement that this is the creation path for a new credential. Guidance 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?

Excellent transparency beyond annotations. Discloses auth requirements, the cap limit (25 destinations), the specific error (DESTINATION_CAP_REACHED) and remediation, and the differing behavior of email vs non-email kinds (verification flow). It also clarifies that unrelated fields are ignored, which is important behavioral context not covered by 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?

Five dense sentences, each earning its place. Front-loads auth requirement, then purpose, then behavioral details and error handling. No fluff, well-structured for an agent to parse key facts quickly.

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 and well-rounded. Mentions auth, purpose, parameter handling, variant behavior (email vs non-email), limit and remediation, and return value usage. Despite no output schema, it describes what is returned ('the new channel id') and how to use it. An agent has all needed context to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description adds general context about 'fields for the chosen kind' being required and others ignored, but does not duplicate or add specific meaning to individual parameters beyond what the schema provides. Baseline 3 when schema does the heavy lifting.

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

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

States a specific verb and resource: 'Create a notification destination (channel) that monitors can route alerts to.' This clearly distinguishes it from update_destination, delete_destination, and set_route. However, it doesn't explicitly name those siblings to guide the agent as strongly as a 5 would.

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 states prerequisites (API key with write scope), when to use alternatives ('delete_destination rather than retrying' on cap reached), and next steps ('pass it to set_route'). It covers when to use this tool and what to do if it fails, giving 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 destructiveHint=true and idempotentHint=true, and the description compounds that with what the agent cannot get elsewhere: the write-scope auth requirement, the upsert 'updated' note, and critically that the CI webhook secret is returned exactly once and never retrievable. That last point is the kind of irreversible-consequence information the annotations cannot express.

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

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

It is a single dense paragraph, but the priority content (auth scope, core create/upsert behavior) is front-loaded and each subsequent sentence addresses a distinct branch (schedule kinds, http probes, CI binding). Some parameter restatement could be trimmed since the schema already covers it, but nothing is irrelevant.

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 28-parameter tool with no output schema, the description covers the safety-relevant, unrecoverable behaviors (set-once ci_provider, one-time secret, upsert mutations) and the type-dependent requirements an agent must know before filling the schema. Annotations and the rich schema carry the rest.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes past mere restatement by synthesizing cross-parameter requirements per monitor_type and adding a decision rationale ('set probe_expected_status/probe_expected_body too, because those are what define healthy; a probe with neither only proves something answered'). That editorial framing exceeds what the field-level schema conveys.

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

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

States a specific verb and resource ('Create a new LastPing monitor') and immediately discloses the upsert behavior ('or update an existing one if slug matches'), which lets an agent distinguish this from sibling update_monitor. The opening sentence about the required API scope is a clean, front-loaded framing.

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

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

Routes the caller across the three monitor flavors (heartbeat/ci via schedule_kind, http via probe_url, CI-fed via ci_provider) and states an explicit set-once constraint: ci_provider is 'the ONLY place it can be set,' effectively telling the agent not to defer it to update_monitor. This is exactly the when/where guidance the alternative tools demand.

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?

Despite annotations being minimal (all false), the description discloses a wealth of behavioral details: requires an API key with write scope or higher, default privacy, public pages expose monitor names, global slug uniqueness (409), cross-project id validation (400), free-tier public page quota (403), and the random unguessable slug default. It even explains the privacy implications of making a page public. This goes far beyond the annotations and is crucial for safe invocation.

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

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

The description is longer than average but every sentence earns its place. It front-loads the primary purpose and use case, then layers in key warnings (privacy, slug, quota). It could be slightly tighter, but the density of critical operational information justifies the length. No redundancy or 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 creation tool with no output schema, the description adequately covers input constraints, error scenarios, and security considerations. The only minor missing piece is an explicit statement about the response format (e.g., returns the created page object), but this is conventional and not necessary for correct invocation. The description is otherwise complete for safe and effective use.

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 schema already covers all parameters (100% coverage), but the description adds significant value: for slug, it explains the regex, global uniqueness, and recommends omitting unless explicitly requested; for visibility, it elaborates on privacy risks and the one-public-page limit; for check_ids, it notes that empty is legal and that ids must belong to the project. This guidance directly affects how an agent should fill the parameters.

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

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

The description clearly states the tool's purpose: 'Create a status page — a single page showing the current status and recent history of a chosen set of monitors.' It uses a specific verb ('create') and resource ('status page'), and differentiates from siblings like update_status_page and delete_status_page by focusing on the initial creation use case. The additional context about exposing health to non-logged-in users further clarifies its role.

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 explicitly says when to use it: 'Reach for this when the health of a monitor needs to be visible to someone who cannot log in to the project.' It also provides critical usage caveats: pages are private by default, the visibility parameter must be read before making public, and it suggests using list_monitors to obtain check_ids. It even hints at alternatives (update_status_page for modifications) implicitly. This is explicit, actionable 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?

The description extensively discloses behavior beyond annotations. It explains that a second call is rejected (idempotent), that declarations are immutable, that grading outcomes change (success ping failing all declared criteria leads to FAILED run), and that conflicting declarations are rejected. It also clarifies the safety profile (requires write scope). This richness goes well beyond the readOnlyHint/idempotentHint/destructiveHint annotations, adding substantial context without contradiction.

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 long, but every section earns its place given the tool's complexity. The core purpose is front-loaded in the first sentence, and the parameter details are organized. The main description is concise while the assertions parameter documentation is appropriately exhaustive. It is not overly verbose; the length is proportional to the complexity of the contract it defines.

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 there is no output schema and the tool carries significant side effects, the description covers all essentials: authentication, timing, immutability, allowed values, constraints, errors (including rejection of malformed entries), and references to a worked example. Nothing an agent needs to call it correctly is missing.

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

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

While the schema provides 100% coverage, the description enriches each parameter significantly. For rid, it re-emphasizes it must match the /start ping. For check_id, it points to sources. For assertions, it provides a full specification: JSON array format, allowed kinds, required fields per kind, limits (max 20), examples, and pitfalls (purely negative declarations are self-satisfying, regexp caveats). This is far beyond the schema's one-line descriptions.

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: 'Commit ... to the criteria by which THAT RUN will be judged' for a specific run. It clearly explains the tool's function and contrasts with the alternative of not calling it at all ('Declaring nothing is allowed...'). It distinguishes itself from siblings by being the only tool that declares run expectations, and it references get_ping_instructions for a worked example.

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 provides timing instructions: 'Call this right after your run's /start ping, before doing any work'. It also states when not to call: 'simply never call this tool for a run' when you want monitor-level assertions to stay in force. It even references an alternative tool (get_ping_instructions) for a worked example, giving clear contextual 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?

The annotations already set destructiveHint=true, but the description goes far beyond by disclosing the ON DELETE SET NULL behavior, that monitors survive with history and incidents intact, become unowned, keep running, and that the agent row itself cannot be un-deleted. No contradiction with 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 long, but every sentence earns its place — no filler, each sentence adds a required fact (prerequisites, the core action, monitor survival, reattachment, deletion of monitors, irreversibility). It is front-loaded with the essential purpose and permission requirement before the detailed behavioral caveats.

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

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

For a destructive mutation with cascading implications, the description fully covers prerequisites, side effects, reattachment workflow, how to fully remove associated monitors, and irreversibility. There is no output schema, but for a delete operation the primary missing concerns are all addressed.

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

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

Schema coverage is 100% and the schema already fully describes the only parameter as 'Agent UUID (from register_agent or list_agents)'. The description adds no new semantic value beyond restating 'by UUID', so the baseline 3 is appropriate.

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

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

Clearly identifies the action: 'Permanently delete a LastPing agent from the registry by UUID.' It distinguishes the tool from siblings such as delete_monitor and update_agent by explicitly calling out that monitors are not deleted in this operation, making the purpose unmistakable.

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 prerequisites ('Requires an API key with the write scope or higher'), explicit exclusion ('THIS DOES NOT DELETE ITS MONITORS'), and names the exact alternatives for related operations ('call delete_monitor', 'call update_monitor'). This is model guidance for when to use and when not to use this tool.

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

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

Annotations only signal destructive and idempotent, but the description adds crucial behavior: permanence, removal of the destination from all monitor routing, silent notification loss for exclusively-routed event types, and API key scope requirements. This richly exceeds what the annotations already provide and does not contradict them.

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 well-structured and every sentence serves a purpose, covering permission, permanence, side effects, and alternatives. It loses a point for a slight redundancy between 'Permanently delete' and 'This cannot be undone,' and for leading with the API-key prerequisite rather than immediately stating the core action.

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, high-risk delete operation, the description is highly complete: it covers permission, irreversibility, routing consequences, and recommended pre-conditions. It omits the exact success/failure return semantics for deleting a non-existent id, but the idempotentHint annotation partially covers that gap.

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

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

Schema coverage is 100% and the schema already explains that id is the destination UUID and tells the user to get it from list_destinations. The description adds no parameter-specific semantics beyond those already encoded in the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Permanently delete a notification destination (channel).' It also distinguishes itself from siblings like delete_agent, delete_monitor, and delete_status_page by clearly targeting destinations, and from set_route by describing its different purpose.

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

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

It gives explicit prerequisites (write-scope API key), warns when not to use deletion, and points to the alternative set_route for temporary changes. It also directs the agent to check monitor routing with get_monitor before proceeding, which is excellent when-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true)Skip, so the description adds value by emphasizing irreversibility and specifying the required API key scope. However, it does not mention whether other resources are affected (e.g., incidents or destinations) but the description is sufficient for the safety profile.

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

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

The description is concise and front-loaded: it begins with the essential prerequisite (API scope), then the action, and ends with the critical warning. Every sentence contributes meaningful information without any waste.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the essential aspects: prerequisite, action, irreversibility. It lacks details about return values or side effects, but for a delete operation with annotations, this is adequate.

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

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

Schema coverage is 100%, so the schema already documents the 'id' parameter as 'Monitor UUID'. The description adds no additional semantic detail beyond the schema, but since the schema is complete, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Permanently delete') and the resource ('LastPing monitor by UUID'), and it distinguishes from siblings like pause_monitor or snooze_monitor by emphasizing permanence. However, it does not explicitly differentiate from the general delete_* siblings, though the resource specificity is sufficient.

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 provides a clear context for when to use it (when permanently deleting a monitor) and adds an important prerequisite (API key with write scope or higher). It does not explicitly state when not to use it, but the permanence warning implies to avoid if wanting to retain the monitor, which is a reasonable implicit guideline.

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

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

The description goes beyond the annotations by disclosing that deletion is permanent and cannot be undone, that the public URL stops working immediately, and that monitors on the page are NOT affected. This adds critical behavioral context beyond the destructiveHint and idempotentHint annotations. No contradiction with 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 concise and front-loaded: it starts with the requirement, then the action, then the consequences, then the alternative. Every sentence adds value, and it's appropriately sized for the tool's complexity.

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

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

Given the single parameter, the clear schema, and the annotations, the description is complete. It covers prerequisites (API key scope), consequences (permanent deletion, URL stops working), non-effects (monitors unaffected), and the alternative (update_status_page). No output schema exists, but the description doesn't need to explain return values for a delete operation.

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

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

The schema already provides 100% coverage for the single parameter 'id' with a description ('Status page UUID, from list_status_pages.'). The tool description doesn't add much parameter-specific detail, but the schema is sufficient. The description's mention of 'public URL' and 'monitors' indirectly clarifies what the id refers to, but the schema already covers it. Baseline 3 for high coverage, with a slight bump for the description's contextual hints about the resource.

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 clearly states the tool's function: 'Permanently delete a status page.' It specifies the resource (status page) and the action (delete), and distinguishes it from the sibling update_status_page by noting the alternative for non-destructive visibility changes. The scope is unambiguous.

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

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

The description explicitly states when to use this tool (when you want to permanently delete a status page) and when not to use it ('To stop sharing without losing the page, set visibility to 'private' with update_status_page instead'). It also names the alternative tool, providing clear 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?

No annotations were provided, so the description carries full responsibility. It discloses side effects (creates monitors), non-effects (never deletes, edits, or updates; orphans still alert), idempotence (safe to re-run), and auth requirements. The timezone warning is exceptionally transparent about a subtle failure mode.

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

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

Front-loaded with the core purpose and safety warning, but the no-delete/no-update point is repeated several times and the timezone warning is stated twice. Slightly longer than necessary, though the repetition serves a safety-critical function.

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 one-parameter endpoint with no output schema: input format, entry requirements, idempotence, return semantics (three-way diff), error behavior, and post-call interpretation are all covered. An agent can call this correctly without additional documentation.

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 schema already documents `sources` well, but the description adds crucial semantics beyond it: stability of source_ref between runs, the meaning of the diff keys, the 1000-entry and 100-monitor limits, and all-or-nothing validation. This compensates fully for the single string parameter's JSON-inside-string complexity.

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

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

States a specific verb and resource: 'Turn a scan of a repository or a host into monitors' and get back a diff. The phrase 'PROPOSE, THEN ASK' plus 'This is how a user gets monitored without filling in a form' unambiguously distinguishes the operation from generic monitor creation.

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

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

Explicitly tells the agent when to call it (nightly, on every CI build, after every deploy), why re-running is safe, and when NOT to act on output (never act on orphaned without asking the user). Also covers the prerequisite: an API key with write scope or higher.

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

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

Given the annotations already indicate readOnly, idempotent, and non-destructive behavior, the description adds useful context: the API key requirement, the exclusion of secrets (output references Terraform variables), and the import-block behavior that ensures adoption rather than recreation. These are genuinely beyond the annotations.

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

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

The description is three sentences and each one contributes a distinct fact: the authentication requirement, the export scope/format/import behavior, and the secrets handling. It is concise and without filler, though the auth requirement could arguably follow the main purpose for better front-loading.

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 the tool's moderate complexity (3 optional params, no output schema), the description covers the main operational points: the source resources, the output form (Terraform HCL), import blocks for adoption, the authentication boundary, and the secrets gap. It doesn't specify the exact return format, but given the absence of an output schema, this gap is acceptable.

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

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

The input schema covers all three optional parameters with 100% description coverage, so the tool description doesn't need to re-explain them. The description mentions the resource categories ('monitors, destinations...') but does not add parameter-specific semantics beyond the existing schema entries.

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 action ('Export') and distinct resources ('monitors, destinations, routes, alert templates and status pages') with a concrete output format ('Terraform HCL'). It further distinguishes itself from mere read/list tools by noting 'import blocks so they are adopted rather than recreated'.

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 clear prerequisite ('Requires an API key with the read scope or higher') and signals its purpose of generating adoptable Terraform. It doesn't explicitly name alternative commands like list_monitors or get_terraform, but the sibling tools are visibly separate (create/update/list), so no exclusions are necessary.

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

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

Annotations already cover readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context: auth requirements and that the response matches list_agents fields, including a live status rollup. No contradiction with 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?

Four short sentences, each with a distinct purpose: auth, action, return shape, and how to obtain valid inputs. No filler or redundancy.

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

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

Complete for a simple get-by-ID call: auth, input source, and return shape are covered. It does not describe not-found or error behavior, but for this tool that is a minor omission.

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 'id' parameter is fully documented. The description reinforces the source of valid IDs but does not add new parameter-level 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 and resource: 'Get a single LastPing agent by UUID.' It clearly distinguishes itself from list_agents by focusing on a single agent identified by UUID.

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 clear context: requires an API key with read scope, and explicitly directs the agent to list_agents for valid IDs or register_agent to create one. It does not explicitly rule out using it for batch retrieval, but the singular scope makes that evident.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable context: the required API key scope, the map structure with valid keys, and the important empty-result semantics (built-in defaults). This goes well beyond the annotations and fully discloses observable behavior.

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

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

Four sentences, each earning its place: auth requirement, operation, return structure, and fallback behavior. The key enumeration is detailed but necessary because there is no output schema. The most critical info is front-loaded, with 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 simple one-parameter, read-only tool, the description is complete. It covers auth, exact return shape, valid key formats, and the meaning of an empty result. With no output schema present, the description provides all needed interpretation. Nothing an agent requires 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% — the only parameter id is described as 'Monitor UUID.' The description does not add any detail about the parameter itself, relying on the schema. With such high schema coverage, a baseline of 3 is appropriate, and the description adds no extra semantics for id beyond implying the monitor context.

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: 'Get all custom alert message templates for a LastPing monitor.' It precisely names the operation and clearly distinguishes it from the sibling set_alert_template, which is the write counterpart. The return shape is also described, leaving no ambiguity about what the tool does.

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

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

The description clearly implies this is the read tool for alert templates and notes an auth prerequisite ('read scope or higher'), but it does not explicitly contrast with the sibling set_alert_template or state when not to use it. The usage context is implied rather than spelled out, so the tool does not fully guide an agent toward alternatives.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the auth scope required, that the delivery error text is never returned, that run events are matched by the recorded run_id so an empty run_id is a record fact rather than an anomaly, and that responses are wrapped with untrusted_fields that must be treated as data. These are exactly the non-obvious traits an agent needs before trusting output.

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 is front-loaded with the auth prerequisite and the core action, and every clause carries information (event types, edge-case interpretation, injection warning). It is long, but the length is driven by genuine behavioral disclosure rather than padding.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: it enumerates timeline event kinds, explains the wrapper structure (data plus untrusted_fields), and covers the empty-run_id case. Nothing an agent needs to call and 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?

There is only one parameter and schema coverage is 100%, with the schema itself explaining where the numeric id comes from. The description adds no syntax or format detail beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource (get ONE incident) and enumerates exactly what the record contains — a timeline of run/alert/note/resolution events — which no sibling tool provides. An agent can distinguish it from list_incidents, list_open_incidents and get_run_history 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 a concrete usage frame: 'Use it to answer what was the run doing when it broke, did anyone get paged, and what has already been tried in one call,' which signals it is the aggregated single-incident view. It does not explicitly name an alternative (e.g. get_run_history) or state when not to use it, so it stops short of a full routing rule.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds important context: field presence semantics ('absent when the monitor has none') and a warning that related write operations replace entire sets, risking silent data loss. It also explains what assertions, guards, and routes mean. No contradiction with 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 every sentence earns its place: auth requirement, basic purpose, return-field semantics, and critical read-before-write warning. It is front-loaded with the core action and uses the final sentence to highlight a non-obvious behavioral consequence.

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 explaining the three key return fields and their absence behavior. It also covers auth, the single-parameter call pattern, and the relationship to mutating siblings. An agent has enough to call it correctly and interpret the important parts of the response.

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

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

Schema coverage for the single parameter id is 100% and the schema already describes it as 'Monitor UUID.' The description reinforces 'by UUID' but adds no new parameter-level detail. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

States a specific action and resource: 'Get a single LastPing monitor by UUID.' It also distinguishes this from list-style siblings by emphasizing 'single' and by UUID. The mention of returned configuration fields further clarifies exactly what the tool is for.

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 explicit guidance on when to call this tool: 'Read this before calling update_monitor with assertions or guards, and before calling set_route.' It also discloses the required auth scope up front. This is strong, actionable routing advice.

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 valuable context: it requires an API key with read scope or higher, explains the content of the response, and outlines the tradeoffs of each reporting mechanism. It does not contradict annotations and goes beyond them by describing the functional behavior and prerequisites.

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 extremely verbose, running into a dense paragraph of many sentences. While every sentence adds value, the sheer length makes it unwieldy for an AI agent to parse quickly. It could be restructured with bullet points or subheadings for clarity. The front-loaded core purpose is clear, but the excessive detail on mechanisms and usage instructions dilutes conciseness. It earns a 3 because it is not minimally sized, though it is not redundant.

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

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

Given the tool's complexity (multiple reporting mechanisms, prerequisites, related tools), the description is exceptionally complete. It covers prerequisites (API key scope), content of response, selection criteria for each mechanism, and references to other relevant tools (declare_run_expectations, discover_monitors_reconcile). It also explains the tradeoffs and potential pitfalls (e.g., translated hook installs failing). Even without an output schema, the description conveys everything an agent needs to call this tool correctly and understand its results.

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 only one parameter 'id', and the schema description already covers it thoroughly: 'Monitor UUID (from create_monitor or list_monitors).' With 100% schema description coverage, the description adds no additional meaning beyond what the schema provides. The baseline of 3 is appropriate because the schema does the heavy lifting and the description doesn't introduce extra parameter nuances.

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 clearly states the tool's purpose: to retrieve everything needed to make a monitor report, including ping URL, snippets, and three reporting mechanisms. It distinguishes itself from siblings by focusing specifically on reporting instructions rather than monitor configuration or management. The verb 'Get' and resource 'ping instructions' are specific and unambiguous.

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

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

Provides explicit when-to-use guidance: 'Call this right after create_monitor.' It also details the three mechanisms (how_to, hook_install, run_wrapper) with clear selection criteria based on the monitored thing and the agent type. It explicitly warns against using hook_install for non-Claude Code agents, and directs to read reporting_options first. This is comprehensive and leaves no ambiguity about when to use this tool versus alternatives.

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

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

Annotations already declare readOnly/idempotent/destructive hints, so the bar is lower, but the description adds substantial context: the read-scope API key requirement, the 200-event cap with events_truncated flag, the absence of trace fields in this release, the response wrapper structure, and a security warning about untrusted_fields containing raw job output that must be treated as data, never instructions. No contradiction with 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?

Despite being long, every sentence carries unique value: auth requirement, purpose, usage trigger, limits, future changes, and security warning. It's front-loaded with the core purpose and the usage guidance comes immediately after. No redundancy; the density is justified by the tool's complexity.

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

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

With no output schema, the description fully compensates by explaining the returned object's contents, the wrapper structure, the truncation behavior, and the untrusted_fields security note. It also covers prerequisites (auth) and temporal constraints (trace fields later). 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% – both id and rid have clear descriptions. The description doesn't add syntax or format details beyond the schema, but it does contextualize the parameters by saying they come from get_run_history or list_open_incidents, which aids selection. This aligns with the baseline 3 for high schema coverage.

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

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

The description opens with a specific verb-resource pair ('Get ONE run's full timeline') and enumerates exactly what that includes (events, assertions, terminal output, CI metadata). It distinguishes itself from get_run_history (summary row) and list_open_incidents, so an agent can tell it apart 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?

Explicitly states when to use: after get_run_history or list_open_incidents points at a specific run and you need the blow-by-blow. It also contrasts with the 'summary row' alternative, giving clear selection criteria. This is the gold standard for usage guidance.

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

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

Annotations already cover the read-only/idempotent safety profile, yet the description adds substantial non-obvious behavior: steps are matched on rid and absent otherwise, pings lacking ci_meta and rid are excluded, duration_ms is computed by LastPing rather than self-reported and is distinct from duration_s, and untrusted_fields must be treated as data not instructions.

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 sentence carries load-bearing information about return shape and exclusions, which is justified given there is no output schema. The auth requirement is front-loaded, though the return-structure explanation is a single long block that could be more clearly segmented.

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 must carry the full burden of explaining the return contract, and it does so comprehensively — field presence rules, exclusion rules, duration semantics, and the untrusted_fields wrapper are all covered.

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 documented in the schema. The description adds no parameter-level syntax or default detail beyond what the schema provides, which is the baseline 3 case.

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

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

States a specific verb and resource (get run history for a monitor) and explicitly scopes it to both CI/CD and agent/heartbeat runs. No sibling tool covers this, and the description's scope statement makes that distinction apparent.

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 clear context, including the auth scope required and a concrete use case ('how long does this job normally take?'). It does not state when-not to use it or name alternatives, but there is little sibling overlap to disambiguate against.

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 safe read-only profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds genuine value beyond that by disclosing the auth requirement (read scope) and detailing the live status rollup semantics with the worst-first ordering and each possible status value. It stops short of disclosing whether results are paginated or sorted, but for a 0-parameter list tool this is a strong behavioral disclosure.

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?

Every sentence earns its place: auth requirement, core purpose, return fields, the non-obvious status rollup explanation, and the sibling pointer. The status semantics block is verbose but necessary because it defines seven domain-specific values otherwise opaque to the agent.

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

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

Given zero parameters, no output schema, and simple annotations, the description covers everything an agent needs: purpose, auth prerequisites, return fields, status meanings, and the alternative for creation. No missing information would prevent correct invocation or interpretation.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about individual parameters. The 'List all' phrasing correctly signals that no filtering is available, which is the most important semantic guidance for a parameter-less tool.

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

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

The description states a specific verb and resource ('List all agents registered in the project') and is differentiated from siblings: get_agent retrieves a single agent, register_agent creates one, and the phrasing 'List all' makes the scope explicit. An agent can distinguish this from get_agent without opening schemas.

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

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

The description clearly states when to use the tool (list all agents) and explicitly points to register_agent as the alternative for creating an agent, which serves as a when-not/when-to-use distinction. It does not explicitly mention get_agent for single-agent lookups, but 'List all' implies that contrast strongly enough.

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 indicate read-only, idempotent, non-destructive, and closed-world behavior; the description goes well beyond them by disclosing that plaintext key values are never returned, when fields are absent, that last_used_surface is spoofable, and that chain revocation follows created_by_key_id. No contradiction exists.

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

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

Every sentence contributes operational or security-critical detail, and the key limitations (no plaintext, spoofable surface) are stated explicitly. Despite density, the content is organized and free of 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?

Since there is no output schema, the description carries the burden of documenting return behavior; it covers all key fields, absence conditions, and the security caveat. An agent can safely call and interpret results without additional lookup.

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, the schema fully covers input semantics, so the baseline of 4 applies. The description appropriately invests in output semantics instead of parameter detail.

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

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

The description states a specific verb and resource — "List all API keys in the project" — and clarifies the non-secret prefix's role for revoke_api_key. This clearly distinguishes it from create/revoke key siblings and leaves no ambiguity about what operation is performed.

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 provides the prerequisite (admin scope or higher) and explicitly connects its output to revoke_api_key for key identification. It does not explicitly discuss when not to use it, but the listing purpose and related key-lifecycle siblings give clear context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description goes well beyond by disclosing the required auth scope, the no-paging behavior, the per-row outcome semantics, and especially the security-relevant 'untrusted_fields' wrapping. This is valuable behavioral context the 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?

The description is dense but every sentence earns its place: auth, purpose, row semantics, default window, paging limitation, and result wrapping are all covered. It is front-loaded with the core action and the user-facing question, then moves into supporting details without redundancy.

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

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

With no output schema, the description carries the full burden of explaining return shape and delivers with `data` and `untrusted_fields`. It also covers auth requirements, default time window, filtering semantics, and explicitly states the missing paging behavior. The agent has enough to safely invoke 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%, so the baseline is 3; the schema already documents limit, status, and monitor. The description adds operational meaning to the status parameter (pending, delivered, dead, suppressed with concrete causes) and explains row granularity, which helps the agent choose filters. It does not add much for limit or monitor, but those are adequately described in the schema.

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

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

The description states a specific verb and resource ('List recent alert deliveries across every monitor in the project') and explains the exact diagnostic scenario it answers, including the statuses returned. This clearly differentiates it from siblings like list_destinations and gets the agent pointed at the right tool.

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 provides an explicit use case ('my monitor went down and I was not paged...') and tells the agent when not to use it: paging is intentionally not exposed, and full archive needs belong to the dashboard's delivery log. This is direct when/when-not guidance without leaving the agent to infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which are consistent with listing. The description adds value by specifying the required auth scope and listing the channel types returned, going beyond the annotation information 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?

Two sentences with no filler. The auth requirement is front-loaded, followed by the core action and channel types, then a practical next step. Every clause adds 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 simple list tool with no output schema, the description explains the return scope (all destinations and their types) and how to use the results (routing rules). Nothing critical is missing for an agent to successfully call and leverage 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?

There are no parameters (schema coverage 100% with no properties), so the description carries no burden for parameter documentation. Per the baseline rule for 0 parameters, a score of 4 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?

Description states the specific verb 'List' with a clear resource ('all notification destinations') and enumerates the channel types (email, webhook, Slack, Discord, Telegram). This fully distinguishes it from siblings like create_destination, update_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?

Provides the prerequisite of API key scope ('read scope or higher') and a direct follow-up use case ('Use channel IDs to configure routing rules for monitors'). It doesn't explicitly state when not to use this tool versus alternatives, but the context is clear enough for an agent to infer the appropriate usage.

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 mark it read-only, idempotent, and non-destructive, but the description adds meaningful behavioral context: response ordering (newest first), open-incident semantics via closed_at=null, the wrapper shape, and the security-sensitive warning that untrusted_fields must be treated as data, not instructions.

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

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

Four compact sentences deliver one distinct value each: authorization, purpose, ordering/semantics, and response-wrapping/security. There is no filler or repetition.

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

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

Given a small 2-parameter schema, no output schema, and helpful annotations, the description covers authorization, ordering, open/closed semantics, output shape, and a safety-critical warning about untrusted_fields. The agent has everything it needs to call this tool correctly.

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

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

Schema coverage is 100% and the schema already documents both id and limit, including defaults and max. The description adds no significant parameter-specific behavior, so the baseline score of 3 applies.

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

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

The description names a specific verb and resource: 'List recent incidents (downtime events) for a monitor.' It also differentiates open vs. closed incidents with 'An open incident has closed_at=null,' which helps distinguish this from list_open_incidents and similar monitor list tools.

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

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

It states an explicit prerequisite — 'Requires an API key with the read scope or higher' — and gives concrete usage context for a monitor-specific incident listing. It does not explicitly name alternative sibling tools or state when not to use it, but the behavior described is clear enough for most selection decisions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, lowering the burden on the description. The description adds useful behavioral context: it requires 'read scope or higher' and operates within the authenticated project. It does not mention pagination or rate limits, but these are minor for a simple read-only list.

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

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

Three sentences, no filler, and the key operational requirement (read scope) is front-loaded. Every sentence contributes either scope, return shape, or filtering behavior.

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

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

For a read-only list tool with one optional parameter and no output schema, the description provides the API key scope, project context, returned fields, and filter behavior. Nothing an agent needs to call it correctly is missing.

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

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

The input schema fully documents the single optional tag parameter with an example, so the schema carries the semantic weight. The description adds only the phrase 'filter by a single tag,' which is a minor clarification rather than substantial new 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 clearly states the verb and resource: 'List all monitors in the authenticated LastPing project' and enumerates the returned fields. It does not explicitly contrast with sibling get_monitor, so it stops short of full sibling differentiation.

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

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

The description provides some context—authentication scope and optional tag filtering—but never states when to prefer this tool over get_monitor or other monitor-related siblings. The usage is implied by the listing purpose rather than explicitly guided.

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?

Even though annotations already mark this readOnly/idempotent/non-destructive, the description adds a wealth of behavior beyond annotations: read-scope auth requirement, newest-first ordering, absence semantics ('ABSENCE MEANS NO EVIDENCE — NEVER GOOD NEWS'), per-field degradation behavior, result wrapping, and the untrusted_fields warning. This is exemplary disclosure.

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 unusually long, but it is front-loaded with the core purpose and call timing, then organized into scannable bullets for payload fields and absence semantics. It is verbose and slightly editorial in places, yet each section adds practically useful detail that structured annotations and the input schema do not provide.

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 tool with no output schema, the description is remarkably complete: it covers auth, invocation timing, interpretation of every meaningful field, absence semantics, follow-up write-back via add_incident_note, and security handling of untrusted_fields. Nothing essential is missing for an agent to call and act on this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. Both agent_id and limit are already well described in the schema, including defaults and ordering effects. The description adds context around what the inbox covers, but it does not need to, and does not materially extend the schema's parameter documentation.

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

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

The description names a specific verb and resource: read/list the agent's failure inbox, i.e. every incident currently OPEN on the monitors it owns, in newest-first order. This clearly distinguishes it from the generic sibling list_incidents by scoping it to 'this agent's' monitors and open incidents.

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 says to call this at the START of a run, before doing work, and explains this is how an agent learns what broke while it was not running, with no webhook/chat/mailbox required. It does not explicitly contrast it with list_incidents, but the when-to-use guidance is clear and actionable.

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 useful behavioral context: the API key requirement and the nuance that the public URL is only present for public pages. It also reveals that each status page includes its monitors, which helps an agent anticipate the response shape.

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

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

The description is three sentences, each serving a distinct purpose: auth requirement, list action with fields, and conceptual context with a concrete follow-up usage. It is front-loaded with the essential requirement and avoids redundancy. 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?

Given the tool is a simple zero-parameter, read-only list operation with no output schema, the description is complete: it covers auth, the exact fields returned, the meaning of a status page, and its role before update_status_page. There is no missing information an agent would need 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?

The input schema is empty with 100% schema description coverage and zero parameters, so there are no parameter semantics to document. The description does not need to add parameter details, and the baseline for a zero-parameter tool is 4. No parameter-related gaps exist.

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 explicitly states what the tool does: it lists the project's status pages and enumerates the returned fields (id, slug, title, monitors, visibility, public URL). It also defines a status page, distinguishing it from the related monitor tools. This is a clear verb+resource+scope statement.

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

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

The description gives a specific usage context: it is the read you need before calling update_status_page because check_ids replace the monitor set. It also states the required auth level (API key with read scope or higher), giving the agent an explicit precondition. No alternative list tool exists among siblings, so the when-to-use guidance is sufficient.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds value by noting the API key requirement ('write scope or higher') and the behavioral detail that the monitor still receives pings but does not alert. This goes beyond the annotations without contradicting them.

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 three concise sentences with no fluff: auth requirement, purpose, and behavioral effect. It is front-loaded with the auth requirement and delivers all key information efficiently.

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 fully covers the necessary context: what it does, the effect on pings and alerts, and the required scope. There is no missing information that would prevent an agent from calling 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?

The input schema has 100% coverage: the only parameter 'id' is described as 'Monitor UUID.' The description does not add any parameter-specific meaning beyond what the schema already provides, so a 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?

The description states a specific verb+resource: 'Pause a LastPing monitor so it stops alerting (paused=true).' It clearly distinguishes from siblings like resume_monitor and snooze_monitor by specifying the exact effect (stops alerting but still receives pings). The purpose is unambiguous.

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

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

The description provides clear context: pausing stops alerting. However, it does not explicitly mention alternatives like resume_monitor or snooze_monitor, nor does it state when not to use this tool. It gives a clear trigger (want to stop alerting) but lacks explicit exclusions or alternative 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?

Beyond annotations, the description discloses important behaviors: it is not an implicit create, duplicate slugs are rejected, re-registering the same name is safe, and an unknown agent name yields a 400 UNKNOWN_AGENT error. This gives the agent a clear model of the side effects and constraints.

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 well-organized, front-loading the auth requirement and core action before usage rules, attachment flow, and edge cases. Each sentence contributes meaningful operational guidance, with no filler beyond a brief motivational clause that supports contextual understanding.

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 there is no output schema, the description compensates by naming the return values (id, slug, wire-up instructions) and explaining the full lifecycle: registration, monitor attachment, duplicate behavior, and error semantics. An agent has enough to invoke this tool correctly and integrate it with create_monitor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying the name parameter to slug derivation and duplicate-slug behavior, and notes that the description parameter is optional. It does not deeply elaborate on parameter formats, but the schema already handles most of 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?

The description states a specific action—'Register a new autonomous agent in the project's agent registry'—and clearly distinguishes this from sibling tools like create_monitor, get_agent, update_agent, and delete_agent. It also explains the tool's unique output: id, slug, and wire-up 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?

The description provides explicit usage context: call it once per autonomous worker, not per monitor, and requires API key write scope or higher. It also names the integration path—pass the returned agent_id or slug to create_monitor's agent_id parameter—and clarifies when re-running is appropriate.

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, the description adds meaningful behavioral details: requires write scope, transitions the monitor to paused=false, and clarifies that alerting resumes on the next missed ping. It does not contradict the annotations; idempotentHint=true is consistent with resuming 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?

Two short sentences with no filler. The authorization requirement is front-loaded, followed by the action and its consequence. Every sentence contributes essential 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 single-parameter action with no output schema, the description covers prerequisites, the state change, and the post-condition. Nothing needed to select or invoke the tool 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 input schema already documents the single required parameter with 100% coverage ('Monitor UUID'), so the description does not need to add parameter-level detail. Baseline 3 is appropriate because the schema carries the semantic load.

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 uses a specific verb ('Resume') plus a specific resource ('paused LastPing monitor') and the exact target state (paused=false). This clearly separates it from sibling tools like pause_monitor and snooze_monitor.

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

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

It states a precondition (API key with write scope or higher) and scopes the tool to paused LastPing monitors, which gives clear contextual usage. It does not explicitly name alternatives or say when not to use it, but the sibling set makes the intended use obvious.

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 indicate destructiveHint=true and idempotentHint=true, but the description goes beyond by explaining the recursive revocation and its immediate effect on authentication. It also highlights the irreversibility and potential to revoke multiple credentials, providing critical context that annotations alone do not convey.

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

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

The description is concise and front-loaded with the most critical information (requirements and irreversible action). It packs substantial detail into a few sentences without unnecessary fluff. Slightly verbose in the middle explaining the cascade rationale, but it earns its place by aiding agent judgment.

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

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

Given the tool's complexity (destructive, cascading, irreversible), the description is complete. It covers prerequisites (admin scope), preconditions (check list_api_keys), behavioral outcomes (immediate revocation of all descendant keys), and the irreversibility. The absence of an output schema is acceptable because the tool's effect is what matters, not the response.

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

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

The schema covers the single parameter with a description and a pointer to list_api_keys, but the description reinforces the meaning by emphasizing the cascade and the need to verify the key's children. Since schema coverage is 100%, the description adds value by clarifying the consequences of using the parameter, though the schema already does most of the work.

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

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

The description clearly states the action ('Permanently revoke an API key') and the resource (an API key), and it highlights the cascading effect that distinguishes it from a simple revocation. It is specific and unambiguous, differentiating it from sibling tools like create_api_key and list_api_keys.

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 provides explicit guidance: it requires admin scope, advises checking list_api_keys first to understand the cascade, and warns that the action is irreversible. It also explains the rationale for cascading, helping the agent understand when it's appropriate to use this tool.

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

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

Annotations flag destructiveHint=true and idempotentHint=true; the description usefully narrows that destruction by disclosing read-modify-write semantics ('All other existing templates are preserved') and pre-save variable validation. It adds real context beyond the annotations, though it doesn't describe response format or failure modes on invalid variables.

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

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

Front-loaded correctly with auth and purpose in the first sentence, but the 22-item variable list plus two long provider-specific paragraphs on failing_stage and body push this well past what most calls need. The content is non-redundant but heavy for an inline tool description.

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

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

With no output schema and only four well-documented params, the description covers everything an agent needs: auth scope, mutation semantics, preservation guarantees, reset behavior, and variable availability including provider caveats.

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 baseline is 3, but the description adds meaning beyond it: empty-string template resets to the built-in default and cause selects a per-cause override. The enumerated variable list further defines what template can legally contain, which the schema does not.

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

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

States a precise verb+resource+scope: 'Set or clear a single alert message template on a monitor.' The word 'single' and the sibling name get_alert_templates make it immediately distinguishable from the read counterpart and from broader monitor updates.

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 operating context: requires write scope, pass an empty string to reset to default, omit cause for an event-type-wide template. It does not explicitly name alternatives (e.g. get_alert_templates for reading current templates), 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?

Annotations declare destructiveHint: true and readOnlyHint: false, but the description goes much further, explicitly warning that 'every destination you leave out stops receiving that event, including ones somebody else configured.' It also discloses the authentication requirement (write scope) and the need for destinations to be verified/enabled. No contradiction with annotations; the description enriches the behavioral profile.

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

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

The description is a single, dense paragraph where every sentence earns its place: the action is front-loaded, the critical destructive warning is highlighted in caps, and each subsequent sentence provides a necessary instruction (prerequisite, ID retrieval, edge case, validation). There is no fluff; the structure guides the agent from understanding to execution.

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 mutating tool with no output schema, this description covers all essential operational context: prerequisites (call get_monitor first), how to compute the correct channel_ids, the effect of empty input, destination verification requirements, and where to get IDs. Nothing an agent needs to call this tool correctly and 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% for all three parameters, so the baseline is 3. The description adds beyond the schema by instructing agents to pass existing IDs plus new ones, emphasizing that channel_ids replaces the whole set, and noting that destinations must be verified and enabled. This extra context helps agents avoid mistakes that the schema alone would not prevent.

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 clearly states the tool's purpose: 'Route a monitor's alerts for one event type to a set of destinations (channels).' It further clarifies the critical behavior that it replaces the entire set, which distinguishes it from any additive routing tools and gives the agent an accurate mental model. The description also points to related tools (get_monitor, list_destinations) that help the agent understand its role in the workflow.

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 provides explicit procedural guidance: 'CALL get_monitor FIRST and read its `routes` field' and 'Use list_destinations for IDs.' It explains when to use the tool (to set routing) and precisely how to construct the channel_ids by preserving existing IDs plus new ones. It also covers the empty-input edge case for clearing routing. This is actionable and 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 already signal idempotence and non-read-only behavior; the description adds useful behavioral context by stating the auth requirement, the effect of suppressing alerts, and how clear=true removes an active window. This meaningfully supplements the structured annotations without contradicting them.

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 compact and well-structured: auth prerequisite, core action and effect, then parameter usage rule. Every sentence adds necessary information with no filler or repetition of the tool name.

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

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

Given the moderate complexity of four parameters and no output schema, the description covers the essential call requirements: auth, semantics, mutual exclusivity, and clearing behavior. It could mention response or error behavior, but nothing critical is missing for invoking 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?

The schema already documents each parameter and the OR relationship, but the description adds the 'exactly one of' rule and concrete examples like '1h' and '24h'. This reinforces the intended usage beyond the schema's individual field descriptions, though the schema coverage is already high.

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 clearly states the action: 'Set or clear a maintenance window on a monitor', and explains the effect that the monitor will not alert during the window. It distinguishes this tool from generic update tools by focusing on the maintenance/snooze concept, though it does not explicitly contrast it with sibling tools like pause_monitor or resume_monitor.

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 provides clear context on when the tool is appropriate: managing a maintenance window to suppress alerts. It also gives explicit operational constraints such as requiring a write-scope API key and providing exactly one of duration, until, or clear. It does not mention when not to use it or explicitly name alternatives.

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

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

Annotations indicate a non-read-only, side-effectful operation, but the description adds crucial context: it sends a test alert immediately by default, and explains the resend_verification mode's behavior (including idempotency on verified destinations and the 400 error for non-email types). It does not contradict annotations. The description carries the behavioral burden well, though it could mention the exact response format, which is absent.

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 efficiently structured: it front-loads the primary purpose, then provides conditional alternatives and error handling. Every sentence adds necessary detail without redundancy. It is longer than average but earns its length.

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

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

Despite having no output schema, the description explains the expected outcome (test alert or resend link) and key error cases (unverified email, 400 for non-email). Given the tool's simplicity and the richness of the annotations and schema, nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds value beyond the schema by explaining the conditional semantics of resend_verification (when to use it, that it's idempotent, and that it only applies to email destinations). This is a solid improvement over the bare schema.

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

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

The description clearly states the verb ('send') and resource ('destination'), and explains the purpose: to move a destination from 'created' to 'known to work' by delivering a test alert. It explicitly differentiates from the resend_verification mode, so an agent can distinguish it from sibling tools like create_destination or set_route.

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 provides explicit guidance on when to use this tool: after create_destination to confirm credentials. It also states when NOT to use it (for unverified email destinations) and names the alternative (resend_verification=true). This is a textbook example of usage 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 indicate a destructive, non-read-only, idempotent operation. The description adds value by explaining merge-patch semantics, the auth requirement (write scope), and the side effect that slug is immutable—clarifying that existing references by slug remain valid. This exceeds what annotations 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?

The description is moderately long but each sentence contributes: auth requirement, core operation, merge-patch semantics, and slug immutability. It is front-loaded with the auth requirement and clearly structured, though it could be slightly trimmed without losing key points.

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

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

For a mutation tool with no output schema, the description covers the essential aspects: auth, behavior, parameter nuances, and side effects. It does not describe the return value, but that is not critical for calling the tool correctly. The description is sufficiently complete for an agent to use it safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters by explaining that description can be omitted (safe default) or passed as an empty string to clear, and that name changes do not affect the slug. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the action ('Update an existing LastPing agent's name/description'), the resource (agent), and the identifier (UUID). It distinguishes itself from siblings like delete_agent and get_agent by focusing on the update operation and the specific fields that can be changed.

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 when to use it (to modify name/description) and provides important constraints like slug immutability and merge-patch behavior. It does not explicitly name alternatives, but the context is sufficient for an agent to decide when this tool is appropriate.

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?

Excellent disclosure beyond annotations: auth scope requirement, partial-update semantics ('Only the fields you pass are changed'), immutability of kind, and the side effect that changing email address resets verification and sends a confirmation email. These are critical behaviors not captured by 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?

Four tight sentences, each earning its place. Auth requirement front-loaded, then the core action, then the immutability constraint, then the notable side effect. Zero waste.

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

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

Complete for a mutation tool. Annotations cover safety (destructive), description covers auth, partial-update behavior, immutability, and side effects. No output schema exists but none is needed for this update operation. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema thoroughly documents each parameter including the complex nested config shape. The description reinforces partial-update semantics but doesn't add much beyond the schema. Baseline 3, raised to 4 for reinforcing the 'omit to leave unchanged' contract and the config kind constraint.

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 ('Update a notification destination's name and/or config in place') and clearly distinguishes from sibling delete_destination and create_destination. The scope of what can be updated (name/config only) is explicit.

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 when-to-use context by stating the kind cannot be changed and pointing to delete-and-recreate as the alternative. Also states auth requirement. However, it doesn't explicitly name the sibling tools or contrast with test_destination/create_destination.

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

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

Goes well beyond the annotations: it discloses that tags/assertions/guards REPLACE rather than merge (explaining the destructiveHint), that slug and ci_provider are immutable, that omitted fields are preserved while explicit null clears filters and empty strings do not, and specific error codes (UNKNOWN_AGENT, MAX_RUNTIME_NOT_SUPPORTED). This is exactly the mutation-risk context an agent 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?

Front-loads the two facts an agent must act on first (write scope, merge-patch semantics) before the longer explanatory clauses. It is a single dense paragraph with some redundancy against the parameter descriptions, but no filler sentences.

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 28-parameter, no-output-schema mutation tool this is complete: it covers permission needs, patch semantics, immutability, clearing conventions, and cross-tool prerequisites, so an agent can invoke it correctly without inference.

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

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

Schema description coverage is 100%, so the per-parameter schema already carries the semantics and the baseline is 3. The prose adds conceptual framing (assertion vs guard purpose, on_demand tradeoffs) but much of it restates schema text rather than adding new parameter-level meaning.

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

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

States a specific verb+resource+scope: 'Update an existing LastPing monitor's schedule/config by UUID using merge-patch semantics.' It distinguishes update_monitor from create_monitor/delete_monitor in the sibling set by naming the merge-patch behavior and immutability of slug/ci_provider.

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 entry conditions ('Requires an API key with the write scope or higher') and routing context (must call register_agent first to obtain an agent_id, ci_provider changes require delete+recreate). It does not, however, explicitly frame when to prefer this tool over siblings like pause_monitor/resume_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?

Beyond the annotations, the description discloses major behavioral traits: it reads the page first and merges, omitted arguments leave values unchanged, passing check_ids replaces the entire monitor set, slug changes break existing links, and public visibility publishes monitor names. This goes well beyond the destructiveHint and idempotentHint annotations without contradicting them.

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 every sentence contributes: authentication, core capability, merge semantics, monitor-set replacement, and the most dangerous side effect (slug changes). The critical warnings are front-loaded, and the wording is efficient 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 mutation tool with no output schema, the description covers invocation essentials thoroughly: auth requirements, side effects, and error-relevant constraints. The only gap is that it does not state what a successful call returns (e.g., updated page object vs. simple success), which an agent might need to verify the result.

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

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

Although the schema descriptions are already rich (100% coverage), the tool description adds crucial cross-parameter semantics: the replace-not-append behavior of check_ids, the danger of slug changes, the merge behavior for omitted arguments, and the privacy implications of visibility. This meaningfully amplifies what an agent can infer from the schema alone.

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

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

The description names a specific verb ('Update'), a specific resource ('a status page'), and enumerates exactly which aspects can be changed: title, slug, visibility, and the set of monitors. This clearly distinguishes it from siblings like update_monitor, create_status_page, and delete_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?

The description gives clear context: it is the tool for changing an existing status page, requires write-scoped API credentials, and explains the merge behavior that differentiates it from a blank overwrite. It does not explicitly call out when to prefer create_status_page or delete_status_page, but the update semantics are unmistakable.

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