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

The description adds meaningful behavior beyond the annotations: it assigns the incident to the authenticated caller, returns the incident record, does not resolve the incident, and does not post a subscriber update. It does not mention permission requirements, reassignment behavior, or what happens on repeated acknowledgement, so it stops short of fully rich behavioral disclosure.

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

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

The description is three focused sentences with the core action front-loaded. Every sentence earns its place by covering purpose, usage boundaries, and alternatives 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?

For a simple mutation tool with annotations covering safety traits, the description is complete enough to call correctly: it explains the assignment action, the non-effects, the expected return, and how to obtain the required incident UUID. No output schema exists, but the description sufficiently indicates that an incident record is returned.

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 input schema already documents all three parameters, including the UUID format and the warning not to use an incident name, number, or slug. The description names list_incidents as the source of the incident UUID, which is useful, but it does not add syntax or format details beyond the schema and says nothing extra about the optional project and workspace 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 states a specific verb and resource: "Assign an existing incident to the authenticated caller and return the incident record." It also distinguishes this action from resolving the incident or posting a subscriber update, making it clearly different from sibling tools such as update_incident and post_incident_update.

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: "Use this when taking ownership of an investigation." It also states what the tool does not do and names the correct alternatives for communicating status (post_incident_update) and discovering the incident UUID (list_incidents).

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false): it discloses that creation assigns the caller as owner, that the optional body becomes the first investigating update, that no subscriber update emails are sent, and that monitorId limits scope to pages containing that monitor. Missing only minor traits such as reversibility or permission/error 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?

Front-loaded with purpose and return value, then alternative routing, then scoping and side effects — every sentence carries information and there is no filler. Slight redundancy with the schema on the visibility default keeps it from a 5.

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

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

For a 7-parameter, non-idempotent mutation with no output schema, the description supplies what the structured fields do not: the returned record/UUID, caller attribution, initial-update behavior, and the no-email side effect. Preconditions such as required permissions or invalid project IDs are left unstated.

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 baseline already covers all seven parameters; the description nevertheless adds semantic value by explaining what monitorId scoping actually means for incident visibility and that the body becomes the first investigating update. The visibility default is restated rather than extended, which keeps it below a 5.

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

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

Opens with a specific verb and resource ("Open a manual incident in the selected project") and states the return value (its record and UUID). It explicitly distinguishes manual incidents from automatic ones and names post_incident_update as the sibling for existing incidents, so an agent can route correctly without reading sibling schemas.

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

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

Gives an explicit when-to-use condition ("an event not already represented by an automatic incident") and an explicit alternative with its own condition ("use post_incident_update for an existing incident"). The monitorId sentence further narrows applicability by explaining the scoping effect of the parameter on which pages the incident appears.

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

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

Goes well beyond the annotations: explains that heartbeats wait for incoming pings while other types schedule outgoing checks, that auto-enabled alert channels are inherited, that failures can open incidents and notify channels, and that hosted plans can reject capacity/frequency/region choices while private network targets are refused by default. These are real side effects and failure modes an agent cannot infer from readOnlyHint=false / destructiveHint=false / idempotentHint=false.

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 purpose and return value, then behavior, then constraints — the ordering is sensible and there is no filler. A small amount of content (e.g. "heartbeats wait for pings; other types schedule outgoing checks") overlaps the type field's schema description, so it is dense rather than perfectly non-redundant.

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

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

For a 22-parameter creation tool with no output schema, the description covers the return payload, the inheritance of alert channels, the incident/notification side effects, and the main rejection scenarios. Nothing critical for calling it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-tool semantics (region and channel ids come from list_regions/list_channels) and restates two constraints that matter at call time: private network targets are refused by default and hosted plans may force larger intervals or reject regions. That is useful meaning beyond the schema's field-level prose.

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

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

