Spike.sh MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description goes beyond that by spelling out the live-state mutation, that escalation stops, and that incidents are marked as being worked on. It still omits idempotency (what happens if an already-acknowledged incident is passed) and auth/permission 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?

Two compact clauses, front-loaded on the action and its consequence, with emphasis marking the state change. The trailing endpoint reference is marginally useful for debugging but is largely redundant with structured data.

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 two-parameter mutation with no output schema, the description supplies the essential effect an agent needs (state change, escalation stopped). Only minor gaps remain around failure/idempotency behavior, which is acceptable at this complexity.

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 required ids array and the optional teamId/x-team-id scoping are already fully documented in the schema. The description's {ids:[...]} restates the payload shape but adds no format, batching, or 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 (acknowledges) and resource (incidents), plus the concrete effect: stops escalation and marks them as being worked on. It is distinguishable from list/get siblings, but never contrasts with the closest sibling, spike_resolve_incidents, which an agent could easily confuse with 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 via the described effect (use it when you want escalation stopped and the incident marked as being worked on). There is no explicit when-to-use, when-not-to-use, or 'use spike_resolve_incidents instead to close it out' routing statement.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds genuinely new context: the operation is team-scoped and it discloses the returned payload keys ({escalation, integrations, isPinned, alertRules}) that no output schema provides. It stops short of stating auth scope details or the 404 behavior for a missing/foreign-team id.

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 lines, front-loaded with purpose before the endpoint hint, and no filler. The 'Spike: GET /escalations/{escalationId}' fragment is terse to the point of being notation-heavy, but it does add a concrete routing anchor.

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 2-param read tool with annotations covering safety and no output schema, the definition supplies the response shape, the scope, and the id source, which is close to everything an agent needs. It could add the failure mode for an unknown or out-of-team id, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both teamId and escalationId are already fully documented in the schema (including the x-team-id fallback and id provenance). The description adds only the path-level mention of escalationId, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one escalation policy by id') and names the sibling it is not — the singular 'one' clearly distinguishes it from spike_list_escalations. It even enumerates the returned shape, so an agent can tell it apart from the list 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?

Usage is only implied: you call it when you have an escalation id. The 'team-scoped' note gives context, and the schema's escalationId description points at spike_list_escalations as the source of ids, but the description itself states no when/when-not conditions or explicit alternative (e.g. list vs get).

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 real context beyond it: the payload composition (incident, duration, metadata, comments, repeatedIncidents) and the fact that the request is team-scoped. It does not cover error/not-found behavior or pagination of comments, which keeps it short of a 5.

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

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

A single front-loaded sentence carrying purpose, payload shape, and the underlying endpoint mapping, with zero filler. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates what comes back, and it flags team scoping for a multi-tenant API. It lacks any note on failure modes (e.g., invalid counterId or team mismatch), which is the only meaningful gap for a simple 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 description coverage is 100%, so both counterId and teamId (including the SPIKE_TEAM_ID default and spike_list_teams hint) are already fully documented in the schema. The description reinforces the counterId lookup but adds no syntax or constraint detail beyond it, 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 ('Get'), resource ('a single incident'), and lookup key ('by its counterId'), and names the returned payload shape. This clearly separates it from siblings like spike_list_incidents and spike_get_incident_activity_log.

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: fetch one incident's full record when you already have a counterId. There is no explicit when-to-use/when-not guidance and no routing to the activity-log sibling for event history, so an agent must infer the boundary.

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 safety is covered. The description adds real context beyond that: the return shape ({incident, activities:[...]}), the nature of the entries (acknowledged/resolved/commented with timestamps), and the team-scoping/auth requirement. It does not mention pagination or ordering guarantees beyond 'chronological'.

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

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

A single dense sentence that leads with the purpose and then enriches it with return shape and endpoint. Efficient, though the parenthetical REST-endpoint notation is somewhat cluttered for an agent that already has 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?

