Squadcast MCP by usefulapi

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

Annotations only flag destructiveHint=true, so the description usefully adds that acknowledgment halts escalation/paging and that this targets the LIVE account. It does not mention permissions, idempotency, or error behavior on already-acknowledged incidents, but it goes meaningfully beyond the annotation.

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 single sentence that leads with the verb and the state change, followed by a compact API reference. No filler, though the raw endpoint string adds little for an agent that already has the tool name.

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

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

For a one-parameter mutation with no output schema, the core call path is covered. Missing pieces are the preconditions (must the incident be triggered? unacknowledged?) and what an acknowledgment returns or how failures surface, which matter for a mutating action.

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% for the single incidentId parameter, so the schema already carries the semantics. The description merely echoes it in the REST path template ({incidentID}) without adding format, source, or validation 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?

States a specific verb (acknowledge) and resource (triggered incident) and adds the concrete effect – it stops escalation/paging. It scopes the action to the LIVE account, but does not explicitly contrast with the sibling squadcast_resolve_incident, so the agent must infer the distinction.

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 parenthetical ('stops escalation/paging'), which tells the agent this is for silencing alerts while handling an incident. However, it never states when to acknowledge versus resolve, nor any precondition such as the incident being in a triggered state.

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, so the agent knows this mutates server state. The description adds the 'LIVE incident' scoping constraint, but says nothing about required permissions, whether the note is editable/deletable afterwards, or error behavior on non-live incidents. Adds some value but not rich behavior 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?

Two tight sentences with zero filler; the core action and its scope constraint are front-loaded, followed by the endpoint reference.

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 add-note mutation with full parameter coverage and no output schema, the description is largely sufficient. Remaining gaps are minor: it does not state the error path for non-live incidents or confirm the note is returned, but nothing critical to calling it 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 all three parameters (message, incidentId, attachments) are already documented in the schema. The description only restates the optional attachment URLs, adding no format or syntax detail 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?

The description gives a specific verb+resource (add a war-room note to an incident) plus the underlying endpoint (POST /v3/incidents/{IncidentId}/warroom). It contrasts naturally with the sibling list_incident_notes, so an agent can distinguish write-note from read-notes 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?

The word 'LIVE' implies notes are only addable to currently active incidents, which is a useful implicit usage constraint. However, no explicit when-to-use/when-not or alternative sibling is named, and it does not say what happens if the incident is resolved.

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 establishes the safe-read profile, and the description adds only the raw API route. It says nothing about error behavior for a missing/invalid id, whether the full incident object or a summary is returned, or any auth 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 very short sentences with the operation stated first. The trailing REST endpoint reference is mild filler for an agent but does not bloat the definition.

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 trivial single-resource read with annotations covering safety and a fully documented parameter, this is minimally sufficient. With no output schema, however, the description leaves the agent with no idea 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% for the single incidentId parameter, so the schema already carries the meaning. The description adds no format, source, or example beyond 'by its id', making the baseline 3 the right call.

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

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

The description states a specific verb and resource ('Get a single incident by its id'), which cleanly separates it from squadcast_list_incidents and gets closest to the sibling it most resembles. It does not name any sibling explicitly, so it stays 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer from the name alone that this is the lookup path when an incident id is already known.

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 safe-read profile is covered. The description usefully enumerates the event kinds returned (state changes, notifications, actions) and the REST path, but adds nothing about ordering, volume, pagination, or retention of the timeline.

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, front-loaded with the purpose and contents, with the endpoint reference trailing as supporting detail. No filler or redundancy.

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

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

For a single-parameter read tool with annotations covering safety and no output schema to describe, the definition is nearly sufficient. It conveys what the timeline contains, though a note on result ordering or limits would make it fully complete.

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 single incidentId parameter is fully documented in the schema. The description restates the 'single incident' scope and shows {incidentID} in the endpoint template, but contributes no additional semantics (e.g., ID format) 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 ('Get the timeline of events for a single incident') and clarifies content with '(state changes, notifications, actions)', plus the underlying endpoint. This clearly separates it from squadcast_get_incident and squadcast_list_incident_notes, though it does not name a sibling 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?