States a specific verb and resource ("Create and start a monitor in the selected project") and immediately adds what comes back (record + UUID, plus the ping token for heartbeats). This clearly separates it from list_monitors, get_monitor and update_monitor without needing their schemas.

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

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

It explicitly routes the agent to list_regions and list_channels for the optional region/channel ids, and frames creation as creating-and-starting a new monitor. It stops short of stating when not to use it (e.g. update_monitor for an existing monitor, or checking for duplicates first), so it is clear context but not full when/when-not 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 a non-readonly, non-idempotent, non-destructive write, so the bar is lower; the description still adds the permission prerequisite, the fact that the new project is immediately usable via the project argument, and what is returned. It omits details like duplicate-name behavior or limits, keeping it just short of a 5.

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

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

Three short sentences, all front-loaded: action and return first, then sibling routing, then the permission requirement. No filler.

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

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

There is no output schema, but the description discloses that the record and id are returned, and it covers the permission prerequisite and post-creation usability. Complete for a simple 3-parameter create tool, with only minor gaps around edge-case behavior.

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

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

Schema coverage is 100%, so the schema already documents the name, project, and workspace parameters including their fallback behavior. The description's mention of 'the project argument' adds little beyond that, 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 ('Create a project inside the selected workspace') plus the return value (record and id), and explicitly distinguishes itself from create_workspace. An agent can identify this tool without opening the schema.

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

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

Gives an explicit use case ('separate monitors within an existing workspace') and names the alternative with its selecting condition ('use create_workspace for a separate team'). It also states the prerequisite of access to all projects in the workspace.

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 that a slug conflict returns an error, that omitted monitorIds creates an empty page, that the page becomes publicly readable without authentication, and that branding options depend on the hosted plan. It does not discuss deletion or reversibility, which is notable given there is no delete_status_page sibling.

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 front-loaded, moving from the primary action to constraints, then alternatives. Each sentence carries useful information 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?

For a 9-parameter creation tool with no output schema, the description covers public visibility, error behavior, monitor omission, and the update alternative. Minor gaps remain around lifecycle/reversibility, but the essential invocation context is present.

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

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

Schema coverage is 100%, so parameter meanings are already documented. The description adds only marginal detail, such as omitted monitorIds creating an empty page, while repeating the slug uniqueness already stated 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 opens with a specific verb and resource: 'Publish a status page at /status/<slug> and return its record and UUID.' It clearly distinguishes creation from sibling operations like update_status_page and list_status_pages.

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 names list_monitors for component selection and update_status_page for editing existing pages. It also states the slug-uniqueness requirement and error behavior, plus what happens when monitorIds is omitted.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely non-schema context: the auth/grant requirement and what is returned ('the new workspace record and id'). Minor confusion remains around 'including its first project' versus the project parameter's 'omit to use the default project', which reads ambiguously for a creation tool.

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

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

Three short sentences, with the core action front-loaded and the alternative, prerequisite, and return value following in priority order. No filler.

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

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

No output schema exists, and the description compensates by stating the return shape; the auth prerequisite is also covered. The only residual gap is the unclear relationship between 'including its first project' and the optional project/workspace parameters.

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

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

Schema description coverage is 100%, so all three parameters are already documented in structured form; the description adds no syntax or meaning beyond pointing at list_workspaces for ids. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource plus ownership scope: 'Create a workspace owned by the signed-in user, including its first project.' It explicitly contrasts with the nearest sibling, create_project, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative tool and the condition that selects it ('Use create_project instead to organize an existing workspace'), and adds a hard prerequisite ('Requires an OAuth grant for all workspaces; a workspace-scoped API key cannot create one'). Both when-to-use and when-not-to-use are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses that check history is destroyed, that the resource is unrecoverable through this tool, that the response is an empty success, and that deletion does not create an incident-resolution update. That is exactly the kind of irreversible-consequence and side-effect detail an agent needs before a destructive call.

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

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

Three short sentences with zero waste: the destructive action and its scope are front-loaded, the safer alternative follows, and prerequisites/recovery limits close it out. Every clause carries decision-relevant information.

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

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