With no output schema, the description usefully sketches the return payload and entry semantics, plus the team scoping. For a two-param read tool this is close to complete, missing only ordering/pagination details.

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

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

Schema description coverage is 100%, so both params (teamId, counterId) are already documented in the schema. The description only echoes team-scoping and the counterId path variable, adding no syntax or format detail beyond the structured fields. 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 the chronological activity log for an incident') and further pins down what the log contains (who acknowledged/resolved/commented and when). This clearly distinguishes it from spike_get_incident, which returns the incident itself rather than its audit trail.

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 by the name and the '(team-scoped)' note, but the description never states when to reach for this versus spike_get_incident or the list/acknowledge/resolve siblings. No explicit alternatives or exclusions are given.

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

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

Annotations only declare readOnlyHint, and the description adds useful context beyond that: the exact response envelope keys and the fact that the call is team-scoped, plus the alternative teamId resolution noted in the schema. It doesn't mention permissions or error behavior, but the read-only safety profile is already covered by annotations.

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

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

Front-loaded with the action and resource, and every clause adds information (response shape, `from` semantics, team scope). The embedded JSON shape makes it dense but not wasteful.

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

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

With 100% schema coverage and no output schema, the description usefully compensates by outlining the return object and noting team scoping. An agent has enough to invoke it correctly; only explicit sibling routing 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 all three parameters are already documented in the schema (including the teamId default and the from timestamp format). The description's note that `from` sets the window start for rendered shifts adds only marginal nuance over the schema. 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 ("Get one on-call schedule by id") and even sketches the returned object shape. The "one ... by id" framing clearly separates it from the sibling spike_list_on_calls.

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 "by id" phrasing conveys the single-item retrieval context versus the list sibling, and it notes the request is team-scoped. However, it never explicitly names the alternative (spike_list_on_calls / spike_who_is_on_call_next) or states when to prefer this over them.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the bar is lower; the description adds the concrete return field list, the underlying endpoint mapping, and the team scoping constraint. It stops short of noting error behavior (e.g. what happens for an unknown counterId or cross-team id).

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

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

A single front-loaded sentence with the verb, key, and payload shape, followed by a compact endpoint parenthetical. No filler and nothing 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?

With no output schema, the description usefully enumerates the returned fields (service, org, openIncidentsCountForService, incidents, badgeURL) and notes team scoping. It is essentially complete for a simple single-resource read, minor gaps only around failure modes.

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

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

Schema description coverage is 100%, so both counterId and teamId are already fully documented in the schema (including the default-team fallback and the spike_list_teams hint). The description's mention of counterId adds nothing 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 one service') plus the identifying key (counterId), which cleanly separates it from the sibling spike_list_services. The included response field list further pins down the scope of the resource.

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 lookup-by-identifier usage and mentions the request is team-scoped, but it never explicitly tells the agent to call spike_list_services first to obtain a counterId — that guidance lives only in the schema. No when-not or alternative is stated in the description text.

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 declares the safety profile, so the description's main added value is the endpoint mapping and team scoping. It does not disclose return volume, pagination, ordering, or result caps, which are the remaining behavioral unknowns for a list endpoint with no output schema.

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

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

Two tightly packed sentences: the status definition is front-loaded where it matters most, and the endpoint annotation is compact. The 'Spike: GET /incidents/acknowledged (team-scoped)' clause slightly restates the already-stated team scope, but earns its place as implementation traceability.

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-optional-parameter read-only lister with full schema coverage and annotations carrying the safety profile, the description covers what the tool returns conceptually (acknowledged, unresolved incidents for one team). Only pagination/ordering behavior is unaddressed, a minor gap.

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

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

Schema description coverage is 100% and there is only one optional parameter, whose description already documents the 24-char hex format, the x-team-id header, the SPIKE_TEAM_ID default, and the spike_list_teams route. The description only echoes 'team-scoped' and adds no syntax or format 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 (List), a precisely defined resource (currently ACKNOWLEDGED incidents, glossed as 'being worked on, not yet resolved'), and a scope (team). The status gloss distinguishes it from the sibling status-filtered listers spike_list_incidents and spike_list_triggered_incidents without the agent needing to open 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?

