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 already mark this as a non-read-only, idempotent, non-destructive operation, and the description reinforces and extends this: it states the required write scope, that existing traces are never backfilled, that repeated adoption into the same agent changes nothing, and that results are wrapped with untrusted_fields that must be treated as data. 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, core action, both modes, error semantics, idempotency, and output wrapping. It is front-loaded with the most important facts and uses clear separation of concerns.

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 unusually complete: it covers authentication, creation vs merge behavior, error codes, idempotency, non-backfill behavior, and the response wrapper. An agent has everything needed to invoke it correctly and interpret results 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?

The input schema already describes both parameters (id as discovered source UUID, agent_id as optional agent UUID), so the baseline is 3. The description adds meaningful behavior: omitting agent_id triggers agent creation, agent_id should come from suggested_agent_id, and the 409 error conditions clarify parameter choice consequences.

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 action: 'Count a discovered trace source's traces under an agent from now on.' It clearly distinguishes the two modes (create a new agent vs merge into an existing one) and references sibling tools register_agent and list_discovered_agents, so an agent can tell this apart from related operations.

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

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

It gives explicit when-to-use guidance: omit agent_id to create a new agent, provide agent_id (from suggested_agent_id in list_discovered_agents) to merge. It also handles the edge case where the slug is taken (409 AGENT_EXISTS) and instructs to merge instead, plus notes that re-adopting is a no-op and cross-agent adoption returns 409 ALREADY_ADOPTED.

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

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

With all annotations false, the description carries the full burden and handles it well: it discloses that the plaintext is returned once and cannot be retrieved again, warns to store it immediately, and notes the admin requirement. These are exactly the non-obvious behaviors an agent needs to know.

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 with no filler: prerequisite, creation, one-time-secret warning, and the sibling alternative. The most critical information is front-loaded and every sentence earns its place.

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

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

For a security-sensitive mutation with no output schema, the description covers prerequisites, secret handling, expiry advice, and the correct alternative tool. Combined with fully documented parameters, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already explains every parameter thoroughly; baseline 3 applies. The description adds only a light hint to set expires_at for short-lived keys, which is marginal beyond the schema's detailed enum and explanation.

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 clear verb+resource: "Create a new LastPing API key," and the name itself is unambiguous. It also distinguishes itself from the sibling create_ingest_key by stating that tool is for exporter tracing keys, so an agent can tell them apart.

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

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

It states the prerequisite (admin scope or higher), gives a security directive (store immediately in a secret manager), and explicitly routes to create_ingest_key for the exporter-with-write-key case. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations only indicate non-readonly, non-open-world, non-idempotent, non-destructive. The description adds substantial behavioral detail: email kinds are created unverified, a confirmation link is required, unrelated fields are ignored, and host pinning does not prove ownership. It also explains the cap behavior on failure.

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 well-organized, with the most important constraints front-loaded. Every sentence delivers specific operational knowledge, from authentication through creation, verification, cap handling, and post-creation use.

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 large parameter set and no output schema, the description covers prerequisites, side effects, failure modes, return value, and downstream usage. This is more than sufficient for an agent to select and correctly invoke the 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 description does not need to restate parameter docs. It adds value beyond the schema by explaining that unrelated fields are ignored and that fields should be selected according to the chosen kind, which clarifies a likely point of confusion for callers.

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 ('Create a notification destination'), names the resource ('channel'), and clarifies its purpose ('monitors can route alerts to'). It clearly distinguishes from related siblings like set_route, update_destination, and delete_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 explicit context: required API scope, which kinds are usable immediately versus email needing verification, the 25-destination cap, and the specific DESTINATION_CAP_REACHED fallback of deleting a destination. It also directs the caller to pass the new id to set_route, giving clear next steps.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which are minimal. The description adds substantial behavioral context: the key is returned ONCE in plaintext, it can send traces/metrics/logs/pings for one monitor and nothing else, every REST call refuses it, and it cannot read or change anything in the account. It also discloses the 90-day expiry cap. This goes well 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 dense but every sentence earns its place: scope, permissions, relationship to get_trace_setup, plaintext-once warning, security handling, and expiry behavior. It is front-loaded with the most important fact (requires write scope) and the core purpose. It is slightly long but not bloated; the warnings are necessary for safe use.

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 credential-creation tool with no output schema, the description covers what the agent needs: prerequisites (write scope), the one-time plaintext return, the binding to a monitor, the expiry default, and the security handling. The sibling context (get_trace_setup) is referenced, and the parameter schema is fully covered. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the security-critical handling of the returned key, the relationship to get_trace_setup, and the expiry cap behavior. It doesn't add much per-parameter detail beyond the schema, but the context it adds is valuable. A 4 is appropriate because the description enriches the parameters' purpose even though the schema already documents them.

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 ('Create'), a specific resource ('a tracing key for one monitor'), and the exact scope ('ingest-scoped LastPing key bound to that monitor'). It clearly distinguishes this from generic create_api_key by emphasizing the monitor binding and ingest-only permissions, so an agent can tell it apart from siblings without opening the schema.

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

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