The scope of use is implied by the resource (fetch the event timeline for one known incident), but there is no explicit when-to-use guidance or conditions selecting it over alternatives like squadcast_get_incident or squadcast_list_incident_notes.

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. The description adds only the REST endpoint mapping (GET /v3/services/{serviceID}), which is not behavioral context — it says nothing about permission requirements or what happens when the id is unknown.

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

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

Two short sentences, front-loaded with the purpose. The endpoint mapping sentence is mildly redundant with the tool name but costs almost nothing.

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 one-parameter read tool with annotations covering safety, the description is minimally sufficient. With no output schema present, the agent gets no sense of the returned service shape, which is a modest 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% with a single documented serviceId parameter, so the baseline is 3. The description restates 'by its id' without adding format, source, or validation 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 ('Get a single service by its id'), which implicitly separates it from the sibling squadcast_list_services. It does not name that sibling or any other alternative explicitly, so it is clear but not fully differentiated.

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 statement of when to use this tool versus squadcast_list_services, nor any prerequisite or context for choosing it. The 'single by its id' phrasing hints at retrieval of one record, but the agent must infer the routing decision entirely.

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 readOnlyHint=true annotation already establishes this is a safe read, lowering the bar. The description adds the underlying endpoint (GET /v3/teams/{teamId}), which corroborates a single-resource fetch, but discloses nothing further about error behavior or return shape.

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

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

Two short sentences with the core action front-loaded and no filler. The endpoint citation is marginally redundant for an agent but does aid API mapping, so it still earns its place.

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

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

For a single-resource read tool with an annotations-declared safety profile, one fully documented parameter, and no output schema, the description covers what an agent needs. Only the lack of routing guidance against list_teams keeps it from being complete.

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 parameter, so the schema fully documents teamId. The phrase 'by its id' merely restates the parameter and adds no format or source-of-id 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 ('Get a single team by its id'), and the word 'single' implicitly contrasts with squadcast_list_teams. It is clear, but it never names the sibling list tool to sharpen the distinction.

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 infers it should use this when it already has a team id, but no explicit when-to-use or when-not-to-use guidance is given, and no alternative (e.g. squadcast_list_teams for discovery) is 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?

The readOnlyHint annotation already declares this a safe read, so the bar is lower. The description contributes the upstream endpoint (GET /v3/users/{userID}), which aids traceability, but says nothing about behavior on an unknown id (error vs empty) or the shape of the result.

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

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

Two short sentences, front-loaded with the operation, zero filler. The endpoint reference is compact and appended rather than 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 one-parameter read tool with annotations covering safety and no output schema, this is nearly sufficient. The only gap is unspecified error behavior for a nonexistent id, which is a minor omission rather than a blocker.

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

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

Schema description coverage is 100% with a single required userId parameter, so the schema fully documents the input. The description's 'by their id' adds no format or syntax detail 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 ('Get a single user by their id'), and the singular scope distinguishes it from the sibling squadcast_list_users without naming it. It could have explicitly named the list sibling to make routing unambiguous, but the purpose itself is clear.

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 phrase 'by their id' weakly implies the agent must already hold a user id, but there is no explicit when-to-use guidance, no prerequisites, and no mention of the sibling squadcast_list_users as the alternative for discovery. This is essentially no 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 the GET /v3/escalation-policies endpoint and the team-scoping requirement, but says nothing about pagination behavior or result limits, which would be the useful extras here.

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 clauses, zero waste, with the hard requirement front-loaded immediately after the purpose statement. 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?

For a three-parameter read-only list tool with full schema coverage and a readOnlyHint, the description covers purpose, the mandatory parameter, and its source. Pagination semantics are left entirely to the schema, which is acceptable but the only remaining 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%, so all three parameters are already documented. The description emphasizes that owner_id is a TEAM id (guarding against a user-id mix-up) and that it is required, which is a modest restatement of the schema rather than new information.

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+resource ("List escalation policies") and states the scoping constraint ("for a team"), with the underlying endpoint for grounding. It is clearly distinct from write siblings like squadcast_resolve_incident, though it does not explicitly contrast with the closest read siblings such as squadcast_list_schedules.

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

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

