SIGNL4 MCP by usefulapi

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

Annotations already declare readOnly=false, destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description genuinely adds behavioral context: the acknowledgement is attributed to a specific user in history, and it halts escalation to further tiers. It does not explain what 'destructive' means here or note auth requirements, so it is not exhaustive.

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

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

Two sentences, zero waste. The 'WRITE:' marker front-loads the mutation class, followed by effect and endpoint in descending order of usefulness.

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 write with no output schema and full annotation coverage, the description supplies effect, attribution, and endpoint. The only minor gap is the absence of any statement about the response or what happens on an already-acknowledged alert.

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 (alert_id, user_id, comment) are already documented with sources for their values. The description adds no extra syntax or format detail beyond the schema's own fields, so the baseline 3 applies.

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

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

States a specific verb (acknowledge) and resource (an alert/signl) plus the acting user, and immediately names the operational effect: 'Stops escalation to further tiers for that alert.' The scope is distinguishable from close_alert and annotate_alert, and the backing endpoint is given, so an agent can tell what this does without opening the schema.

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

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

Usage is implied by the semantics ('acknowledge' vs 'close'), but the description never states when to pick this over signl4_close_alert or signl4_annotate_alert, nor any prerequisite such as an active/open alert. The context is inferable but not spelled out.

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 write/safety profile (readOnlyHint=false, idempotentHint=false), but the description adds real context they don't carry: the note lands on the alert timeline, it is visible to the team, and it does not page anyone. It stops short of stating whether notes can be edited/deleted or what permissions are needed, which is why it isn't 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 short sentences plus the route, front-loaded with the WRITE marker so the mutation nature is the first thing read. No filler sentences.

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

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

No output schema exists, and the description sensibly covers what happens to the note rather than a return payload. Combined with annotations, an agent has enough to call this correctly; only permission requirements and reversibility are left unstated.

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

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

Schema description coverage is 100%, so alert_id, user_id and text are already fully documented, including where to obtain the ids. The description only echoes the path parameter naming (signlId) and adds no format or constraint detail beyond the schema — the baseline 3.

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

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

Opens with 'WRITE: add a text note to an alert's timeline' — a specific verb, resource and effect. It is trivially separable from read-side siblings like signl4_get_alert_timeline, and the POST path reinforces the action.

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 does not page anyone by itself' implicitly contrasts this with paging siblings such as signl4_raise_alert, and 'on behalf of a SIGNL4 user' hints at attribution requirements. However, there is no explicit statement of when to choose annotate over raise_alert or ack, nor any exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and the write/read profile, so the safety bar is low. The description adds genuinely useful context beyond them: the alert is removed from the open list and notifications cease, which is the effect an agent needs to reason about. It stops short of covering auth requirements or whether closure is reversible.

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 led by 'WRITE:' plus the endpoint path; every clause earns its place and 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 three-parameter mutation tool with no output schema and full schema descriptions, the definition covers purpose, effect and endpoint. Missing only edge details such as failure modes or permission requirements, which is a minor gap given annotation coverage.

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

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

Schema description coverage is 100% and each parameter already documents itself, including cross-references to signl4_list_users and signl4_list_alerts. The description adds nothing beyond the schema for alert_id, user_id or comment, 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 (close/resolve) and resource (alert), plus the concrete effect on the alert's lifecycle: it leaves the open list. This distinguishes it from signl4_acknowledge_alert, which implies suppression without removal, so an agent can route between the two.

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 effect ('stops all further notifications', 'leaves the open list') implies when closure is appropriate, but the description never explicitly contrasts it with signl4_acknowledge_alert or the other alert-mutating siblings, nor states prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by cataloguing the returned surface (history, per-user delivery, escalations) and citing the underlying GET endpoint, but says nothing about authorization requirements or rate limits. Given the annotation coverage, 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?

A single sentence that front-loads what is returned and tacks the endpoint onto the end; no filler, no restatement of the title. Every clause adds either content or routing information.

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

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

There is no output schema, so the description must carry the return-shape burden, and it does so by enumerating the fields and nested structures (history, attachments, escalations with per-user delivery). Combined with 100% schema coverage on the lone input, an agent has what it needs; only cross-sibling disambiguation is missing.

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

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