The description explicitly says this is the credential get_trace_setup's steps need, tells the agent to omit expires_at for a 90-day key, and warns against using one's own LastPing API key as an exporter's credential. It also gives clear security handling instructions (write to git-ignored file, never echo back). This is explicit when-to-use and how-to-use guidance with exclusions.

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

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

The annotations declare idempotentHint=true, but the description says a call without a slug 'Create[s] a new' monitor and only updates when a slug matches. Repeated identical calls without a slug would therefore create duplicates, so the described behavior contradicts the idempotency annotation. While the description itself is transparent about auth, upserts, and the one-time CI secret, the rule requires a score of 1 on annotation 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 front-loaded with the auth requirement and the core create/upsert behavior, and each parameter is organized as rule, rationale, and caveat. It is long and repetitive—the 'on an upsert ... pass the current value' clause recurs across many fields—so it loses a point, but the length is largely justified by 29 interdependent parameters.

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?

The description covers every parameter's meaning, conditional combinations, defaults, upsert effects, and failure modes, and it explicitly discloses the one-time return of the CI secret/webhook URL. With no output schema, it stops short of stating the full response shape (e.g., the created monitor id), but an agent has enough to invoke the tool and interpret the critical side effects.

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?

Even though schema coverage is 100%, the description adds far more than the schema: per-monitor-type requirements, API error codes like 400 FIELD_NOT_IN_SHAPE and 400 UNKNOWN_MONITOR_TYPE, upsert pass-the-current-value caveats, and conceptual warnings such as probe_expected_body being the difference between 'the server answered' and 'the app works'. This far exceeds the baseline for a fully documented schema.

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

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

The description names the exact action and resource: 'Create a new LastPing monitor', and immediately clarifies the upsert behavior '(or update an existing one if slug matches — returns 'updated' note on upsert)'. This clearly distinguishes it from siblings like update_monitor and delete_monitor, so an agent knows precisely what this 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?

The description provides explicit routing: heartbeat/ci monitors need schedule_kind while http monitors need probe_url and probe_interval_s; ci_provider is called 'the ONLY place it can be set' and the description explicitly says to use update_monitor for CI filters that an upsert would silently drop. It also gives clear 'when not to' guidance, such as http monitors rejecting schedule fields and on_demand monitors rejecting period_s/cron_expr.

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?

Annotations already indicate destructive and idempotent behavior, but the description adds meaningful context: required auth scope, scoping to a single event type, preservation of other event routing, and the error response for unconfigured event types. 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?

Four focused sentences with no filler. It front-loads the auth requirement and core behavior, then provides the alternative and error condition. Every sentence 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 two-parameter destructive tool with no output schema, the description covers auth, exact effect, non-effect on other event types, alternative usage, and error behavior. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, with both parameters already documented and event_type constrained by an enum. The description does not add parameter-specific detail beyond what the schema provides, so the 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?

States a specific verb and resource: 'Stop routing ONE event type of a monitor to any destination.' It clearly defines scope and consequence, and is distinguishable from siblings like set_route and delete_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?

Explicitly gives the alternative workflow: 'To drop one destination but keep the rest for the same event type, call get_monitor and then set_route.' It also mentions the required API key scope and the 'route not found' error condition, leaving little ambiguity about when to use it.

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

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

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 mark this as read-only and idempotent, and the description adds valuable extras: the API key scope requirement, the response envelope with untrusted_fields, and a security warning to treat those fields as data. This goes well beyond the structured 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 tightly-packed sentences: the auth requirement, the action, the response content, and the security note. Each sentence earns its place, and the most critical information is front-loaded.

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

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