There is no output schema, but the description explicitly states the return is an empty success response, so the agent knows not to expect a payload. Combined with the disclosed permissions, irreversibility, and cascade scope, nothing needed to invoke this destructive 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?

Schema coverage is 100%, and each parameter already carries a description (UUID from the list tool, project/workspace defaults), so the baseline of 3 applies. The description adds no parameter-level detail such as which identifier form to prefer or what happens if project and workspace conflict, so it neither compensates nor detracts.

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

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

States a specific verb and resource ('Permanently remove a monitor') plus the scope of destruction ('and its check history') and the return shape ('empty success response'). It is immediately distinguishable from siblings like pause_monitor, update_monitor, or get_monitor without opening any schema.

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

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

Explicitly names the alternative and the condition that selects it: 'Use pause_monitor instead when you may need it again.' It also states the access prerequisite (workspace owner/admin in addition to write scope), so an agent knows both when to pick this tool and whether it can succeed.

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 non-destructive, so safety is covered; the description adds real value beyond them by enumerating what the response contains (write-up, update timeline including internal updates, related monitor/checks, assignee, notification deliveries) and flagging that the data is private team information. It does not mention payload size, pagination, or behavior for missing/archived incidents, which keeps it from a 5.

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

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

Three front-loaded sentences, the return contents before the routing guidance, no filler. Minor redundancy between 'by its UUID from list_incidents' and 'Use list_incidents to discover ids', which is the only thing keeping it from a 5.

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

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

There is no output schema, so the description carries the return-value burden itself and does so concretely (write-up, timeline with internal updates, monitor/checks, assignee, deliveries). Combined with annotations covering the safety profile and a fully documented schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already spells out the UUID format and the 'not a name/incident number/slug' caveat, so the description's 'by its UUID from list_incidents' is largely reinforcement. It adds no extra semantics for the project/workspace parameters, 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?

Names a specific verb and resource ('Investigate one incident by its UUID') and immediately scopes it against siblings: list_incidents for discovery, update_incident/post_incident_update for mutation, and list_public_status_page_incidents for the public variant. An agent can pick this tool without opening any schema.

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

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

Explicit routing: use list_incidents to discover ids, update_incident to edit the write-up, post_incident_update to change status, and this tool only for private/team incidents rather than public status-page ones. Both the when-to-use and the when-not-to-use cases are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: what comes back (monitor plus history) and that secret HTTP headers are masked for callers lacking management access. It stops short of describing history depth, pagination or limits, which keeps it from a 5.

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

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

Three tight clauses: what it returns, when to use it versus siblings, and a redaction caveat. The purpose is front-loaded and every sentence carries information.

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

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

With no output schema, the description carries the return-value burden and does state it returns the monitor plus check history and uptime, plus the header-masking caveat. It omits how much history is returned or whether it is paginated/windowed, which is a minor but real gap for an investigative read 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% and the schema already documents all three parameters, including that id is a UUID not a name/slug and how project/workspace defaults apply. The description's 'by its UUID from list_monitors' reinforces the id source but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('one monitor's configuration, recent check history and uptime statistics') plus the identifier source ('UUID from list_monitors'). It explicitly contrasts itself with the sibling summary view and with run_check, so an agent can distinguish it 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 clear when-to-use ('investigate a specific monitor') and names two alternatives with their roles: list_monitors is the summary view, run_check performs a new check. Nothing is left to inference about tool selection.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds genuinely new context: no credentials required, only published data is exposed, and a missing page or an MCP-disabled page returns an error. The failure mode disclosure is exactly the kind of information annotations cannot express.

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

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

Three tightly packed sentences: purpose and return values first, then alternatives, then error behavior. No filler, no repetition of structured fields.

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

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