Schema coverage is 100% and the single alert_id parameter is fully documented in the schema, including where to obtain it (signl4_list_alerts or the id from signl4_raise_alert). The description adds no parameter-level information, 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 ('Full detail of one alert') and enumerates the fields returned (title, text, severity, category, status, history, parameters, attachments, escalations), which differentiates it from the narrower siblings signl4_get_alert_timeline and signl4_get_alert_report. It stops short of explicitly naming those siblings, so an agent must infer the boundary.

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

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

Usage is implied rather than stated: needing complete detail for a single alert is the obvious trigger, and the field enumeration suggests when this is preferable to the timeline/report variants. However, no when-not, no prerequisites, and no alternative is named despite three closely related alert-detail siblings in the list.

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, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real value by disclosing partial-failure behavior ('Teams that cannot be read are reported under errors') and the backing endpoint GET /v3/signls/report, which the agent cannot derive from structured fields.

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

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

Two sentences, front-loaded with the returned metrics and ending with the endpoint, with essentially no filler. Slightly dense but every clause carries information.

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

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

With no output schema, the description does the work of sketching the return shape (per-team, per-category counts plus an errors bucket), which is what an agent needs to interpret results. It is thin on the exact time periods and pagination/size limits, but otherwise complete for a read-only report tool.

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

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

Schema coverage is 100%, so both parameters are already documented, including the hint to fetch team ids from signl4_list_teams. The description only restates the user-scoping option and adds no syntax or default detail beyond the schema, so the baseline 3 applies.

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

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

The description names a concrete resource (alert volume and response statistics) and enumerates exactly what is measured: acknowledged, closed and unhandled counts, overall and per category. That scoping distinguishes it cleanly from sibling reporting tools such as signl4_get_duty_summary and signl4_get_alert_timeline.

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 when-to-use or when-not-to-use guidance and no mention of the sibling report tools an agent might confuse this with. The 'optionally for one user' clause describes a parameter, not a usage condition, so the agent must infer the trigger context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the timeline event categories, but says nothing about ordering guarantees beyond 'ordered', pagination, or result size 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?

Two compact sentences, front-loading the return content before the endpoint path. Nothing is wasted, though the raw REST path is of limited value to an agent choosing a 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?

For a simple single-parameter read with no output schema, enumerating the event types in the response largely compensates for the absent return specification. Only ordering and paging behavior remain unaddressed.

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

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

Schema coverage is 100% and the single alert_id parameter is fully documented in the schema, including where to obtain it. The description adds no parameter detail 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 resource (ordered timeline of an alert) and enumerates the event types it contains, which clearly distinguishes it from signl4_get_alert (the alert object) and signl4_get_alert_report. It doesn't explicitly name the siblings it differs from, keeping it 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 or alternatives are given. The agent must infer from the resource that this is the tool for historical event lookup rather than current state, and nothing says when get_alert or get_alert_report would be preferred.

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, destructiveHint=false, openWorldHint=true), so the description's main added value is naming the returned fields (dutyMode, onDutyTime, tier) and the exact endpoint. With no output schema present, that return-shape detail is genuinely useful, though nothing is said about pagination or access scoping beyond the schema's own default note.

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

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

One compact sentence front-loads the core behavior, followed by a short parenthetical of returned fields and the raw endpoint path. The endpoint is marginally redundant but the whole thing is short and 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 simple two-parameter read tool with full schema coverage and annotations covering safety, the description supplies enough: what it returns and the fields involved. Only the absence of fallback/error behavior and any hint of response structure beyond field names keeps it from a 5.

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

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

Schema description coverage is 100%, so both user_id and team_ids are already fully documented, including how to obtain GUIDs. The description adds no syntax, format, or edge-case guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb-and-resource combination: retrieving whether a user is on or off duty per team, plus the underlying endpoint. Clear enough that an agent understands the operation, but it never distinguishes itself from close siblings like signl4_get_duty_summary or signl4_list_duty_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?

There is no statement of when to use this versus signl4_get_duty_summary or signl4_list_duty_schedules, nor any prerequisite context. Usage is only implied by the resource name, leaving the agent to guess which duty-related tool applies.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses what the call returns (enabled state and the last two, or all, duty periods) and cites the underlying GET /v3/duties/summary endpoint, which matters because no output schema exists.

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

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