For a single-parameter read-only tool with no output schema, it covers everything: the auth prerequisite, how to obtain the ID, what the response contains, and how to handle untrusted fields. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the id parameter, which already includes the UUID source from register_agent or list_agents. The description reiterates this but adds no new semantic details, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Get'), a resource ('a single LastPing agent'), and a scope ('by UUID'). It clearly distinguishes from list_agents by emphasizing 'single' and noting it returns the same fields, which prevents confusion with the list operation.

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

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

It provides clear usage context: requires an API key with read scope or higher, and tells the agent to use list_agents or register_agent to obtain valid IDs. It does not explicitly contrast this with get_agent_dependencies/get_agent_usage, but the general purpose is well implied.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the API-key read scope requirement, the p95 bucket-ceiling caveat with p95_is_floor, the 50-row cap with `more`, and the security-sensitive `untrusted_fields` wrapper. These are concrete behavioral details an agent needs and that annotations do not provide.

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

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

The description is dense but largely earns its length, front-loading auth and the core listing behavior before covering caveats and response wrapping. It could be tightened because the direction sentence partly repeats the schema and the single-paragraph format lacks visual structure.

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?

Even with no output schema, the description covers result shape, row limits, ordering, metrics, direction semantics, and untrusted-field handling. An agent has enough context to invoke the tool correctly and interpret its response 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?

The input schema already documents all three parameters clearly with 100% coverage, so the baseline is 3. The description adds only minor repeated direction phrasing and output-level context, not meaningful new per-parameter semantics.

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

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

The description states a specific verb and resource: 'What one agent calls, heaviest first, from its OpenTelemetry traces.' It enumerates dependency types and metrics, making the tool's role unambiguous. It also distinguishes itself from a sibling by noting that 'get_agent already carries the top five.'

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 use cases: 'Use it to answer "what does this agent depend on", "which of its calls fail" or "what is it spending on models".' It also signals when a lighter alternative suffices by saying 'get_agent already carries the top five.' This is clear when-to-use guidance with an alternative.

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

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

Annotations already signal readOnly/idempotent/non-destructive, and the description goes far beyond them: cache reads are included in tokens_in, origin rows are never summed, cost_source semantics are explained, and untrusted_fields warns about data-vs-instructions. 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?

The description is dense and every sentence carries meaningful information, but it is a single run-on block and front-loads the auth requirement rather than a crisp one-line purpose. It is appropriately sized for the tool's complexity despite the structural roughness.

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 must act as the return contract, and it does: it enumerates all fields, explains origin and cost_source values, describes by_agent ordering, and documents the data/untrusted_fields wrapper. Auth requirements and id modes complete the call contract.

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 explaining the id-less mode produces project-level traces-only totals plus by_agent, and clarifies cost_usd is decimal text. Range semantics are already fully 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 clearly states the resource and behavior: it returns model usage rows per model per UTC day, with fields enumerated. It also distinguishes the two calling modes by id, making it unmistakable next to siblings like get_agent.

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

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

It gives clear usage context: 'With id, one agent's usage; without id, the whole project's, traces only, plus by_agent' and states the API-key scope requirement. It does not explicitly name alternative tools, but the call modes are well specified.

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 mark readOnly, idempotent, non-destructive, and the description adds compatible details: API key read-scope requirement, the re-run behavior of hook_install (replaces ~/.claude/lastping-report.sh keeping a .bak), how the protocol works, and the pointer that tracing keys come from create_ingest_key rather than the caller's API key. Nothing contradicts 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 content is well organized but extremely long for a one-parameter read tool, mixing selection guidance, protocol mechanics, tracing setup, and discovery advice in a single unbroken text block. It earns its place topically, but an agent must parse a dense wall of text to extract the call decision; trimmer sibling-specific guidance would be more concise.

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 telling the agent what will be returned and how to act: it names the three reporting mechanisms, the universal fallback, the Claude Code shortcut, the command wrapper, the success/fail/start/step protocol, and pointers to expectations, discovery, and tracing flows. Nothing an agent needs to correctly invoke and follow up 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 single parameter id is already documented in the schema as 'Monitor UUID (from create_monitor or list_monitors)', so schema coverage is 100%. The description adds only a slight contextual cue by saying to call the tool right after create_monitor; it does not need to compensate for schema gaps. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get everything needed to make a monitor actually report: the ping URL, copy-paste check-in snippets, and the three MECHANISMS for reporting, returned together.' This clearly distinguishes it from sibling get_* tools, which retrieve resources rather than report-instructions. The name is reinforced without being merely restated.

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 is unusually explicit about selection: call it 'right after create_monitor', choose by the monitored thing by reading reporting_options, use how_to as universal default, hook_install only for Claude Code, and run_wrapper for command-launched processes. It also tells agents when not to translate hook_install into other hook systems, which is valuable exclusion 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 read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: timeline capping at 200 events, span capping at 2,000, truncation flags, terminal event always present, span ordering rules, outcome semantics including the unfinished case, and the untrusted_fields security warning. This goes well beyond what annotations 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?