Although there is no output schema, the description names the returned fields and the failure cases, and it covers auth and sibling routing. An agent has everything needed to select and 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%; the slug parameter already documents its meaning, pattern, and position in the URL, so the description correctly does not repeat it. Baseline 3 applies since the description adds no supplementary 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?

"Read the published health summary for a status-page slug" gives a specific verb, resource, and scope, and the following sentence enumerates exactly what is returned (overall/component status, 90-day uptime, active public incidents). It is immediately distinguishable from get_incident/list_incidents and from the public incident-history siblings.

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

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

Explicitly routes the agent: use this for the summary, use list_public_status_page_incidents for incident history, and list_public_status_page_maintenance for downtime schedules. It also states the precondition (no credentials, published pages only), so there is no ambiguity about when this call 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 already declare this as read-only, idempotent and non-destructive. The description adds meaningful scope context beyond them: it returns channel records rather than performing a delivery test, and it does not manage channel creation or secrets. Pagination and ordering behavior are not mentioned, keeping it just short of a 5.

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

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

Four compact sentences with no filler. The primary purpose is front-loaded, followed by usage guidance and then the two important scope exclusions.

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 two-parameter list tool with no output schema, the description covers purpose, return nature ('channel records'), and what the tool does not do. Only minor operational details such as pagination or the exact returned fields are absent.

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

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

Schema coverage is 100%, so both the project and workspace parameters are already documented, including defaulting behavior. The description only refers generally to 'the selected project' and adds no syntax or filtering semantics beyond the schema.

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

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

States a specific verb and resource ('Discover alert-channel UUIDs and delivery types') and scopes it to the selected project. It is clearly distinguishable from siblings like list_monitors or create_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?

Explicitly says to use the returned ids with create_monitor/update_monitor.channelIds to route alerts, rules out this being a delivery test, and states that channel creation and secret configuration happen through the app or REST API. When-to-use, when-not, and alternative paths are all named.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds value beyond that by disclosing the return shape (incident summaries and UUIDs) and the open-first ordering, which annotations cannot express. It stops short of noting result limits or pagination.

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

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

Three short sentences, each doing distinct work: what it lists, what it returns, and where to go instead. Scoping and ordering are front-loaded 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 two-optional-parameter read tool with no output schema, the description covers purpose, return contents, and sibling routing adequately. Minor gap: no mention of pagination, result caps, or whether closed/resolved incidents are included.

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

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

Schema description coverage is 100%; both project and workspace carry their own descriptions including the omit-to-use-default behavior. The description only vaguely refers to 'the selected project' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus scope: incidents (automatic and manually opened) visible in the selected project. It also specifies result ordering (open incidents first), so an agent knows exactly what this returns relative to siblings like list_maintenance or get_incident.

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 routes the agent: use get_incident for timeline/failed checks/investigation details, and use post_incident_update (not update_incident) to change status or resolve. That is concrete when-to-use and when-not-to-use guidance naming three alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds context beyond them: the call is authenticated, its scope is the selected project, and it returns schedule plus monitor associations. It does not mention pagination or result limits, so not a full 5, but it meaningfully extends the annotation 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?

Three sentences, each with a distinct job: what it returns, which sibling to prefer, and what it cannot do. The scope and content are front-loaded with no filler.

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

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

No output schema exists, and the description compensates by naming what is returned (windows with schedule and monitor associations). With both params fully documented in the schema and auth/scope covered, only result-shape details like pagination or empty-result behavior are missing.

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

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

Schema coverage is 100% — both project and workspace are described in the schema, including the defaulting behavior and provenance (from list_workspaces). The description only restates the project scoping implicitly ('in the selected project') and adds no format or precedence details, so baseline 3 applies.

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

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

States a specific verb and resource ('Read maintenance windows') plus scope ('in the selected project') and content ('schedule and monitor associations'). It explicitly contrasts with the sibling list_public_status_page_maintenance, so an agent can pick between them without opening a schema.

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

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