A single tight sentence plus the endpoint, with the resource and payload front-loaded before the HTTP path. Slight jargon ('Duty assistant info') costs it a point but there is no filler.

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

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

For a read-only, zero-required-param tool with full schema coverage and no output schema, the description covers scope, payload shape and endpoint adequately. Missing only the routing distinction against sibling duty tools and any note on result volume when last_two_only is false.

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 fully documented, and the baseline is 3. The phrase 'last two (or all) duty periods' does echo last_two_only and clarify what setting it false yields, but that is largely a restatement of the schema's own 'Only the last two duties (default true)'.

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 ('duty assistant info per team') and enumerates the payload — enabled flag plus last two (or all) duty periods — which lets an agent distinguish it from a bare status read. It stops short of naming the sibling it overlaps with (signl4_get_duty_status, signl4_list_duty_schedules), so differentiation requires inference.

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 and never mentions the closely related signl4_get_duty_status or signl4_list_duty_schedules siblings. An agent must guess whether this summary or a status/schedule call is the right choice for a given question.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint and enumerates the returned fields, which is useful, but says nothing about auth, rate limits, or behavior when the team 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 compact sentences, front-loaded with the resource and its returned fields, with zero filler. Given there is no output schema, using the second sentence to list return fields is well-earned 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?

For a simple one-parameter read with no output schema, listing the returned fields is a meaningful addition, and annotations carry the safety profile. Missing only error/not-found behavior, which is minor 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% and the single team_id parameter is fully documented there, including sourcing from signl4_list_teams. The description adds no format or constraint detail beyond echoing {teamId} in the path, so the 3 baseline 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 team', 'One SIGNL4 team') and names the fields returned (name, description, time zone, member ids). The word 'One' implicitly separates it from signl4_list_teams, though no sibling is named explicitly.

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

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

Usage is only implied: you call this to retrieve a single team, and the schema note points to signl4_list_teams as the source of the id. There is no explicit when-to-use or when-not-to-use statement in the description itself.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the return content (the field set) even though no output schema exists, plus the underlying endpoint GET /v3/users/{userId}; it says nothing about auth needs, rate limits, or error behavior such as an unknown user 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 short sentences with the resource and its returned fields front-loaded. The second sentence (the raw endpoint path) is close to redundant with the tool name and parameter template, so it is not perfectly waste-free, but the whole definition is compact.

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

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

For a single-parameter read tool with no output schema, the description supplies the missing piece an agent would otherwise lack: what fields come back. Combined with annotations covering the safety profile and a fully documented parameter, nothing essential is missing, though it could have named the list tool as the id source.

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%, including the note that the GUID comes from signl4_list_users, so the schema already carries the semantics. The description only echoes the parameter through the path template {userId} and adds no format or constraint detail beyond maxLength/minLength already in 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?

"One SIGNL4 user" names a specific verb implied by the name and a specific resource, and lists the fields returned (name, e-mail, contact addresses, time zone, duty status per team). It is clear it fetches a single user rather than a collection, though it never names signl4_list_users as the counterpart the way a top-tier definition would.

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: the singular "One SIGNL4 user" plus the required user_id suggest this is for fetching a specific known user, in contrast to signl4_list_users. There is no explicit when-to-use/when-not statement, and the only pointer to signl4_list_users as a prerequisite lives in the schema description, not the tool 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 and destructiveHint=false, so safety is covered; the description adds value by noting the call is 'POST /v3/signls/paged (a read)', pre-empting confusion that a POST implies mutation. It also discloses page size cap, default, and the continuation_token continuation mechanism, though it says nothing about auth scope 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?

Three tight sentences, front-loaded with what is searched and returned before filters and paging mechanics. Every clause carries distinct information (ordering, fields, filters, page cap, continuation, HTTP method).

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 helpfully names the returned attributes (status, severity, category, history timestamps) and the continuation_token, so the agent knows what comes back and how to page. It stops short of describing the response envelope or total counts.

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

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

Schema description coverage is 100% and each parameter already carries its own description and constraints, so the schema does the heavy lifting. The description only restates the filter categories in prose without adding format or syntax detail, matching the baseline 3.

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

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

States a specific verb and resource ('Search SIGNL4 alerts (signls)'), plus ordering ('newest first'), returned fields, and filter axes. An agent can distinguish this paged-list tool from the singular signl4_get_alert and the sibling alter tools without opening a schema.

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

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