Long but densely informative with no filler; every sentence adds distinct value, from auth requirements to truncation behavior to output wrapping. Key details are front-loaded: purpose first, then usage context, then edge-case semantics.

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 complex read tool with no output schema, the description covers all the nuances an agent needs: event ordering, verdict semantics, truncation caps, outcome values, span shape, GenAI block conditionality, and result wrapping. Together with the annotations, this is fully actionable.

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 both id and rid fully. The description mentions id + rid as the pairing needed to target a run, but does not add meaningful parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

States a clear, specific purpose: get ONE run's full timeline, not a summary. It enumerates exactly what is included (events, assertions, terminal output, CI metadata, OTLP spans) and distinguishes itself from get_run_history and list_open_incidents, which provide more limited views.

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

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

Explicitly says when to use it: after get_run_history or list_open_incidents has identified a specific run and you need the detailed blow-by-blow rather than the summary row. It also names the relevant alternative tools, making the selection decision clear. The read-scope requirement further frames 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?

The description discloses extensive behavioral details beyond the annotations: the distinction between duration_ms (computed by LastPing) and duration_s (provider-reported), the conditional presence of fields like steps and ci_meta, the exclusion rules for pings without ci_meta or rid, and the untrusted_fields warning. Annotations only state read-only/idempotent, so this adds substantial value.

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

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

Although the description is long, every sentence is information-dense and serves a purpose: scope definition, sibling differentiation, field presence rules, duration semantics, and output wrapping. It is front-loaded with the core purpose and alternatives, and the structure flows logically from general to specific.

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

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

With no output schema, the description explains the return structure (data and untrusted_fields), field presence conditions (steps only on matching rid, CI fields only with ci_meta, duration_ms separate), and edge cases (exclusion of pings without ci_meta/rid). It also covers authentication requirements. This is a comprehensive guide for an agent to invoke 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 provides 100% coverage for both parameters (id as Monitor UUID, limit with defaults/max). The description does not add new parameter semantics beyond what the schema states; it only mentions the absence of filters, which is a behavioral note rather than parameter meaning. Therefore the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Get structured run history for a monitor' with explicit scoping (both CI/CD and agent/heartbeat runs) and explicitly distinguishes it from sibling list_runs by noting it lists only ping-based runs and takes no filters. This provides a specific verb, resource, and clear 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 gives explicit when-to-use guidance: 'use list_runs for traced runs, for runs across every monitor, and to filter by outcome...' and states that this tool takes no filters. It also mentions the required API key scope. This is clear and actionable 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 mark it read-only and idempotent, and the description adds substantial behavioral context beyond that: 7-day retention, newest 20 attempts, the 'Answered 202 but kept nothing' class of outcomes, the two failures that leave no row, and the untrusted_fields security warning. 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 and long, but every section earns its place: auth requirement, purpose, when to call, per-attempt fields, refusal reasons, accepted-but-dropped reasons, empty-list troubleshooting, and result wrapping. It is not bulleted and is a heavy wall of text, but the complexity of the diagnostic tool justifies the 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?