Gives an explicit when-to-use ('this authenticated list for planning') and names the alternative with its distinguishing condition (list_public_status_page_maintenance only covers a published page slug). It also states out-of-scope operations and routes them elsewhere: 'does not schedule downtime; use the app or REST API to create or remove windows.'

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds useful non-annotation context: secret HTTP header values are masked unless the caller can manage the workspace, and it summarizes the returned fields. It could say more about result limits or pagination, but the key behavioral caveat is disclosed.

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 front-loaded: purpose first, then usage guidance, then the masking caveat. Every sentence contributes; there is no filler.

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

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

For a two-parameter, read-only list tool with full schema coverage and annotations carrying the safety profile, this is complete enough. The description also compensates for the lack of an output schema by naming the main returned fields.

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 project and workspace are already well documented in the schema. The description references the selected project but does not add new syntax, defaults, or constraints beyond what the schema provides.

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

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

Starts with a specific verb and resource: read monitor summaries for the selected project, and lists the fields returned (ids, status, uptime, latency). It clearly differentiates itself from get_monitor by directing that sibling to recent check history.

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

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

Explicitly states when to use it: to find a monitor before changing it or to scan for outages. It also names get_monitor as the alternative for check history, so the agent has a clear 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?

Adds real context beyond the annotations: no credentials required, internal updates are filtered out, and a missing or MCP-disabled page returns an error rather than an empty result. Those are meaningful contracts an annotation set cannot express. It stops short of saying how many incidents 'recent' covers, since there is no limit parameter — a small but real unknown for a list tool.

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

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

Three dense sentences: the capability first, the routing second, the constraints and error contract last. No restatement of the tool name, no filler, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description does say what comes back — incidents with their public updates, newest first — and it covers auth and error behavior. It does not describe the record shape or the size of the 'recent' window, so an agent can call it correctly but cannot fully predict 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 is 100% and the schema already defines slug as the last path segment of /status/<slug>. The description still adds meaning by qualifying the slug as belonging to a 'published' status page and by tying that same parameter to a concrete failure mode (missing page or MCP-disabled).

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 (read) and resource (public incidents plus their public updates) scoped to a status-page slug, with ordering (newest first). It explicitly distinguishes itself from get_public_status_page and get_incident, which is exactly what an agent needs to pick between the three.

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

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

Names the two competing siblings and the condition that selects each: get_public_status_page for current health, get_incident (authenticated) for internal detail. It also implies the exclusion criterion for itself — public-facing content only. The only gap is not mentioning list_public_status_page_maintenance, a minor omission in a large sibling set.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description still adds real context: no credentials are needed, public window records come back, and a missing page or one with MCP access disabled yields an error. It stops short of describing ordering or volume of returned windows, so it is strong rather than exhaustive.

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

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

Three sentences, each carrying distinct information: what it reads, when to use it versus the sibling, and what comes back including failure modes. The identifying scope (public, no credentials) is front-loaded with zero 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 single-parameter read tool with full annotation coverage and no output schema, the description supplies everything needed: auth posture, sibling routing, and error conditions. There is no gap an agent would need to guess at before calling it.

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

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

Schema coverage is 100% and the slug parameter already documents its format and the /status/<slug> address convention, so the schema does the heavy lifting. The description only restates that a published status-page slug is required, adding no new syntax or constraint 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 names a specific verb and resource (read scheduled and ongoing maintenance windows) and pins the scope precisely: public, per-status-page, unauthenticated. It explicitly distinguishes itself from list_maintenance, so an agent can separate the two without inspecting either schema.

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

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

It states the use case ('explain announced downtime') and names the alternative for the other case ('authenticated list_maintenance is the project-wide management view'), which is an explicit when-to-use/when-to-use-something-else split. Nothing is left to inference.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing domain constraints: 'auto' is always valid, explicit remote regions are HTTP/TCP only, and hosted plans may cap how many are used. It does not describe the exact response shape, though the first sentence implies ids plus a per-monitor maximum.

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

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