The filter axes (team, status, creation time, text, external id) tell the agent when this tool applies, and the paging sentence tells it how to continue. It never explicitly says when NOT to use it or names an alternative listing tool, so it stops short of a 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, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds the genuinely useful pagination contract — a continuation_token is returned and must be passed back — plus the semantic content of each entry.

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 dense sentences: resource and content first, then filtering and pagination mechanics, closed by the endpoint. Nothing redundant and no filler.

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

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

No output schema exists, yet the description tells the agent what an entry represents and how paging continues, which covers the main unknowns. Remaining detail (entry fields, sort order, whether time range is inclusive) is left unstated, a minor gap for a read-only list tool.

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

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

Schema description coverage is 100% and all six parameters are documented there with formats, defaults, and the cross-reference to signl4_list_teams. The description restates the filter axes (team, time, message) without adding syntax or constraints beyond the schema, which is the correct baseline 3.

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

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

Names the specific resource and scope: the SIGNL4 subscription audit log of changes and events, with the 'who changed what, when' content spelled out and the backing endpoint GET /v3/audits given. The verb is only implied by the name 'list', which keeps it 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?

Gives concrete operating guidance: filter by team, time window, and message text, then feed the returned continuation_token back in for the next page. No alternatives or explicit when-not-to-use are named, but no sibling overlaps this resource either.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds the returned field list and the REST endpoint ('GET /v3/categories/{teamId}'), which is mild extra context, but says nothing about pagination, ordering, or auth behavior beyond the annotations.

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

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

Two tight sentences with the resource and returned fields front-loaded before the downstream-use hint. The trailing REST path is slightly redundant metadata but is conventional and tiny; nothing else is wasted.

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 compensates by naming the returned fields, and for a single-parameter read tool that plus the schema is nearly sufficient. Only the absence of any note on result volume/ordering keeps it from being 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 description coverage is 100% and the single team_id parameter already documents its GUID format and points to signl4_list_teams for discovery. The description only implies team scope via 'of a team' and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the alert categories of a team') and enumerates what is returned (name, color, auto-classification keywords), so the agent knows exactly what comes back. It is naturally distinct from all siblings since none of them deal with categories, but it does not explicitly contrast itself with any alternative tool.

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

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

The note that 'the category name can be passed to signl4_raise_alert' gives a concrete downstream use case for calling this tool, and 'of a team' implies team scoping. There is no explicit when-not-call guidance or statement of alternatives, but the workflow context is clear.

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 and destructiveHint=false, so safety is covered. The description adds genuine context beyond them by flagging that the endpoint is 'POST /v3/schedules (a read)', preempting an agent's false inference that POST means mutation.

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, front-loaded sentences with no filler; the purpose leads and the POST-is-a-read caveat is parenthetical rather than buried. Slightly dense packing of field names, but nothing is wasted.

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 enumerating returned fields and naming the filterable dimensions, which is enough for an agent to call and interpret the tool. Missing pagination/total-count behavior is the only notable gap, and limit is covered in the schema.

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 (to, from, limit, user_id, team_ids) is already documented with type, bounds, and guidance. The description's filter summary adds no syntax or semantics beyond the schema, making the baseline 3 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 resource (planned on-call duty schedules) and adds a plain-language gloss ('who is on duty when'), plus enumerates the returned fields (start/end, team, user, tier, stand-in, shift). The word 'Planned' implicitly separates it from get_duty_status/get_duty_summary, but no sibling is named explicitly.

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

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

The clause 'Filter by team, user and time window' maps the tool to its filtering capability, but there is no statement of when to prefer it over signl4_get_duty_status or signl4_get_duty_summary, and no exclusions. Usage is implied rather than directed.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful scoping fact that results are limited to teams the API key can access, but says nothing about pagination, ordering, or behavior when the key has no access; modest value beyond 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?

Two tight sentences, front-loaded with the action and scope, then the downstream rationale, with the endpoint as a trailing reference. Nothing is redundant or 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?

With no output schema, the description usefully enumerates the return fields and explains why the ids matter, which is exactly the missing context. It is nearly complete for a default-all list endpoint; only pagination/ordering behavior is unaddressed.

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

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

