Better Stack MCP by usefulapi

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

Adds genuinely useful behavior beyond the annotations: the side effect of stopping escalation and the concrete failure mode that re-acknowledging returns HTTP 409. The 'Idempotent-ish' hedge is consistent with idempotentHint=true in state terms (409 errors but nothing else changes), so this is a nuance disclosure rather than a contradiction. It omits auth/permission requirements and what the response body contains.

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 its effect, then the edge case, in three dense sentences with no filler. The trailing raw endpoint (POST /api/v3/.../acknowledge) is the least valuable line for an agent invoking an MCP tool, though it does confirm the underlying 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 two-parameter mutation with no output schema, the description covers purpose, effect, and the one realistic error path, which is close to sufficient. Missing pieces are minor: no statement about what a success response returns and no mention of permission/scope requirements for acknowledged_by.

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

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

Schema description coverage is 100% and both parameters are documented inline, including that incident_id comes from betterstack_list_incidents and that acknowledged_by accepts an e-mail or custom identifier. The description adds nothing about the 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?

States a specific verb (acknowledge) and resource (an ongoing incident) plus the operational effect — signalling someone is looking into it and stopping further escalation. It does not name the nearby sibling betterstack_resolve_incident, so the acknowledge-vs-resolve distinction is left implicit rather than 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?

The description implies when to use it ('signalling that someone is looking into it') and hints at the alternative action by scoping to an 'ongoing' incident. But it never says explicitly when to prefer this over betterstack_resolve_incident, nor does it state prerequisites such as needing a valid, unacknowledged incident.

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?

readOnlyHint=true already covers the safety profile, and the description adds useful context beyond it: the exact set of fields returned and the underlying endpoint (GET /api/v3/incidents/{id}). It does not address behavior on an unknown id or error/pagination semantics, so it stops short of full 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?

One front-loaded sentence carrying the return-field detail, followed by a short endpoint reference. No filler and no repetition of the title.

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

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

For a single-parameter read tool with no output schema, the description compensates by naming the returned fields, which is exactly what an agent needs to decide whether this call answers its question. Only the missing not-found/error behavior keeps it from a 5.

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

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

Schema coverage is 100% and the schema itself documents where incident_id comes from (betterstack_list_incidents). The description only restates 'by id' and adds no format, validation, or lookup guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get a single incident by id') and enumerates what the response contains (cause, status, timeline timestamps, acknowledger/resolver, related monitor). 'Single incident by id' cleanly separates it from the sibling list_incidents without needing to name it.

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

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

Usage is only implied: an agent can infer this is the detail-fetch that follows list_incidents, and the schema's parameter description reinforces that by pointing at betterstack_list_incidents as the id source. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_monitor for the related monitor.

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

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

Annotations already declare readOnlyHint=true, so the description earns credit for going further: it enumerates what the response contains (current status, last_checked_at, SSL/HTTP settings, regions, alerting configuration) and cites the underlying endpoint. It stops short of noting error behavior for missing ids, but the read-only safety profile is fully covered.

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 tight sentences: the purpose and returned fields come first, then the API mapping. No filler, nothing to trim.

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

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

A single-param read tool with no output schema, and the description compensates by summarizing the response payload. What is missing is minor: behavior when the id does not exist or the monitor is not visible to the caller.

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 monitor_id comes from betterstack_list_monitors. The description only says 'by id' and adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single monitor by id') and enumerates the fields returned, so an agent knows exactly what it retrieves. It does not explicitly name betterstack_list_monitors as the alternative, but 'single monitor' implicitly separates it from the list 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?

Usage is implied ('single monitor by id' vs the list sibling), but there is no explicit statement of when to prefer this over betterstack_list_monitors or what happens if the id is unknown. The schema's parameter note points at the list tool as the id source, but that guidance is in the schema, not the description.

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?

readOnlyHint=true already covers the safety profile, and the description adds the underlying endpoint (GET /api/v2/heartbeats) plus the attributes returned (period, grace, status values up/down/paused/pending), which is genuinely useful context. It does not mention pagination behavior, result ordering, rate limits, or the global-token requirement implied by team_name.

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, zero filler. The resource and its domain meaning come first, followed by the response attributes and endpoint — everything is front-loaded and each clause 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?

For a read-only paginated list with a fully described schema and no output schema, the description covers what the tool returns and where it maps in the API. The only real gap is a note on pagination/result limits and the token scoping around team_name, which the agent must infer.

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

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

Schema description coverage is 100%, so page, per_page, and team_name are fully documented in the schema; baseline 3 applies. The description mentions period, grace, and status, but those are response fields rather than parameters, so it adds no parameter meaning 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 ('List heartbeats') and goes further by defining what a heartbeat is ('cron/background-job monitors that expect a periodic ping'), which disambiguates it from the monitor/incident siblings. It never names a sibling tool or contrasts scope with them, so it stops short of a 5.

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

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

Usage is implied rather than stated: the parenthetical definition tells the agent this is the tool for cron/background-job monitors, which subtly separates it from betterstack_list_monitors, but there is no explicit 'use this when…' or 'do not use for…' guidance and no mention of pagination strategy or token prerequisites.

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, so the safety profile is covered. The description adds useful behavior beyond that: it discloses the returned fields (cause, started_at, acknowledged_at, resolved_at) and the underlying endpoint, which matters since no output schema exists. It omits pagination defaults and rate-limit behavior.

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

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

Three tight sentences: identity/definition first, filter summary second, return shape and endpoint last. No filler or restated name/title, and nothing important 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 9-parameter read-only list tool with no output schema, the description covers what the resource is, how it can be filtered, and what fields come back. Minor gaps remain around pagination limits and total-result behavior, but the schema carries the parameter-level detail.

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

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