Four tight sentences, front-loaded with what the tool returns, then downstream usage, then the region-type constraints. No filler and nothing repeated from the schema or annotations.

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

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

Covers return content, downstream consumers, and the key eligibility rules, which is sufficient for a two-optional-param read tool with no output schema. Minor gap: it doesn't say whether scoping by project/workspace changes which regions are returned.

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

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

Schema coverage is 100% and both optional params (project, workspace) are fully documented there, so the description adds nothing about them. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource: 'Discover configured check locations and the maximum regions per monitor on this deployment.' No sibling tool deals with regions, so the scope is unambiguous even though no sibling is named.

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 routes the agent downstream ('Use the returned ids with create_monitor/update_monitor.regions or run_check.region') and adds a direct prohibition ('do not guess ids'), which is exactly the when-to-use guidance an agent needs before a mutation.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond them: the result is a private management list containing ids, and pages outside the selected project are excluded. It stops short of any ordering or pagination behavior, which keeps it from a 5.

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

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

Three short sentences, no repetition, and the core purpose is front-loaded before the sibling routing and the scope caveat. Every sentence carries information.

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

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

With no output schema, the description does the necessary work by saying the result is records plus UUIDs usable for update. For a two-optional-parameter, read-only list tool that is largely complete; only result ordering or pagination behavior is unaddressed.

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

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

Schema coverage is 100% and both parameters carry their own descriptions including the omit-for-default behavior. The description only alludes to the project scope ('outside the selected project'), adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Read status-page records and UUIDs') and pins the scope to the selected project. It also names the two sibling tools it could be confused with, so an agent can separate management reads from published reads and from updates.

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

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

Explicitly routes the agent: use the returned ids with update_status_page, and use get_public_status_page with a slug for the published component/outage summary. That is a concrete when-to-use / use-something-else statement rather than implied 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, non-destructive and closed-world, so safety is covered. The description adds scope semantics beyond that: results are limited to this connection's accessible workspaces, and omitted parameters fall back to connection defaults. It does not describe result shape or pagination, keeping it below a 5.

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

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

Three sentences, front-loaded with the purpose and the pre-condition, then the return content, then the parameter guidance. Nothing redundant and no filler.

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

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

For a two-parameter, zero-required, read-only discovery tool with rich annotations, the description covers purpose, scope, and default behavior adequately. With no output schema, it does briefly characterize the return ('accessible workspaces with their projects'), though it does not describe the shape of nested project data.

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

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