With no output schema present, the description fully covers return shape: the 20 attempts, last_accepted_at, traced-run summary, per-attempt fields, reason-code meanings, and the data/untrusted_fields wrapper. It also warns about the field-injection risk and edge cases where no row is produced, making it complete for an agent to invoke and interpret.

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 fully documents monitor_id with a clear description and source functions, and schema description coverage is 100%. The description adds indirect context about monitor_ids through reason codes like unknown_monitor, but does not need to further explain the single parameter.

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

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

The description states a specific diagnostic purpose: explaining why traces, metrics, or logs sent to a monitor did or did not arrive, and lists the exact data returned. It distinguishes itself from siblings like get_trace_setup by explicitly referencing the test span that get_trace_setup describes and positioning this tool as the follow-up diagnostic.

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 it after the get_trace_setup test span, and whenever a user reports sending data that isn't showing up. It also gives fallback guidance for empty results ('check those two first'), plus the auth prerequisite, making the invocation context unambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description adds the API key requirement, the shape of the result (prompt and blocks/files), the need to get the key via create_ingest_key, and security rules about never echoing credentials or committing them. 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 adds essential information: prerequisites, usage trigger, execution instructions, security constraints, and output interpretation. It is front-loaded with the key purpose and prerequisites.

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 result structure (prompt, files), the prerequisite (API key), how to obtain the key, and verification steps. Nothing critical is missing for an agent to correctly invoke and use 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?

The schema already covers both parameters well, so the baseline is 3. The description adds extra meaning by explaining what the result's prompt represents for the named tool and that omitting the tool returns every block, which clarifies the optional parameter's behavior concretely.

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 the exact steps to make a tool send OpenTelemetry traces to LastPing for one monitor," with a clear list of what those steps cover. This distinguishes it from siblings like get_ping_instructions and get_trace_diagnostics by focusing on setup instructions for one 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 explicitly says when to call it: "Call this when a person asks you to set up tracing, observability or telemetry for a project." It does not explicitly name alternative tools to use instead, but the triggering context 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?

Beyond the annotations, the description richly discloses behavior: the live rollup of status from monitors, null semantics for usage_24h, the top_dependencies window, and the critical warning that untrusted_fields must be treated as data, never instructions. This adds substantial safety and operational context that annotations alone 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?

Although the description is long, every sentence earns its place: authentication, core behavior, field definitions, status semantics, dependency scope, creation alternative, and response wrapping. It is front-loaded with the essential 'list all agents' statement and then layers additional detail logically.

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 values, and it does so thoroughly: fields, status enum, usage_24h, top_dependencies, wrapper structure, and untrusted_fields security guidance. Nothing needed to call and interpret this 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 has zero parameters, so the baseline of 4 applies. The description appropriately focuses on response semantics instead of parameter behavior, and there are no parameters whose meaning needs clarification.

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.' It distinguishes itself from siblings like get_agent and list_discovered_agents by emphasizing 'all agents' and 'registered,' giving an agent a clear sense of what this tool does and does not do.

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 for use: it requires an API key with read scope or higher, and it explicitly routes users to get_agent_dependencies for more dependency detail and to register_agent for creation. It does not explicitly state when not to use this tool versus get_agent or list_discovered_agents, but the naming and 'all agents registered' phrasing imply the distinction.

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 mark the tool as read-only and non-destructive, and the description adds valuable behavioral details beyond that: pagination cap (50 rows, `more` counts the rest), response wrapping (`data` holds the response), and a security warning that `untrusted_fields` must be treated as data, not instructions. This is exactly the kind of context the description should supply.

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

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

The description is dense but each sentence earns its place: auth requirement, scope, examples, pagination, and response wrapping/untrusted fields. The ordering is logical (purpose first, then behavior), though the second sentence is a bit run-on and could be clearer without losing information.

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

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

With no output schema, the description compensates by explaining the response envelope, pagination, and the security-sensitive `untrusted_fields`. It references get_agent_dependencies for the standard fields rather than listing them explicitly, which is acceptable if that sibling's documentation is accessible, but it leaves a small gap for an agent that needs the full field list.

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

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

The input schema already provides full descriptions for both parameters (kind and range), including enum meanings and the range overlap behavior. The description does not add new parameter-level semantics beyond what the schema already documents, so the 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 states a specific verb and resource: list all dependencies called by the project's agents, aggregated across agents, with call counts and caller agents. It also names the sibling tool it relates to (get_agent_dependencies) and gives concrete example questions ('what calls postgres', 'which agents use this model'), making its purpose 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?