Schema description coverage is 100%, so every parameter is already documented in structured data. The description only summarizes three of the nine filters and doesn't add syntax or semantics for team_name, heartbeat_id, page, or per_page, so it stays at the baseline.

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

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

The description gives a specific verb and resource ('List incidents') and helpfully defines the domain term as 'alerts triggered by monitors/heartbeats', which disambiguates it from status pages or on-call entries. It does not explicitly contrast with the sibling betterstack_get_incident, so the single-vs-collection distinction is left implicit.

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

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

It names the available filter axes (date range, monitor, acknowledged/resolved state), which implies how the tool is used for narrowing results. However there is no explicit when-to-use guidance or exclusion pointing to get_incident for a single incident, or to acknowledge/resolve tools for state changes.

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?

readOnlyHint already declares the safe-read profile, so the bar is lower. The description usefully adds the set of returned fields and the underlying endpoint (GET /api/v2/monitors), which aids troubleshooting. It says nothing about default page size, total counts, or how large result sets behave, so behavioral context remains partial.

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 compact sentences: the first front-loads what is returned, the second gives the usage cue, with an endpoint note appended. Nothing is wasted and no information 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 read-only, zero-required-parameter list tool with a fully described schema and no output schema, the description covers what it returns and when to reach for it. Only pagination defaults and result-scale behavior are left unstated, which is minor here.

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

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

Schema coverage is 100%, so url, page, per_page, team_name and pronounceable_name are all documented in the schema; that sets the baseline at 3. The description adds no filter semantics of its own and does not mention that team_name only applies with a global token beyond what the schema already says.

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 concrete verb and resource ('List uptime monitors') and enumerates what the response contains: status states, check frequency, alert settings. It is clearly distinct from betterstack_get_monitor by being a listing call, though the description never names that sibling to sharpen the contrast.

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?

'Good first call to discover what is being monitored' gives a clear entry-point scenario an agent can act on. There are no explicit exclusions or named alternatives (e.g. use get_monitor for a single monitor's detail), so it stops short of 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds real content beyond the annotation by stating the response combines schedules with currently-on-call users and by citing the underlying endpoint (GET /api/v2/on-calls). It still says nothing about pagination behaviour, token/permission requirements or result ordering.

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 resource and payload front-loaded; nothing is buried. The trailing API endpoint reference is marginally useful for mapping to the REST API but is the least load-bearing sentence.

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

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

With no output schema, the description carries the burden of describing the return contents, and it does so at a high level (calendars plus on-call users). Pagination and token scoping live in the schema, and the read-only nature is covered by annotations, so the remaining gaps are minor for a zero-required-parameter list tool.

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

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

Schema description coverage is 100% — page, per_page and the global-token caveat on team_name are all documented in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies; it neither helps nor harms.

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 on-call calendars/schedules') plus the payload that matters ('the users currently on call for escalation'), which cleanly separates it from the incident, monitor, heartbeat and status-page siblings. The added 'who gets paged' gloss removes any ambiguity about what the listing contains.

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?

'Useful to see who gets paged' implies a use case but gives no when/when-not guidance, no mention of the team_name scoping option, and no alternative tool to pick instead. The agent must infer that this is the only on-call listing tool and that filtering requires a global token (which only appears in the schema).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds useful context by naming the underlying endpoint and the returned fields, but says nothing about pagination behavior, result caps, or whether the listing is filtered by token scope (that constraint lives only in the schema).

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

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

Two sentences, zero filler, and the substantive content (what the tool lists and what comes back) is front-loaded before the endpoint reference. Nothing could be cut 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, listing the returned fields (company name, subdomain, aggregate_state, published) is genuinely valuable so the agent knows what to expect. Only the pagination semantics and token-scope caveat are under-explained for a three-parameter list tool.

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

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

Schema coverage is 100%, so page, per_page, and team_name are already fully documented. The description adds nothing about them, which is the expected baseline when the schema does the heavy lifting, but it misses the chance to clarify the global-token condition on team_name.

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 ('List') and resource ('status pages'), and even names the fields returned. The resource type alone separates it cleanly from every sibling (incidents, monitors, heartbeats, on-call), though no sibling is named explicitly.

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

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

There is no guidance on when to choose this over other list tools, no mention of pagination strategy, and no explanation of when team_name filtering applies beyond what the schema already says. The reader must infer the use case entirely from the name.

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 provide readOnlyHint=false and idempotentHint=true, and the description adds real value: it names the underlying endpoint and discloses that re-resolving an already-resolved incident yields HTTP 409, which is precisely the operational nuance an agent needs for retry logic. It stops short of the higher bar because it says nothing about permission requirements or whether a resolution can be undone.

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, no filler, with the action and end-state front-loaded and the error/endpoint details trailing. Every clause 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?

For a two-required-parameter mutation with a 100%-covered schema and no output schema, the definition covers the essentials: what it does, the failure mode on repeat, and the endpoint. Minor gaps remain around auth/permission preconditions and reversibility, which matter for a destructive-state mutation.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including where the incident id comes from. The description adds no meaning 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+resource ("Resolve an ongoing incident") and adds the resulting state ("handled/closed"), which goes beyond the title. It does not, however, distinguish itself from the close sibling betterstack_acknowledge_incident, so an agent gets no help telling resolve apart from acknowledge.

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

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

Usage is implied rather than stated: the agent must infer that this is the terminal step after acknowledging. The 409 behavior is useful for repeat-call handling, and the incident_id parameter description points at betterstack_list_incidents for sourcing the id, but no explicit when-to-use/when-not guidance or alternative routing is given.

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