Schema coverage is 100%, so both parameters are already documented (including 'from list_workspaces' provenance and omit-to-default). The description reinforces the omission behavior ('omit them to use this connection's defaults'), adding light but real meaning on top of the schema, so it edges above the baseline 3.

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

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

The description opens with a specific verb and resource ('Discover the workspace and project ids') and states exactly what is returned ('accessible workspaces with their projects'). It also draws a clear boundary ('it does not list other users' workspaces'), which no sibling tool covers, so an agent can distinguish it from create_workspace or list_monitors.

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 ordering guidance ('before calling private tools') and explains both invocation modes: pass ids to select a scope, or omit them to use this connection's defaults. It does not name an alternative tool for any overlapping need, so it stops short of full when/when-not routing.

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

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

Beyond the annotations, it discloses what is preserved (configuration and history) and that the paused monitor is returned, which matches destructiveHint=false. It doesn't say what happens when the monitor is already paused, which matters given idempotentHint=false, nor anything about permissions or alert-silencing nuances.

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

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

Three sentences, front-loaded with the core action and effect, followed by alternative routing and one exclusion. No sentence is redundant and nothing is buried.

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

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

For a mutation tool with no output schema, the description still states the effect (checks and alerts stop), the preserved state, and the return value, and it routes to the two sibling alternatives. 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 description coverage is 100% and each parameter (id, project, workspace) already documents its source and omission behavior. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Stop scheduled checks and alerts for one monitor') plus the key scope qualifier that configuration and history are preserved. It also explicitly separates itself from update_monitor and resume_monitor, so an agent can pick it 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?

The description gives a full decision tree: use this for a pause-only change, update_monitor to combine pause with edits, schedule maintenance for downtime that should still run checks, and resume_monitor to restart. Both positive selection criteria and exclusions are stated.

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

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

Annotations declare non-readOnly, non-idempotent, non-destructive, but the description supplies the actual consequence: repeating a call creates another update and may send another email. It further discloses the subscriber email side effect for public updates, the team-only scope of internal ones, and the public requirement for resolved — none of which annotations encode.

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

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

Front-loads action, return value, sibling routing, and side effects in order of decision importance. Every sentence carries distinct information — visibility semantics, the resolved constraint, and the repeat-call warning — with no restatement of the schema.

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

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

For a 6-parameter mutation tool with no output schema, the description covers what it returns, the side effects (emails, duplicate updates), and the status/visibility coupling. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by tying visibility to the subscriber email side effect and by restating the resolved-requires-public rule as an operational constraint. It does not add much on id, project, or workspace, which the schema already documents.

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

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

States a specific verb and resource pair ('Append an incident timeline update and change its status') plus the return value ('returns the new update record'). It explicitly contrasts with the sibling update_incident ('write-up only'), so an agent can separate the two without opening either schema.

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

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

Gives explicit when-to-use ('communicate progress or resolve an incident') and a named alternative with the condition that selects it ('rather than update_incident (write-up only)'). It also tells the agent which visibility mode to pick and the constraint that resolved must be public.

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

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

The description adds meaningful side-effect context beyond the annotations: the next check becomes due immediately, may create incidents or send alerts, hosted active-monitor limits are checked again, and existing history is retained. It does not contradict the annotations, though it omits permission or tenant requirements.

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 action and usage distinction, then adds only high-value behavioral details. Every sentence carries useful selection or consequence information without 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 non-destructive mutation with full parameter documentation and relevant annotations, the description covers purpose, usage distinction, side effects, and retained history. It could add authentication or permission requirements, but otherwise it is complete 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 coverage is 100%, and the schema already documents id, project, and workspace fully. The description does not add parameter-level meaning beyond what the structured schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: restart checking a paused monitor. It also distinguishes this resume-only operation from update_monitor, which handles combined configuration edits, so the agent can separate it from siblings without consulting the schema.

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

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

It explicitly says to use this tool for a resume-only change and to use update_monitor for combined configuration edits. It also explains the immediate next-check consequence, which helps the agent decide when resuming 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?

Annotations only flag openWorldHint, non-idempotent, non-destructive, non-readOnly; the description supplies the substance: results go through incident/alert workflow and can notify channels, spot checks change no monitor history/status, hosted check credits apply, and probe/network errors are returned.

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 action and the two modes, dense but nearly every sentence carries a distinct fact. The final sentence bundles three unrelated caveats (heartbeats, credits, errors), which slightly muddies 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?

No output schema exists, and the description compensates by naming both return shapes ({ok:true} vs {ok:true,region,result}), the side effects, and the error behavior. An agent has enough to call it correctly and predict consequences.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds behavioral meaning to region: omission produces a recorded check, presence produces an unrecorded one with a different return shape. The id/project/workspace params get no extra treatment beyond the schema.

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

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

Opens with a specific verb+resource: 'Check a monitor immediately.' It also contrasts with get_monitor ('read existing checks'), so an agent can distinguish it from the sibling read tool without opening either schema.

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

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

Explicitly states when to omit region, when to provide it (after list_regions), and directs read-only use to get_monitor. It also excludes a case: 'Heartbeats have no outgoing spot check.'

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

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

Goes well beyond the annotations by disclosing partial-update semantics (omitted fields unchanged), clear-on-null behavior, and the privacy/publication lifecycle (private by default, visible on public status pages only after resolution, false hides again). The one wrinkle: clearing a write-up via null/blank is a data-losing action while destructiveHint is false, and the description does not reconcile that tension or mention permissions.

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

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

Four short sentences, front-loaded with the action and the sibling routing, then mutation semantics, then publication consequences. No filler and nothing an agent needs is buried.

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

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

No output schema exists, and the description still states the return ('the updated record'). With six parameters fully documented in the schema and the write/clear/publish contract covered, an agent has enough to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by stating the clear-vs-preserve contract for rootCause/postmortem and the 'private unless publishPostmortem is true' default, which the schema only partially conveys. It does not add format or content guidance for the Markdown body beyond the byte limit 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?

Specific verb + resource + scope: 'Edit an incident's root cause or Markdown postmortem and return the updated record.' It immediately excludes status/notification changes by pointing at post_incident_update, so the agent can separate it from siblings without opening schemas.

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

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

Explicitly names the alternative tool and the condition that selects it: 'Use post_incident_update instead to change status or notify subscribers.' That is a direct when-to-use-else rule, not an implication.

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 establish mutation, non-idempotency, and non-destructiveness. The description adds substantial behavioral detail beyond those annotations: omitted fields stay unchanged, type cannot change, lists/headers replace prior values, documented nulls clear optional settings, resuming sets status to pending, heartbeat changes recalculate deadlines, and new settings affect later checks.

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 structured and front-loaded. Every sentence contributes an actionable constraint, and the length is appropriate for a 23-parameter mutation tool.

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

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

Given the complex schema, mutation annotations, and absence of an output schema, the description supplies the missing operational context: patch semantics, side effects, prerequisite reading, sibling alternatives, and plan/target restrictions. It is complete enough 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?

Schema description coverage is 100%, so the schema already documents each parameter in detail. The description still adds valuable cross-parameter semantics: at least one changed field is required, omitted fields are preserved, type is immutable, list/header inputs replace existing values, and null clears supported optional settings.

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: 'Patch an existing monitor and return its updated record.' It clearly distinguishes this tool from related siblings such as get_monitor, pause_monitor, and 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?

It gives explicit workflow guidance: read get_monitor first, then send id and at least one changed field. It also names the alternatives, saying to prefer pause_monitor/resume_monitor for a pause-only change and use update_monitor for configuration changes or a combined edit.

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

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

Annotations already declare non-readOnly, idempotent and non-destructive, so the bar is lower; the description still adds real context the annotations cannot convey: PATCH semantics ('omitted fields stay unchanged'), that changes go live on the published page, that an empty externalUrl deletes the header link, and that hosted branding restrictions (plan limits) apply to hideBranding. A gap: the replace/clear behavior of monitorIds is a targeted destructive effect not reconciled with destructiveHint=false.

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

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

Front-loads the verb, resource and ID provenance, then the routing hint, then per-field edge cases. Semicolon-joined clauses stay dense without padding; every sentence carries information an agent would otherwise have to infer.

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

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

Covers identifier provenance, write scope, live-publish consequences, field-omission semantics, the destructive [] case, plan restrictions, and even the return shape ({ok:true}) despite there being no output schema. With all 9 parameters fully documented in the schema, nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's monitorIds replace/clear rule and empty-externalUrl rule duplicate what the schema already says verbatim; its only genuine addition is that unspecified fields are left untouched, which frames the whole parameter set as a patch rather than a full replace.

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 (patch), a specific resource (an existing status page), and even the identifier source ('by its UUID from list_status_pages'). It explicitly distinguishes itself from the read-side sibling get_public_status_page, so an agent can select it without consulting the schema.

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

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

Explicitly routes the agent: use this to edit presentation/components, use get_public_status_page to read the result. The write-vs-read split is clear. It does not address the create/delete boundary (create_status_page, delete paths), so it stops short of full alternative coverage.

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