It states a hard prerequisite (owner_id is REQUIRED) and routes the agent to squadcast_list_teams to obtain it, which is genuine when-to-use guidance. It stops short of any when-not-to-use or exclusion criteria.

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 the underlying REST mapping (GET /v3/incidents/{IncidentId}/warroom) but says nothing about pagination, auth requirements, or how many notes are returned, so it adds modest value.

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

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

Two short sentences, front-loaded with the action and resource. The endpoint reference is compact and plausibly useful to a technical agent, though it is the least essential 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?

For a simple one-parameter read tool with full schema coverage, the description is close to sufficient. However, with no output schema, it never indicates the shape or volume of returned notes or pagination behavior, which leaves 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?

With one parameter at 100% schema description coverage, the schema already documents incidentId fully. The description adds no format, syntax, or ID-source guidance beyond what the schema 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 (List) and resource (war-room notes on a single incident), which is a clear, unambiguous action. It does not explicitly name the contrasting sibling squadcast_add_incident_note, so it falls just 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?

The description gives no when-to-use guidance, prerequisites, or alternatives. The phrase 'on a single incident' implies scope but does not tell the agent when to reach for this versus get_incident_events or get_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 tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds the required-parameter constraint and ISO8601 format expectation, but omits result-volume behavior, pagination, or limits despite the endpoint being an export. It mostly restates what the schema and annotations already convey.

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

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

Dense and front-loaded: filters and sort come first, then the hard constraints and the sibling lookup hint. No filler sentences, though the trailing 'Squadcast: GET /v3/incidents/export' is of marginal value to an agent.

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

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

The description covers filters, sorting and required inputs adequately for a 13-parameter tool, and annotations carry the safety profile. The notable gap is any indication of pagination or result-size behavior for a list/export call, which is exactly the info a schema cannot convey.

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 including enums (sortBy, isStarred, sloAffecting) is already documented in the schema. The description adds only the required/ISO8601 framing, 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+resource ('Search/list incidents over a time window') and enumerates the filter dimensions and sorting it supports. This clearly separates it from siblings like squadcast_get_incident (single record) and squadcast_list_incident_notes.

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 specifies that start_time, end_time and owner_id are REQUIRED and routes the agent to squadcast_list_teams to obtain the team id, which is genuine operational guidance. However, it never contrasts this tool with alternatives (e.g., use squadcast_get_incident when you already have an id), so the when-to-use guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that myOnCall reflects the current moment ('currently on call') and cites the underlying endpoint, but says nothing about pagination behavior, result volume, or 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, no filler, the required parameter and its procurement path are front-loaded ahead of the optional filter. Nothing could be removed 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?

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, required input, and the one non-obvious filter. Only pagination/return-shape framing is absent, which is acceptable given the schema carries the cursor parameter.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by emphasizing teamId's required status and its source, and by framing myOnCall as the current on-call view rather than a generic boolean filter.

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 on-call schedules for a team') with the scope constraint (per-team) front and center. It also names the sibling squadcast_list_teams as the means to obtain the required id, so the agent can distinguish this from other list tools.

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

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