It explicitly gives use cases and implies a distinction from get_agent_dependencies by noting the same figures plus agents. It also mentions the required API key scope. However, it doesn't explicitly state when not to use this tool or direct the agent to a specific alternative, so it falls just short of full 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 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?

Beyond the annotations (readOnlyHint, idempotentHint), it discloses authentication needs, a 200-item limit, ordering by most recently seen, the response wrapper format, and the untrusted_fields security caveat. This provides substantial behavioral context not present in the structured 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?

Every sentence contributes necessary information: prerequisite, core definition, usage trigger, limits, output wrapper, and security warning. The description is dense but free of filler and front-loads the most important operational facts.

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

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

With no output schema, the description fully explains the response shape, fields, result count, ordering, and the untrusted-fields warning. Combined with sibling context, it gives an agent everything needed to call the tool correctly and interpret its result.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter-specific detail because none is needed; it instead clarifies output and usage context, which 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 uses a specific verb and resource, defining discovered agents as 'trace sources that sent spans but match no registered agent.' It lists the returned fields and clearly distinguishes this tool from the sibling list_agents by focusing on unregistered sources.

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

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

It gives an explicit trigger: 'Call this when traces arrive but an agent shows none of them.' It also names the follow-up tool, adopt_discovered_agent, and states the required API key scope, so an agent knows exactly when and how to proceed.

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 mark it read-only, idempotent, and non-destructive; the description goes well beyond these by adding auth requirements, detailed field semantics, the special 'unfinished' outcome behavior, filter/count interactions, pagination, response wrapping, and the untrusted_fields security warning. This is rich behavioral disclosure with no 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 dense; every sentence earns its place. It is logically front-loaded with auth and primary purpose, then return fields, outcome semantics, filtering behavior, pagination, and the untrusted-fields warning. There is no filler or repetition of schema details.

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 16-parameter list tool with no output schema, the description covers auth, scope, sorting, trace-only runs, field vocabulary, outcome meanings, filter combination, pagination, response wrapper shape, and safety handling for raw output fields. Combined with fully described parameters, nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The schema already documents all 16 parameters with 100% coverage, so the baseline is 3. The description adds cross-parameter meaning: filters combine and narrow counts, the outcome enum's 'unfinished' value has special semantics, traced true vs omitted is clarified, and next_cursor pagination is explained. This adds value beyond the schema without needing to repeat each parameter.

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

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

The description opens with a specific verb and resource: 'List runs across every monitor in the project, newest started first.' It also distinguishes itself from get_run_history by noting it includes traced-only runs that get_run_history cannot list, and routes single-run needs to get_run. This fully resolves purpose and 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?

It states the required auth level ('read scope or higher'), explains when this tool is preferable to get_run_history, and points to get_run for one run's full timeline. It also documents pagination behavior and that filters combine, giving an agent clear guidance on how to use this tool correctly.

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?

The description is exceptionally transparent about behavioral consequences: the old key stops working immediately, the new key has a new ID, expiry handling is detailed, and it warns about the plaintext being returned only once. It also covers the 403 error case. This far exceeds the annotations (which only indicate destructiveHint), adding crucial context for safe usage.

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 lengthy but every sentence carries essential information, front-loaded with the admin requirement and the immediate impact on the old key. It is dense but not padded, and the structure flows logically from prerequisite to effects to exceptions.

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 destructive nature and absence of an output schema, the description covers everything needed: return behavior (plaintext once), error conditions, scope checks, and the impact on other systems. No critical operational detail 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 the single parameter, and the schema description already explains how to get the key ID via list_api_keys. The tool description adds no additional meaning about the parameter itself, which is acceptable given the high coverage. The baseline of 3 applies.

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

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