The parenthetical definition of ACKNOWLEDGED gives clear selection context among the sibling list tools, and '(team-scoped)' tells the agent this returns one team's incidents. It stops short of explicitly naming alternatives (e.g. 'for all incidents use spike_list_incidents') or stating exclusions, so it is clear-but-not-routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by previewing the response shape (totalEscalations, escalations array, pagination) and citing the underlying endpoint, but says nothing about auth requirements or rate limits.

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

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

A tight two-sentence block with the purpose front-loaded and the response shape appended for reference. The endpoint citation adds modest but non-essential detail; nothing is bloated.

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

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

With no output schema present, the description usefully compensates by naming the returned fields and pagination. Combined with the fully documented single parameter, an agent has enough to invoke and interpret the call.

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

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

Schema description coverage is 100% and the single teamId parameter is thoroughly documented (24-char hex, x-team-id header, default fallback, how to list ids). The description adds no parameter detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (escalation policies) with a scope qualifier (a team's), which cleanly separates it from the singular spike_get_escalation sibling. It does not explicitly name the get counterpart, but the list/get distinction is self-evident.

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 notes the operation is 'team-scoped' but gives no explicit when-to-use, when-not-to-use, or alternative guidance. The routing hint about omitting teamId to use the default lives in the schema, not the description, so the description itself adds no usage direction.

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 goes beyond that by sketching the return shape (incidents array, totals, pagination), which is genuinely useful since there is no output schema. It stops short of noting auth requirements, rate limits, or whether results are default-ordered, so a 3 is appropriate.

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?

Single sentence, front-loaded with the core action, and the return-shape and endpoint details are appended compactly. No wasted prose, though the late 'Spike: GET /incidents' fragment is slightly awkward and could be trimmed without loss.

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

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

With no output schema, the description usefully fills the gap by naming the envelope keys and per-incident fields. For a 3-param, zero-required read tool whose parameters are fully documented in the schema, this is nearly complete; only the sibling-routing guidance is missing.

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

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

Schema description coverage is 100%, and the schema itself documents page, perPage, and teamId (including the 24-char hex format and the SPIKE_TEAM_ID fallback) thoroughly. The description adds nothing about parameters beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List incidents for a team') and the underlying endpoint (GET /incidents, team-scoped). It is distinguishable from most siblings, but it does not explicitly differentiate itself from the filtered variants (spike_list_acknowledged_incidents, spike_list_triggered_incidents) — the agent must infer that this is the unfiltered list. Clear, but not sibling-aware.

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 explicit when-to-use or when-not-to-use guidance. With three sibling list_* tools covering acknowledged and triggered subsets, the agent gets no help deciding which list tool to reach for. The team-scoping note lives 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavior beyond that: the response envelope shape ({oncalls:[...]}), the per-record fields (id, name, timezone, layers), and the team scoping of the endpoint — all useful for planning subsequent calls.

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

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

Compact and front-loaded — purpose first, then return shape, then chaining guidance, then endpoint. The inline '{oncalls:[...]}' is slightly cryptic but earns its place by conveying the response wrapper.

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

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

With no output schema, the description compensates by sketching the return shape and fields, and it names the id-consumer tools. For a single-optional-param read tool, this is close to complete; only deeper pagination/size behavior is 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 description coverage is 100% and the single teamId parameter is fully documented in the schema, so baseline is 3. The description only echoes team scoping ('team-scoped') without adding format or default-resolution detail beyond what the schema already 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?

States a specific verb and resource ('List a team's on-call schedules') and scopes it to a team. The mention of the underlying endpoint GET /on-calls and the id-based follow-ups clearly separates it from spike_get_on_call and spike_who_is_on_call_next.

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

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

Explicitly tells the agent what to do with the returned id ('Use the id with spike_get_on_call / spike_who_is_on_call_next'), which routes workflow correctly. It does not state when-not to use it or contrast with sibling list tools (e.g. spike_list_teams), so it stops short of a full 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true), and the description adds real behavioral context: the exact response envelope (totalServices, the per-service fields, pagination) and the underlying endpoint semantics (GET /services, team-scoped). It stops short of stating auth requirements or default page sizes.

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 purpose, then compresses the entire return shape into a single brace expression instead of prose — efficient. The trailing "Spike: GET /services (team-scoped)" is mildly redundant with the opening phrase.

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

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

With no output schema, the description usefully inline-documents the response payload and pagination, which is exactly what an agent needs to consume results. The single optional parameter is fully covered by the schema, so nothing critical is missing.

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

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

Schema coverage is 100% — the teamId description already explains the 24-char hex format, the x-team-id header, the SPIKE_TEAM_ID default when omitted, and the spike_list_teams lookup path. The description adds nothing about 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+resource ("List a team's services") and scopes it to the team, which distinguishes it from the singular spike_get_service and from spike_list_teams. It does not name a sibling explicitly, so it lands at 4 rather than 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?

The description offers no when-to-use guidance and no named alternative; the only routing hint (use spike_list_teams to find ids) lives in the parameter schema, not the description. An agent must infer from the tool name alone when to pick this over spike_get_service.

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 establish readOnlyHint=true, so the description's added value is the scoping rule (no team header required) and the fact that the `_id` field is the identifier other tools consume. That is real operational context an agent would otherwise have to infer; return-format detail is partly covered by the inline payload sketch.

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 compact sentences, front-loaded with the action, then the scoping caveat, then the downstream identifier semantics. The bracket payload sketch is slightly dense but short enough to earn its place as a return preview.

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

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

For a zero-parameter read with no output schema, the description covers what it returns, the shape of the response, and the required scoping context. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and no risk of ambiguity. The description still clarifies the ambient scoping behavior (org-wide, no x-team-id), which is the only parameter-like concern.

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 all teams in the Spike.sh organization') and is the only team-listing tool among siblings, so no differentiation is needed. It also sketches the returned object shape, which sharpens what 'list teams' actually yields.

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 frames the call as org-wide by saying it is 'NOT team-scoped (no x-team-id needed)', and explains the follow-on use of the `_id` values as `teamId` for every other tool — effectively positioning this as a bootstrap step. It stops short of naming a when-not-to-use case, but no sibling competes for this job.

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, but the description adds real value beyond annotations: it defines what 'TRIGGERED' means as a state (open, unacknowledged) and discloses the underlying API route and its team-scoping. It stops short of describing pagination, ordering, or result volume.

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 clauses with zero filler; the state definition (the routing-critical detail) is front-loaded and the API reference trails it as supporting context.

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

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

For a read-only, no-required-param list tool with no output schema, the definition is nearly sufficient: state semantics, team scoping, and the sibling reference for team ids are all present. Only result ordering/limits are unspecified, which is a minor gap.

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

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

Schema coverage is 100% and the sole teamId parameter is fully documented in the schema, including the default-fallback behavior and the spike_list_teams pointer. The description only echoes the team scoping already stated there, 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 (list) and resource (triggered incidents) plus the exact state filter: 'currently TRIGGERED (open, unacknowledged)'. This definition of the state set is what separates it from siblings like spike_list_acknowledged_incidents and spike_list_incidents 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 clear context via 'for a team — the active fire-fighting queue', which tells an agent this is the unacknowledged-work view. It does not explicitly name when to prefer a sibling instead (e.g. spike_list_acknowledged_incidents for the triaged queue), leaving that inference to the reader.

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 supply destructiveHint=true, so the mutating nature is already declared; the description reinforces this by emphasizing that live incident state CHANGES and incidents are marked done. It adds little beyond the annotation, though — no note on reversibility, required permissions, or partial-failure behavior when multiple ids are passed.

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

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

A single compact sentence with the mutation warning front-loaded and the API endpoint appended. The capitalization emphasis is a bit shouty and the endpoint detail is marginal, but nothing is padded.

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

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

For a destructive, multi-id mutation with no output schema, the description covers what happens (state change, marked done) but omits what an agent most needs: whether resolution is reversible, what happens on partial failure, and what the response contains.

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

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

Schema description coverage is 100%, so both ids and teamId are already well documented at the field level. The description only echoes the ids payload shape ({ids:[...]}) and adds nothing about teamId or batching semantics, 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 — resolves/closes incidents — plus the scope ('one or more'). It implicitly distinguishes itself from spike_acknowledge_incidents by framing the operation as closing/marking done, but it never names the sibling it must be chosen over.

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 explicit when-to-use guidance. Given siblings like spike_acknowledge_incidents and spike_set_incident_priority, the agent gets no rule for choosing resolve versus acknowledge versus re-prioritize; the reader must infer that 'closes/marks done' is terminal.

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

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

Annotations declare destructiveHint=true, so the safety bar is already lowered, yet the description still adds real value: it emphasizes that live incident state CHANGES and maps the call to the underlying POST /incidents/priority endpoint with its payload shape. It stays silent on batch semantics (partial failures, unknown ids) and permissions, 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?

Two tight sentences with the purpose and mutation warning front-loaded before the endpoint detail. The endpoint/payload clause is mildly redundant with the schema but useful for an API-backed integration, so it is not wasted space.

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 destructiveHint covering the safety profile and no output schema needed, the description is nearly complete for a tool of this complexity. The remaining gap is batch behavior — whether setting priority across multiple ids is atomic or can partially fail — which an agent calling this at scale would want to know.

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 ids, teamId and the priority enum are fully documented structurally. The description reinforces the p1..p5 range and the plural/multi-incident nature of ids but adds no syntax, ordering, or scoping detail beyond the schema — the baseline 3 for high coverage.

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

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

States a specific verb and resource — sets priority p1..p5 on one or more incidents — and explicitly flags that this mutates live incident state. That distinguishes it cleanly from read siblings (spike_get_incident, spike_list_incidents) and from other state changers like spike_acknowledge_incidents and spike_resolve_incidents.

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

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

The description makes clear this is a state-changing operation but never says when to choose it over the other mutation siblings (acknowledge, resolve) or what prerequisites exist. Usage is only implied by the verb and the warning, so it lands at minimum-viable 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 declare readOnlyHint=true, so safety is covered, but the description adds real value beyond that: the exact return shape ({nextShift:{userId, startTimeInUTC, endTimeInUTC}} or {}), the empty-result behavior, and the backing endpoint. It does not mention auth or pagination, but for a simple read that is minor.

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

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

A single dense sentence front-loads the purpose, then the return shape, then the endpoint. Nothing is wasted, though the raw endpoint interpolation adds little for an agent selecting the tool.

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

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

With no output schema, the description usefully supplies the return shape and the empty-result case, which an agent needs. Combined with the readOnly annotation and full schema coverage, the definition is nearly complete; only explicit sibling routing is 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 description coverage is 100%, so both parameters are already documented in-schema; the description only restates oncallId via the endpoint path and echoes the team-scoping. Baseline 3 is appropriate since 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+resource with a distinctive scope qualifier: 'Get the NEXT scheduled shift for an on-call schedule'. The 'NEXT' semantics cleanly separate it from sibling list/get tools like spike_list_on_calls and spike_get_on_call, so an agent can pick it 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?

Usage is implied by 'NEXT scheduled shift' versus listing/current-shift siblings, but there is no explicit when-to-use, when-not-to-use, or named alternative. The '(team-scoped)' hint gestures at context without stating prerequisites.

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