Gives clear entry context: teamId is REQUIRED and where to get it (squadcast_list_teams), plus an explicit conditional use case for myOnCall ('the who's on call lens'). It does not state exclusions, but no sibling tool overlaps this resource, so the omission is minor.

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 safe-read profile is covered. The description adds the required-parameter constraint and the underlying GET /v3/services mapping, but says nothing about pagination, result volume, or ordering for a list endpoint.

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, zero filler, with the required-parameter constraint front-loaded ahead of the API mapping. Every sentence earns its place.

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

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

For a read-only filtered-list tool whose safety profile is already in annotations and with a fully documented schema, the description covers the essential prerequisite and tool routing. Only result size/pagination behavior is unaddressed, 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%, so the schema already documents all three parameters. The description usefully emphasizes that owner_id must be a TEAM id (the schema phrase 'Team id that owns the services' is similar), but adds no syntax or format detail beyond that. Baseline 3 applies.

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

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

The description gives a specific verb+resource ('List services for a team'), which clearly separates it from the singular sibling squadcast_get_service. It is not tautological, though it never names the sibling it contrasts with 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?

It states the precondition clearly: owner_id is REQUIRED and tells the agent to call squadcast_list_teams to obtain it, which is genuine cross-tool routing. It does not, however, say when to prefer this over squadcast_get_service for a single 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 declare readOnlyHint=true, so safety is covered; the description adds the concrete HTTP method/path and, more valuably, warns that owner_id is a TEAM id rather than a squad id — the most likely source of a failed call. It does not discuss pagination or result size, so it is not fully rich.

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, front-loaded with purpose, then the required-parameter warning, then the API mapping. 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 one-parameter read-only list tool with no output schema, the description covers purpose, the required input, how to obtain it, and the underlying API call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning on top: it relabels ownerId as a TEAM id and names the sibling tool that resolves it, guarding against passing a squad identifier. It adds no format or syntax detail beyond that.

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

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

States a specific verb and resource with its scope: 'List squads for a team.' The scope qualifier ('for a team') plus the endpoint mapping (GET /v4/squads) makes it unambiguous and distinct from the many other list_* 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?

Gives an explicit prerequisite (owner_id is REQUIRED) and routes the agent to squadcast_list_teams to obtain it, which is real workflow guidance beyond what the schema supplies. It stops short of stating when not to use the tool or what it returns, so it is clear context rather than 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 readOnlyHint=true, so the safety profile is covered. The description adds useful context that the output supplies an id consumed elsewhere, but says nothing about pagination, result size, or ordering for a list endpoint.

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

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

Two short sentences, front-loaded with what it does, followed by the actionable payoff and the raw endpoint. 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 no-parameter read tool with no output schema, the description covers purpose, the key returned value, and the endpoint. Only pagination/ordering behavior is unstated, 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?

The tool takes zero parameters, which is the baseline 4 case. There is nothing to disambiguate, and the description's note about the id value is about output, not input.

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 organization') and adds the endpoint (GET /v3/teams), so intent is unambiguous. It does not explicitly contrast with the sibling squadcast_get_team, but 'all teams' versus a single-team fetch 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?

Gives a concrete reason to call it: the returned team id is the `owner_id`/`teamID` that several other tools require, which tells the agent when this lookup is a prerequisite. It stops short of naming specific alternative tools or a when-not condition.

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 only the raw endpoint path (GET /v3/users), which is not behavioral insight; it says nothing about pagination, result limits, or auth scope for a list operation.

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

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

Two short sentences, front-loaded with the scope and followed by a compact endpoint reference. No wasted text.

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 no-parameter list tool the definition is minimally adequate, but with no output schema and no mention of pagination or response size, an agent lacks context on how much data comes back from an org-wide listing.

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 the baseline is 4 per the rubric. There is nothing for the description to clarify beyond confirming the call is unfiltered.

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 all users in the organization') and the 'all' scope implicitly separates it from the sibling get_user. It is clear without being explicit about sibling differentiation.

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

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

No guidance on when to list all users versus fetching a single user via squadcast_get_user, and no mention of filtering, pagination, or prerequisites. Usage must be inferred purely from the verb.

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 destructiveHint=true, so the description carries most of the behavioral burden. It adds genuinely useful context – that this targets the LIVE account and that a resolution message is recorded – but says nothing about incident state transitions, reversibility, permissions, or rate limits for a mutating operation against production data.

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

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

Two short sentences, zero filler, with the action and its scope stated before the raw API endpoint. Nothing is buried and nothing needs trimming or reordering.

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

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

With no output schema and only a destructiveHint annotation, the definition is minimally viable: an agent knows what to call and with which two parameters, but not what a successful resolution returns, whether it is reversible, or how failures surface. Adequate, with clearly visible gaps for a live-account 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% with both parameters documented, so the baseline is 3. The phrase "recording a resolution message" clarifies the intent of the message parameter slightly, but adds no format, length, or constraint detail 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 ("Resolve an incident") plus two meaningful qualifiers: it acts on the LIVE account and records a resolution message. That is enough to separate it from read-only siblings like get_incident and list_incidents, though it never explicitly contrasts itself with the closest sibling, acknowledge_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?

The description gives no when-to-use guidance, no prerequisites, and no routing away from alternatives. An agent must infer on its own why to resolve rather than acknowledge or add a note to the same incident.

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