The description states the core purpose explicitly: 'Replace an API key's secret' with precise details about preserving name, scope, and monitor for tracing keys. It clearly distinguishes from siblings like revoke_api_key (cascade vs. no cascade) and create_api_key (new vs. regenerated).

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 a clear prerequisite (admin scope or higher) and explicitly contrasts with revoke_api_key, noting it does not cascade. While it doesn't mention create_api_key as an alternative for brand-new keys, the context implies regeneration is for existing keys. It gives practical guidance on 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?

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 already mark the tool as destructive and idempotent. The description adds crucial behavior beyond annotations: read-modify-write preservation of other templates, validation of allowed variables before saving, and the scope of the write effect. It also clearly states that passing an empty string resets to the built-in default, so an agent understands what gets changed and what does not.

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 most sentences add necessary operational detail, especially the variable list and its caveats. It is front-loaded with the auth requirement and core purpose before moving into detailed variable semantics. Some length is justified by the unusual behavior of the variables.

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 covers the critical context: auth scope, side effects, preservation of other templates, validation, and variable usage. It could have briefly mentioned the response/return after saving, but the absence is minor because the agent can still invoke the tool confidently.

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 all parameters at 100% coverage. The description adds significant value by exhaustively listing allowed template variables and clarifying tricky semantics for {failing_stage}, {body}, and {title}. The per-cause override ('cause') is barely expanded beyond the schema, but the descriptive text compensates for the most ambiguous parameter: the template variable set.

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 and resource: 'set or clear a single alert message template on a monitor.' It distinguishes itself from sibling get_alert_templates by describing a mutating operation while also clarifying the update model (read-modify-write, per-template preservation).

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 use guidance: requires a write-scope API key, explains how to clear/reset a template with an empty string, and describes the per-cause override semantics. It does not explicitly state when not to use it or directly reference alternatives, but the operation is well-scoped enough that an agent can determine when it applies.

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?

Annotations already indicate readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds significant behavioral context: it explains merge-patch semantics (omitted fields keep values), that tags/assertions/guards replace the full set (not merged), and that slug and ci_provider are immutable. It details side effects like the empty-string compatibility rule for ci_filters being a deliberate API rule. It also reveals cost/performance characteristics for guards (linear work per ping, measured times) and silent under-reporting with long windows. No contradiction with annotations; the description complements them thoroughly.

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 long, spanning hundreds of words per parameter, making it hard to parse for an agent looking for quick information. While the opening paragraph is dense and informative, the parameter descriptions are verbose and could be streamlined. It is not front-loaded; the most critical behavioral summaries (like replace-the-set semantics) are embedded deep within each parameter. However, every sentence adds real value, so it's not fluff, but the sheer length reduces conciseness.

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 complexity of the tool (29 parameters, many with intricate interactions), the description is remarkably complete. It covers prerequisites (API key scope), internal relationships (e.g., ci_branch requires ci_provider, schedule_kind restrictions on http monitors, outage of max_runtime_s with http), and multiple failure modes (e.g., 400 errors for specific constraints). It also explains the rationale behind certain defaults (empty string on ci_filters) and provides practical guidance (e.g., 'set expect_every_s on on_demand monitors'). With no output schema, it doesn't need to detail return values, but it does mention error responses. This is as thorough as one could expect for such a complex tool.

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

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

Schema description coverage is 100%, but the description adds substantial value beyond the schema. For example, it explains the full semantics of guards and assertions, including evaluation rules, edge cases, and constraints (e.g., assertions comparison rule, guard skipping on non-JSON bodies). It clarifies the interplay between parameters (e.g., max_runtime_s vs grace_s, step_timeout_s vs max_runtime_s). It also clarifies the empty-string behavior for ci_branch/ci_workflow, which is not obvious from the schema alone. The description elevates parameter understanding far beyond basic field definitions.

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 identifies the tool as updating an existing LastPing monitor's schedule/config by UUID, with a specific resource ('existing LastPing monitor') and operation ('update ... by UUID using merge-patch semantics'). It distinguishes the tool by explicitly mentioning its unique responsibilities: setting output assertions and metric guards, and its patch semantics which differ from create_monitor. It is not a tautology of the name; it explains the core behavior and its scope.

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

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

The description provides extensive guidance on when to use update_monitor versus alternatives. It explicitly states that ci_workflow and ci_branch filters should be set here because create_monitor's upsert silently discards them. It also highlights that assertions and guards are set via this tool, and mentions the need for a write-scope API key as a prerequisite. It warns against using it for immutable fields (slug, ci_provider) and explains when NOT to use it (rebinding CI requires delete/recreate). This is exemplary 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?

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.