Schema coverage is 100% and the single parameter (team_ids) is fully documented in the schema, including where to obtain the GUIDs. The description adds no filter syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the SIGNL4 teams"), scopes it to what the API key can access, and enumerates the returned fields (id, name, description, time zone, member ids). It is clear enough to act on, but it never distinguishes itself from the sibling signl4_get_team (singular).

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: "Team ids are needed to raise alerts and to look up categories and duties," which tells the agent when this tool is a prerequisite. No exclusions or explicit alternative-naming are given, so it stops short of a 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 declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the default scope (all accessible teams) and the error-handling contract ('Teams that cannot be read are reported under `errors`'). This is meaningful disclosure for a read tool.

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

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

Two sentences, front-loaded with the core action and scope, followed by the error contract and endpoint. No filler; every clause carries information.

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

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

For a read-only, single-param tool with full schema coverage and annotations, this is nearly complete. The absence of an output schema is partially mitigated by the description naming the `errors` result field and 'duty status', though the remaining per-user return fields are left unspecified.

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 parameter is fully documented in the schema. The description's '(all accessible teams by default)' restates the schema default rather than adding new syntax or format detail. 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+resource ('List the users of the given teams') and adds a distinguishing detail ('with duty status') that separates it from signl4_list_users and signl4_get_duty_status. It does not explicitly name the sibling it differs from, but the team-scoped framing is clear enough to route correctly.

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?

'all accessible teams by default' clarifies the default scope, implying usage when team_ids is omitted. However, there is no explicit when-to-use guidance versus signl4_list_users or signl4_get_team, and no exclusions. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the result set is bounded by the API key's permissions and duty status is reported per team with dutyMode/onDutyTime. It stops short of stating pagination or rate-limit behavior.

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

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

Two compact sentences plus the endpoint. The primary action and scope lead, the returned fields follow, and the practical motivation (needing user ids) closes it. No filler.

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

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

No output schema exists, so the description carries the return-value burden, and it does so by enumerating the returned fields including the nested duty per-team shape. Combined with parameterless input and clear read-only annotations, an agent has everything needed to call and interpret this tool.

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

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

With zero parameters there is nothing for the description to disambiguate, so the baseline is 4. The description does note that filtering is by the key's access scope rather than by any argument, which usefully explains why no filter parameters exist.

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

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

Specific verb (List) plus resource (SIGNL4 users), the access scope (the key can access), and the exact fields returned (name, e-mail, contact addresses, activation state, duty status per team). This distinguishes it from signl4_get_user (single user) and signl4_list_team_users (team-scoped), so an agent can pick it without opening a schema.

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

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

It supplies a concrete reason to call it – 'User ids are needed to acknowledge/close/annotate alerts' – which links it to the ack/close/annotate siblings. It does not, however, state when to prefer signl4_list_team_users over this tool when team scoping is the goal, so the routing guidance is good but not exhaustive.

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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description goes well beyond them: it explains *why* it is destructive (every on-duty member is paged by push, SMS and/or voice), what escalation does if nobody acknowledges, and what non-idempotency concretely means ('a second call pages the team again'). It also discloses the return payload shape (the new alert incl. its id), which no output schema provides.

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

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

Four dense sentences, front-loaded with the operation mode and resource, then stakes, then usage restriction, then return/endpoint. No filler or restated name, and each sentence carries decision-relevant information.

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

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

With no output schema, the description still tells the agent what comes back (the new alert including its id), and it covers the safety profile, escalation behavior, and usage boundary. Nothing an agent needs to call this correctly or avoid a mistaken page 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 every parameter (team_id, title, text, category, severity, external_id) is already documented in the schema, including cross-references to signl4_list_teams and signl4_list_categories. The description adds no per-parameter semantics beyond that, so the baseline 3 applies.

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

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

Opens with an explicit verb+resource and mode label ('WRITE: raise a new alert in a SIGNL4 team'), which immediately separates it from read siblings like signl4_get_alert and state-change siblings like signl4_acknowledge_alert or signl4_close_alert. The endpoint (POST /v3/signls) reinforces the resource identity.

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?

States both the positive condition ('Only use it when the user clearly asked to alert the team') and an explicit exclusion ('never for tests unless they said so'), which is exactly the ambiguity an agent would otherwise guess at. The real-world consequence sentence gives the agent the stakes needed to decide.

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