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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered. The description adds nothing beyond them: 'from provided data' hints at a payload but does not say whether the association is additive, whether duplicates are rejected, or whether re-attaching is safe despite idempotent=false.

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

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

A single front-loaded sentence with no wasted words. Its brevity is efficient, though it contributes to the under-specification scored elsewhere.

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?

This is a mutating tool with a nested request envelope and an output schema, yet the description does not explain the data wrapper structure, the expected alert state, or error conditions. An output schema exists, so return values need not be explained, but the input-side and behavioral gaps remain substantial.

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 only 50%: incident_id is documented in the schema, and alert_ids has a brief schema description, but the nested 'type'/'attributes' envelope and the meaning of passing null alert_ids are unexplained. 'From provided data' adds no meaning beyond what the schema already shows.

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 verb and resource ('Attach alerts to an incident'), which is enough to distinguish it from pure read siblings like list_incident_alerts, but the trailing phrase 'from provided data' is vague filler that does not clarify the operation. It does not name the closest sibling or explain how it differs from creating/updating alert events.

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 statement of when to use this tool, what prerequisites exist (e.g., that the alerts must already exist), or what alternatives to prefer. The agent must infer everything from the name and schema.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds the useful constraint that the investigation must be running, but it does not explain effects on investigation data, reversibility, or required permissions.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a simple one-parameter cancellation 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?

An output schema exists and annotations carry the safety and idempotency profile, so the description need not explain return values. For a simple cancel operation, the description is nearly complete, though it could mention the running-state prerequisite more explicitly and what cancellation does to the investigation.

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 investigation_id parameter is documented as a UUID in the schema. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 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?

The description states a specific verb and resource: cancel an investigation. It is clear what the tool does, but it does not distinguish itself from siblings such as start_investigation, get_investigation, or list_investigations.

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 implies the tool applies to a running investigation, but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer that it should not be used for completed investigations or that get_investigation is for inspection.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond them: it discloses the privacy footprint (identifiable employee workload health data), the opt-in configuration gate, the self-hosted-only constraint, and the optional replacement-recommendation behavior. That is exactly the extra context an agent needs before calling an open-world read that touches sensitive HR 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?

Front-loaded with the core purpose, then prerequisites and privacy — good ordering. Slight redundancy: the ONCALLHEALTH_API_KEY requirement is stated twice ('administrator must explicitly configure' and again as 'Requires ONCALLHEALTH_API_KEY environment variable'), and the self-hosted note is appended as a fragment.

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?

Output schema exists, so return values need not be described. With 100% parameter documentation, explicit prerequisites, privacy disclosure, and an output schema, an agent has everything required to decide whether to call it and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning by framing start_date/end_date as the 'specified period', tying och_analysis_id to 'On-Call Health analysis', and explaining that replacements are optional (include_replacements). It stops short of explaining what the och_threshold score means or what happens when och_analysis_id is null, which the schema only partially covers.

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 ('check') plus a precise resource ('at-risk responders ... scheduled for on-call') and ties it to a named upstream source (On-Call Health analysis). An agent can distinguish this from sibling tools like check_responder_availability or get_oncall_schedule_summary purely from the description, since those do not involve health-risk scoring.

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 strong gating context: opt-in feature, administrator must configure ONCALLHEALTH_API_KEY, self-hosted deployments only. It does not name an alternative tool or say 'use X instead when Y', but the availability preconditions are explicit enough that an agent knows when the tool cannot be used.

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 substantive behavior beyond that, namely that results split into scheduled and not-scheduled users and that shift times and hours are clipped to the requested window. The UTC whole-day inclusion rule for date-only end dates is exactly the kind of edge-case disclosure annotations cannot carry.

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

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

Four short sentences, front-loaded with the core purpose, then usage, then return behavior. Each sentence adds a distinct fact with no repetition of the title or schema.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover safety. The description still supplies the interpretation rules an agent needs (clipping, inclusive UTC day) and the pre-assignment use case, leaving nothing material missing for a 3-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: window clipping and the fact that a date-only end date includes that entire UTC day. The user_ids resolution path is documented in the schema rather than the description, so it is not double-counted.

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

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

The description names a specific verb and resource ('Check if specific users are scheduled for on-call') and scopes it to a date range and a user list, which separates it from listing tools like list_shifts or get_schedule_shifts. It stops short of naming a sibling 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?

It gives two concrete usage scenarios: verifying at-risk users surfaced by On-Call Health, and pre-assignment availability checks. There is no when-not guidance or named alternative for adjacent needs such as viewing a full schedule, so context is clear but exclusions are absent.

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 and destructiveHint=false, so the safety profile is covered; the description adds genuine non-obvious behavior that annotations do not: multi-page collection, compacted payloads, and that out-of-bounds arguments are clamped and reported rather than rejected. It stops short of covering rate limits, permissions, or how paging failures surface, so it is strong but 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?

Three short sentences ordered by usefulness: what it does, when to choose it over the sibling, then the argument caps. No filler, no restatement of the title, and the routing guidance is front-loaded before the mechanical details.

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 12 optional params, an output schema already defined, and read-only annotations, the description covers the essentials an agent needs: purpose, alternative selection, and bounds behavior. The gaps are not mentioning search_incidents as an alternative and not clarifying what 'compact' means relative to a full incident record, which matters for audit use.

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% across all 12 parameters, and the description's stated caps (max_results <= 100, batch_size 10-100) largely restate what the schema already declares as min/max. The one marginal addition is that out-of-range values are clamped rather than erroring, which is useful but thin against an otherwise schema-driven parameter story — 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 concrete verb and resource ('Collect a bounded working set of incidents across multiple pages') and frames the output shape ('compact batch', 'payload size under control'), which is clearly distinct from a plain list. It explicitly contrasts with list_incidents, though the closely related filtering sibling search_incidents is never addressed, leaving some ambiguity about which filtering tool to pick.

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?

'Use this instead of list_incidents when you want a compact batch of incidents in one tool call' gives an explicit alternative and the condition that selects it. However, it offers no when-not guidance and never mentions search_incidents, which overlaps heavily on the query/team/severity filters this tool exposes.

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

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

Adds substantial behavior beyond the readOnly/openWorld annotations: authentication requirements, OAuth scope, permission model, 60 requests/minute limit, 429 rate_limited envelope, Retry-After header, attribute multiplicity, attribute_missing warnings, and drill-down null conditions. This is unusually complete for a read-only analytics 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?

The description is front-loaded with purpose and a concrete example, then layers operational details. It is dense and long, but nearly every sentence carries useful behavioral or constraint information for a complex endpoint.

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

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

Given the output schema and annotations, the description covers the remaining gaps an agent needs: auth, rate limits, grouping behavior, drill-down semantics, warnings, and query limits. Nothing material appears missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description still adds useful semantics: group_by examples including attribute keys, filter query examples, and the meaning of meta.total versus per-value counts. It does not need to repeat every schema 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 and resource: count logs matching a Logs explorer query, grouped by service, index, severity, or attribute key. It clearly distinguishes aggregation from row retrieval by explaining that each value's logs_query drills into rows via GET /v1/observability/logs.

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 usage example ('errors per service in the last 6h') with the exact filter and group_by parameters. It also explains the alternative drill-down path for raw rows, making the count-vs-list distinction explicit.

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

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

Annotations already declare a non-read-only, non-idempotent, open-world write, so the description needs to add operational context — and it adds none. Notable behaviors such as deduplication-key coalescing ("alerts sharing the same deduplication key are treated as a single alert"), actor-attribution rules, and On-Call-only fields go unmentioned at the description level.

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 short sentence, so nothing is bloated, but it is under-specified rather than concise — the brevity comes at the cost of any useful information about the creation payload or its gating conditions.

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 create tool with a deeply nested 20+ field payload, On-Call-gated fields, deprecated fields, and deduplication behavior, a single generic sentence is not enough. An agent cannot tell from the description what a minimally valid call looks like or which attributes have side effects.

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 a single `data` wrapper whose nested attributes are extensively self-documented in the schema (actor, deduplication_key, notification_targets precedence, source deprecation), so the schema carries the semantics. The description adds no parameter meaning whatsoever, leaving it at the baseline for a schema-rich tool.

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?

It states a verb and resource ("Creates a new alert"), which is clear enough on its own, but the trailing "from provided data" is filler and the description never distinguishes this from nearby siblings such as create_alert_group, create_alert_event, or attach_alert.

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

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

There is no guidance about when to create an alert versus creating an alert event, attaching an existing alert, or adding it to an alert group. No prerequisites (API key scope, On-Call enablement) are mentioned even though several schema fields are gated on them.

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

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

Annotations already state readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false. The description adds nothing on top – it does not warn that non-idempotent creates can duplicate, does not say what permissions are needed, nor that the event is a note attached to an alert. With annotations present the bar is lower, but zero added context still merits a 2.

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 four-word sentence with no padding, so it is concise, but the terseness comes at the cost of any front-loaded useful detail. It is efficiently written yet under-specified rather than genuinely well-structured.

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 tool has a nested input object, a non-trivial enum ('alert_events'/'note'), an output schema, and write semantics. The description addresses none of this and gives no indication of what a successful response contains or what constraints apply.

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 only 50%, and the nested data object with its enum-constrained type and kind fields is barely documented. The description does not clarify that the only supported event kind is a note, nor how alert_id maps to the path – information the agent must dig out of the schema unaided.

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?

"Creates a new alert event" restates the tool name and title almost verbatim, adding no distinguishing detail. With siblings like update_alert_event, list_alert_events, and get_alert_event in the same family, an agent learns nothing new about what this specific operation produces.

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 guidance, no mention of the sibling tools (update_alert_event, list_alert_events), and no stated prerequisites beyond alert_id being required. The agent must infer the entire call 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=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only a field-deprecation recommendation, which is parameter guidance rather than behavioral context; it says nothing about side effects (e.g. that the group begins grouping/routing alerts immediately), name-uniqueness constraints, required permissions, or owning-team feature gating.

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 action, with the migration advice second. No filler; the deprecation note earns its space because the schema marks those fields deprecated but the description explains the preferred path. Slightly verbose in enumerating three legacy fields by 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?

An output schema exists, so return values need not be explained, and the nested field semantics largely live in the schema. However, for a creation tool with a deeply nested payload, the description omits whether `targets` are effectively required for the group to do anything, whether `name` must be unique, and what happens to alerts arriving during creation.

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?

Top-level schema description coverage is reported as 0% for the single `data` wrapper, though nested properties carry their own descriptions. The description compensates on the highest-value decision by recommending `conditions` over the legacy `group_by_alert_title`, `group_by_alert_urgency` and `attributes` fields, but says nothing about `targets`, `time_window`, `condition_type` or `owner_group_ids`.

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 first sentence names a specific verb and resource ("Creates a new alert group"), which cleanly separates it from list_alert_groups, get_alert_group and update_alert_group in the sibling set. It stops short of explicitly contrasting with update_alert_group or noting preconditions, but the intent is unmistakable.

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 by the name and the deprecation note. The note steers the agent toward `conditions` over the legacy fields, which is field-level guidance rather than tool-level when/when-not guidance. There is no statement about when to create a group versus reusing an existing one, or what prerequisites (targets, owning teams) must exist first.

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 the safety profile (not read-only, not destructive, not idempotent), and the description goes well beyond that: feature gating, automatic async processing when the rule graph exceeds the request timeout, the size metric (rules plus condition groups, conditions, destinations), and the fact that the returned rules list can be stale. One flaw: it tells the agent to poll with "the `request_id` you supplied," but no such field exists in the schema, which could send an agent hunting for a nonexistent parameter.

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?

Headers and bold emphasis front-load the access prerequisite and the async caveat, which is good structure. But the async discussion sprawls across four paragraphs, and the closing "contact Rootly customer support" sentence largely repeats the support mention already made in the opening note, so the length is not fully earned.

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 an output schema present, return-value explanation is correctly omitted, and annotations cover the mutation profile. The description covers the two things an agent could not infer elsewhere — the Advanced Alert Routing entitlement and the asynchronous rule-creation caveat. The only meaningful omission is any hint about the `data` payload contract, which the schema itself carries.

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?

Top-level schema description coverage is 0% — the single `data` parameter is undocumented — and the description adds no semantics about its shape, required attributes (name, alerts_source_ids), or the rules/destinations/condition_groups nesting. It even references a `request_id` parameter that is absent from the schema. The deeply nested field-level descriptions in the schema do most of the real work, which limits the practical harm, but the description itself contributes nothing here.

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 opening sentence names a specific verb and resource ("Creates a new alert route"), which is enough to separate it from update_alert_route, patch_alert_route and create_alert_routing_rule by name alone. It does not explicitly contrast itself with those siblings, and "from provided data" adds nothing, so it stops short of a 5.

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

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

It gives a real prerequisite (Advanced Alert Routing access, contact support if unsure) and post-call guidance (refetch or poll the async status endpoint). However, it never says when to use this versus update_alert_route or create_alert_routing_rule, so the create-vs-update routing decision is left to inference.

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

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

The annotations already declare readOnly=false, idempotent=false, destructive=false, and openWorld=true. The description adds a useful routing-mode caveat but does not disclose permissions, side effects, or idempotency 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 sentences, front-loaded with the core action and followed by a relevant routing-mode note. There is little waste and the important caveat is easy to spot.

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 complex nested create tool, the description covers purpose and the advanced-routing alternative, while annotations and the output schema cover safety and return behavior. It could say more about required data shape or advanced routing implications, but the schema fills most field-level gaps.

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 description adds no parameter-level meaning beyond the schema. The schema itself documents nested fields such as name, enabled, conditions, destination, and owning_team_ids, so the baseline is adequate even though the description does not compensate for the reported low coverage signal.

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: creating a new alert routing rule. It also distinguishes this tool from the sibling Alert Routes endpoint for advanced users, though the phrase "from provided data" is vague.

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

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

It explicitly says advanced alert routing users should use the Alert Routes endpoint instead, and tells uncertain users to contact support. This gives a clear when-not condition and alternative, though it does not describe the normal non-advanced use case in detail.

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 indicate this is a non-read-only, non-idempotent, non-destructive, open-world operation. The description adds no behavioral context such as required permissions, validation rules, what happens if the source type is invalid, or side effects of creation.

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

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

The single sentence is front-loaded and contains no wasted clauses, but it is far too sparse for a tool with a deeply nested input schema. It is concise without being appropriately sized.

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?

Output schema and annotations are present, so return values and basic safety need not be in the description. However, for a complex nested creation payload with source-type-specific attributes, the description provides no useful setup or payload guidance.

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 single 'data' parameter has no top-level description and the tool description merely says 'from provided data.' Although the nested schema is detailed, the description itself does not explain the required wrapper shape, required fields, or source_type-dependent attributes.

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 the core action, creating an alert source, but adds no detail beyond the tool name and title. 'From provided data' is tautological filler rather than a distinguishing purpose, and it does not clarify how this differs from list/get/update alert source 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?

There is no guidance on when to use this tool versus list_alerts_sources, get_alerts_source, or update_alerts_source, nor any prerequisites or exclusions. The description only restates the obvious create action.

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 annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the basic mutation profile is known. The description adds nothing about duplicate-name behavior, required permissions, validation, or side effects of creating an urgency.

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?

It is a single short sentence with no wasted words, but it is under-specified rather than appropriately concise. The sentence does not earn its place because it provides no information beyond 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 create tool with a nested payload and multiple optional fields, the description is far too thin. The output schema may cover return values, but the description still fails to explain the required input structure, constraints, or intended use.

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 description says only 'from provided data' and does not explain the required data envelope, the alert_urgencies type enum, or the required name/description fields. Although some nested properties have schema descriptions, the description itself does not compensate for the 0% top-level schema description coverage.

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

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

The description restates the tool name and title almost verbatim: 'Creates a new alert urgency' adds no detail beyond the name, and 'from provided data' is filler. It does not explain what an alert urgency is or how creation differs from siblings such as update_alert_urgency.

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

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

There is no guidance on when to use this tool versus alternatives like update_alert_urgency or list_alert_urgencies. No preconditions, typical scenarios, or exclusions are stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description contributes nothing beyond that — no mention of what is created, what a duplicate name does, or any side effects — so it fails to add value on top of 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?

It is a single short sentence, so nothing is wasted, but the brevity is under-specification rather than efficiency — there is no front-loaded detail or structure for the agent to act on.

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 write tool with a deeply nested payload and an output schema present, the description leaves major gaps: what a catalog is in this product, required fields, slug derivation, and external_id uniqueness constraints are all unstated. An agent would have to read the nested schema closely to call this correctly.

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

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

There is one parameter, a nested object, with 0% top-level schema description coverage. The description says only "from provided data," adding no meaning: it does not mention that `name` is required, that `slug` is deprecated and derived from `name`, or that `external_id` must be unique within the team, even though those nested-field descriptions exist in the schema.

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

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

The verb+resource ("Creates a new catalog") is identifiable, but the trailing "from provided data" is filler that adds nothing. It does not distinguish this tool from the many adjacent creators such as create_catalog_entity, create_catalog_property, or update_catalog, so an agent cannot tell scope apart from siblings on the description alone.

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 update_catalog, list_catalogs, or create_catalog_entity. No prerequisites (permissions, uniqueness of name/external_id, whether a team context is required) are mentioned, leaving the agent to infer everything from the schema.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, open-world create operation. The description adds no behavioral context beyond that, such as whether the catalog must exist, how uniqueness constraints are handled, or what side effects occur.

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

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

The description is a single short sentence with the action front-loaded, so it is structurally efficient. It loses a point because "from provided data" is filler rather than useful conciseness.

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 create tool with a nested object schema and several entity fields, the description is far too thin. An output schema exists, so return values need not be explained, but the description still fails to cover the catalog context or the shape of the data being created.

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 only 50%, and the top-level required "data" object has no description at all. The phrase "from provided data" is tautological and does not compensate for the missing explanation of how catalog_id and the nested entity payload should be supplied.

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 ("Creates a new Catalog Entity"), which is clearer than a bare tautology. However, "from provided data" adds no meaningful scope, and it does not distinguish this tool from nearby siblings such as create_catalog or create_catalog_entity_property.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites such as needing an existing catalog, and no exclusions. The agent is left to infer usage entirely from the name and schema.

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

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

Annotations already disclose that this is a non-read-only, non-destructive, non-idempotent, open-world operation, so the safety profile is covered. The description adds important behavioral context by marking the endpoint deprecated and naming replacement pathways, though it does not discuss permissions or side effects beyond that.

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

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

The description is two sentences with the deprecation warning front-loaded, followed by the core action. There is no wasted text, and the most important use guidance appears first.

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

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

Given the tool has a rich nested input schema, annotations, and an output schema, the description is mostly complete: it clearly marks the tool as deprecated and names alternatives. The main gap is that it does not clarify the nested `data` payload semantics, but the schema covers much of that structure.

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 only 50%, and the description adds essentially no parameter detail beyond "from provided data." It does not explain the nested `data.attributes` structure, required keys, or the catalog field value limit, leaving the schema to carry the burden without compensating prose.

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

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

The description states a specific verb and resource: "Creates a new Catalog Entity Property." It also flags deprecation and points to replacement approaches, but it does not explicitly distinguish this create tool from sibling tools such as update_catalog_entity_property or create_catalog_property beyond the name.

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

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

It explicitly says the endpoint is deprecated and directs callers to use the `fields` attribute on catalog entities or native catalog endpoints instead. This gives clear when-not-to-use guidance and names concrete alternatives.

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

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

Annotations already disclose that this is a non-destructive, non-idempotent write operation in an open-world context. Beyond that, the description only says it returns a 'catalog_properties type' and adds no details about creation behavior, uniqueness constraints, required fields, or side effects.

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

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

The description is very short and front-loaded, with no wasted clauses. However, its brevity contributes to under-specification for a nested-object creation 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 nested-object mutation with open-world behavior and no output schema, the description is too sparse. It does not explain required fields, valid kinds, catalog scoping, uniqueness behavior, or what the returned catalog property 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 only 50% and there are nested parameters, but the description adds no parameter meaning. It does not explain catalog_id, the data wrapper, or the required nested attributes such as name and kind, leaving the schema to carry the burden.

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

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

The description states a specific verb and resource: 'Creates a new Catalog Property.' It is clear what the tool does, but it does not distinguish this from closely related sibling tools such as create_catalog_entity_property or update_catalog_property.

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 provides no guidance about when to use this tool, prerequisites such as needing an existing catalog, or how it differs from alternatives like create_catalog_entity_property and update_catalog_property.

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=false, openWorldHint=true, and idempotentHint=false, so the agent knows this is a non-destructive but non-idempotent write. The description adds only 'from provided data', which contributes no behavioral context beyond what the annotations already state.

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

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

The description is a single short sentence, which is concise, but it is under-specified rather than front-loaded with useful detail. It avoids waste but also avoids providing necessary context.

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

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

This is a create mutation with a complex nested schema and no schema coverage for the top-level parameter. Even with output schema present and annotations covering the safety profile, the description is too thin for an agent to understand what data is required or how the cause creation behaves.

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 0% for the top-level data parameter, and the description says nothing about the required nested structure, attributes, or how the data object should be assembled. It provides no meaning beyond the parameter name itself.

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: 'Creates a new cause'. It does not differentiate this tool from siblings such as update_cause or create_catalog_entity, but the core purpose 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?

There is no guidance on when to use this tool versus alternatives like create_catalog_entity or update_cause, and no prerequisites or exclusions are mentioned.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the safety bar is lower. The description's only added behavioral context is the deprecation lifecycle status, which is genuinely useful but is not accompanied by any note on side effects, uniqueness constraints on labels, or what a repeated call does.

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 deprecation warning front-loaded, which is exactly the right ordering for a deprecated tool. The only waste is the redundant "from provided data" clause.

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?

An output schema exists so return values needn't be described, and the deprecation notice covers the biggest risk. However, for a nested-object mutation tool with 0% top-level schema description coverage, the description leaves the caller to reverse-engineer the `data` envelope entirely from 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 reported as 0% at the top level, and the description says nothing about the single `data` parameter — no mention of the required `type`/`attributes` envelope, the mandatory `label`, or the enum-constrained `shown`/`required` placement lists. The nested schema does document its own properties, which prevents a 1, but the description itself contributes zero parameter meaning.

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 ("Creates a new custom field") and immediately flags deprecation, which distinguishes it from the active form-field creation siblings. The trailing "from provided data" adds nothing, but the core purpose is unambiguous.

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

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

Explicitly routes the agent away from this tool with "Use form field endpoints instead", which is a real alternative-selection signal rather than implied usage. It does not name the specific sibling (create_form_field) nor say under what legacy conditions this tool would still be correct, 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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context at all — no note on validation failures, whether the created form is enabled by default, or what happens to the discarded slug. With full annotation coverage, a 2 reflects a description that contributes nothing beyond them.

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 short sentence with no padding and the verb front-loaded, but its brevity comes from under-specification rather than discipline — the content is essentially the title plus a filler phrase.

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

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

An output schema exists, so return values need not be explained, and annotations cover the mutation/safety profile. However, for a nested-payload creation tool in a crowded form-related namespace, the description lacks the field-level and disambiguation detail an agent needs, so it is not 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?

The single parameter is a deeply nested object whose meaningful fields (name, command, enabled, description, deprecated slug) are only partly documented in the schema, and the description mentions none of them. It does not tell the agent that 'command' is a required Slack trigger or that slug is ignored, so it fails to compensate for the low schema coverage on a nested-object payload.

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

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

Names a specific verb and resource (create a custom form), which is better than a pure tautology, but "from provided data" adds nothing and the description never distinguishes this from sibling creators like create_custom_field, create_form_set, or create_form_field in the same domain.

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

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

There is no guidance on when to use this tool, what prerequisites exist (e.g. a Slack command string is required), or how it relates to update_custom_form or the form-set/form-field tools. The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond that: no mention of required auth scope, whether name collisions are rejected or duplicated (relevant given idempotentHint=false), or whether the dashboard is immediately visible.

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 short sentence with no padding, but it is under-specified rather than economical — the one clause present ("from provided data") carries no information, so brevity here is a cost, not a virtue.

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 tool has a nested required payload and no useful description of it; the existence of an output schema excuses not explaining return values, and annotations cover side-effect hints, but the create contract itself (payload shape, uniqueness, ownership semantics) is absent. For a create operation in a large sibling set this is inadequate.

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 only parameter is a deeply nested `data` envelope with required `type`/`attributes` and required `name`/`owner`, yet the description contributes nothing about that structure. Even though several leaf fields carry schema descriptions, the top-level shape an agent must construct is undocumented in the description, so "from provided data" leaves real work unexplained.

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 verb+resource ("Creates a new dashboard") is unambiguous and clearly distinct from update_dashboard / list_dashboards / get_dashboard. However, "from provided data" is filler that says nothing about what a dashboard payload contains or what gets created, so the statement stops at minimum viability.

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

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

There is no guidance on when to call this versus update_dashboard or how it relates to creating panels via update_dashboard_panel, and no prerequisites (permissions, ownership rules, whether the dashboard must be attached to a team) are mentioned. The agent must infer all routing decisions.

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 write, non-idempotent, open-world, non-destructive, so the safety profile is covered. The description adds nothing beyond that: no permission requirements, no side effects, no note that name must be unique or that slug is derived and ignored, and no response shape context despite this being a 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?

One front-loaded sentence with no padding, so structure is fine. However, for a tool wrapping a nested object with nine attributes, this level of brevity reads as under-specification rather than efficient conciseness.

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

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

Given a complex nested input, an output schema, and annotation coverage, the description omits nearly everything an agent would need: what constitutes valid environment data, slug derivation, defaults, and permission requirements. The schema carries most of the weight, leaving the description incomplete for a creation 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?

The top-level schema description coverage is reported as 0% and the 'data' wrapper is unexplained; the description says only 'from provided data'. Nested field descriptions exist in the schema (name, deprecated slug, color, properties), but the description does not add or clarify any of that semantics.

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

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

States a specific verb and resource ('Creates a new environment'), which distinguishes it by name from list/get/update siblings, but 'from provided data' adds nothing and the description never explains what an environment is in this product. It is adequate but thin.

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 such as update_environment or of how create differs from other creation tools. The agent gets no help choosing this tool over its siblings.

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=false, idempotentHint=false and openWorldHint=true, so the agent knows this is a non-idempotent write. The description adds nothing beyond that: it does not mention duplicate-creation behavior on retry (relevant given idempotentHint=false), what the new level defaults to, or where the level is appended within the policy.

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 short sentence with zero waste, but it is under-specified rather than efficient — every clause merely restates the tool name. There is no front-loaded information an agent could not already get from the title.

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

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

This is a mutation tool with a deeply nested object parameter (notification targets, paging strategy enums, path selection) and an output schema, so return values need not be described. However, the description explains nothing about the nested payload's required structure or the default-path behavior, leaving a substantial gap for a create operation of 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 only 50%, and the top-level `data` wrapper is undocumented in both the schema and the description. The phrase "from provided data" conveys no semantics about the required position, notification_target_params, or the optional dynamic path defaulting behavior, so the description fails to compensate for the coverage gap.

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 pairs a specific verb and resource ("Creates a new escalation level") which matches the tool name but adds no differentiation from siblings such as create_escalation_level_paths or create_escalation_policy. The trailing phrase "from provided data" is filler that restates the schema rather than clarifying scope.

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

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

There is no guidance on when to use this versus the closely related create_escalation_level_paths, create_escalation_policy, or update_escalation_level tools. No prerequisites, no mention that an escalation_policy_id must exist first, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no note on whether the level is appended to a default path when no path ID is given, no side effects, no idempotency caveat. 'From provided data' is pure filler.

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 short sentence with no waste, but the brevity comes at the cost of under-specification rather than efficiency. The one clause it does include, 'from provided data', carries no 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?

This is a mutation tool with a deeply nested payload (notification targets, paging strategy configuration) and an output schema; the description covers none of that structure, no prerequisites, and no failure modes. For a create operation with a nested 2-parameter body, far more guidance is required.

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 50%, and the undocumented half is the entire top-level 'data' wrapper. The description says nothing about either parameter, so it does not compensate for the gap — notably it omits the default-path behavior that the nested escalation_policy_path_id field describes.

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 verb and resource are stated ('Creates a new escalation level'), but the tool is named create_escalation_level_paths while the description talks only about levels, and the sibling list contains both create_escalation_level and create_escalation_path. Nothing distinguishes this tool from those, so the agent cannot tell which one to pick from the description alone.

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 guidance, no mention of the required escalation_policy_path_id scope, and no pointer to the alternative sibling tools (create_escalation_level, create_escalation_path) that create similar resources. Usage must be inferred entirely from the schema.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context of its own — nothing about the required after_deferral_behavior for deferral paths, the team-level gating on notification type conditions, or what happens on duplicate creates.

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 short, front-loaded sentence with no preamble, which is structurally sound. But 'from provided data' is pure filler, and the brevity is under-specification rather than economy given the tool's complexity.

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 tool with 20+ nested attributes, polymorphic rules, time zones, and deferral-path semantics, a single generic sentence leaves the caller to reverse-engineer intent from the schema. An output schema exists, so return values need not be explained, but the description is far too thin for 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 only 50% at the top level, and the data object's purpose is never explained in the description beyond 'provided data'. While the deeply nested attributes carry their own schema descriptions, the description itself contributes no meaning about escalation_policy_id or the data envelope.

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: creating a new escalation path. However, it offers no differentiation from close siblings such as create_escalation_level_paths or update_escalation_path, and the trailing phrase 'from provided data' adds nothing.

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

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

There is no guidance on when to use this tool versus create_escalation_level_paths or update_escalation_path, no stated prerequisites (an existing escalation_policy_id), and no mention that the payload must distinguish escalation vs deferral paths.

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, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the mutation/idempotency profile is covered. The description adds nothing on top: not what is returned, not that duplicate names may collide, not that a newly created policy without escalation levels does nothing, not what the 'data' envelope must look like.

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 short front-loaded sentence, so it is not bloated, but half of it ('from provided data') carries no information. Brevity here reflects under-specification rather than disciplined editing.

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

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

For a non-idempotent create with a deeply nested payload (business hours, time zone enum, group/service associations) and no annotation depth beyond the standard hints, this description is far too thin. An output schema exists so return values need not be described, but the input contract and post-creation workflow are 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?

There is one top-level parameter, 'data', with 0% description coverage and no explanation in the description beyond 'provided data', which is circular. The nested attributes are self-documented in the schema, but the JSON:API-style wrapper (required 'type' enum, required 'attributes' object) is never explained by either the schema or the description.

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 verb+resource pair 'Creates a new escalation policy' is concrete, but 'from provided data' is tautological filler. With close siblings such as create_escalation_level and create_escalation_path in the catalog, the description does nothing to distinguish this tool from them or to explain how a policy relates to levels/paths.

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 indication of when to use this versus update_escalation_policy, create_escalation_level, or create_escalation_path, and no prerequisites (permissions, required group/service IDs, whether levels must be added afterwards). The agent gets no routing guidance at all.

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, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not mention the 200-with-existing-field no-op behavior, the team form-set provisioning side effect, or any permission requirement, all of which are material for a create call.

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

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

At six words it is short, but this is under-specification rather than conciseness: there is no front-loaded statement of what gets created, what is required, or what happens on conflict. Every sentence that exists is filler ("from provided data").

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

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

This is a complex creation tool with a large nested body, ~35 enum kinds, an incident/problem resource_type split, and side effects like default problem form provisioning. An output schema exists so return values need not be explained, but the description supplies none of the operational context an agent needs to call it correctly.

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

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

Schema description coverage is reported at 0% for the single top-level `data` parameter, and the description does not compensate — it says only "from provided data". The nested attributes happen to be richly documented in the schema itself, but the tool description contributes no meaning about required fields, the type discriminator, or how kind/resource_type interact.

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 reads "Creates a new form_field from provided data", which is essentially the tool name and title restated with the filler phrase "from provided data". It conveys a verb and a resource, but offers no distinction from siblings like update_form_field, create_custom_field, or create_form_field_option.

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

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

There is no guidance on when to use this tool rather than update_form_field, create_custom_field, or list_form_fields, and no preconditions such as required permissions or the need for Problem Management to be enabled. The agent must infer all routing and eligibility from the schema alone.

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=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that – no mention of required parent form_field, whether duplicate values are rejected, or whether a default option displaces existing defaults.

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

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

The single sentence is front-loaded and wastes no words, but a mutation tool with a nested object payload warrants more than eight words. It is efficiently written yet underspecified relative to the complexity of the schema.

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

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

The input schema is nested and only half documented, and while an output schema exists to cover return values, the description leaves out the parent-child relationship to form_field_id and any constraint on the value/color/position combination. For a write tool creating a nested resource, this is inadequate.

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 only 50% (color, value, position, form_field_id described; default and type undocumented), and the description contributes no parameter meaning at all – "from provided data" says nothing about the nested attributes object. With a nested object structure, the description should compensate for the coverage gap and does not.

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 says "Creates a new form_field_option from provided data," which essentially restates the tool name and title without adding scope. It does not distinguish this from siblings like update_form_field_option, list_form_field_options, or get_form_field_option beyond the verb "creates."

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

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

There is no guidance on when to use this instead of update_form_field_option or when a form_field must exist first. The only implied usage cue is the verb "creates," leaving the agent to infer context from the name alone.

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=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. But the description adds nothing beyond that: it omits that resource_type=problem requires Problem Management to be enabled and silently provisions a default problem form set, and that duplicate submissions are non-idempotent. No contradiction with annotations, but zero added context for a write tool with side effects.

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 short sentence is technically concise and front-loaded, but it is under-specified rather than efficient; it earns its place only trivially since it conveys nothing the tool name does not.

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

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

Given a nested-object create tool with conditional side effects and a required payload, the description is far too thin. An output schema exists, so return values need not be explained, but the missing prerequisites, provisioning behavior, and payload shape leave an agent without what it needs to call this correctly.

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

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

There is one top-level parameter (a wrapper object) with 0% top-level schema description coverage, so the description is expected to compensate and does not. It says nothing about the required 'data' envelope, the required name/forms attributes, the deprecated slug, or the incident/problem enum behavior — all of which live only in the nested schema.

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

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

The sentence is essentially a restatement of the tool name and title: 'Creates a new form_set from provided data' adds no scope, no resource detail, and no differentiation from siblings such as update_form_set, list_form_sets, or get_form_set. 'From provided data' is filler rather than specification.

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

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

There is no guidance on when to use this versus update_form_set (for existing sets) or list_form_sets/get_form_set (for reads), and no prerequisites are stated. The agent must infer from the name alone that this is the creation path.

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=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds no further behavioral context — it doesn't mention side effects, whether duplicate names collide (relevant since idempotentHint is false), or any auth/permission requirements for a mutation tool that touches many linked resources.

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 short sentence, front-loaded with the verb, so there is no bloat. However, the trailing phrase "from provided data" is pure filler and the brevity comes at the cost of substance rather than being earned concision.

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 tool takes a deeply nested object with many linked-entity fields, so the description should clarify what the create operation requires and what gets set. An output schema exists so return values needn't be explained, and annotations cover safety, but the description still leaves the agent without enough to know what a valid creation looks like.

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 reported at 0% for the top-level parameter, and the description only says "from provided data", which gives no meaning about the required type/attributes envelope. Nested fields do carry their own schema descriptions (including the deprecated slug note), which mitigates somewhat, but the description itself contributes nothing about which attributes are required.

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?

"Creates a new functionality" names a verb and a resource, so the basic action is identifiable, but "functionality" is a domain-specific entity that is never explained and "from provided data" adds nothing. It also does not distinguish itself from the sibling update_functionality or explain how a functionality differs from a service or catalog entity.

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

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

There is no guidance on when to use this versus update_functionality, or on prerequisites such as required permissions or whether related entities (services, environments, owner teams) must already exist. Only the verb "creates" implies the usage 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=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. However the description adds nothing beyond that: it does not say that the heartbeat interval drives alert triggering, whether the heartbeat is created enabled, whether openWorldHint implies external notification delivery to the target (page/Slack/email), or what happens on repeated calls. For a mutation that will page humans, that is a real gap.

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 short sentence, front-loaded with the verb, so it is not bloated. But it wastes half its length on "from provided data" and leaves no room for the payload structure this nested schema actually needs.

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 input is a nested object with six required fields and enum constraints (interval_unit, notification_target_type), plus a boolean whose semantics affect alerting. A single generic sentence is inadequate; the description should at minimum explain the interval/unit pairing and the notification target requirement. Having an output schema excuses it from explaining return values, but nothing else.

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 reported at 0% for the single top-level `data` parameter, whose nested `attributes` object carries six required fields including `interval`, `interval_unit`, and `notification_target_id` that have no schema description at all. The description does not compensate — it never names a single field, unit convention, or the relationship between `interval` and `interval_unit`, leaving the most error-prone required fields undocumented anywhere.

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?

"Creates a new heartbeat" states a verb and resource, but "from provided data" is tautological filler that restates the input parameter rather than adding scope. It does not differentiate the tool from update_heartbeat or list_heartbeats beyond the implicit create/update/list verb pattern, so the agent learns nothing it could not infer from the tool name.

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

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

There is no guidance on when to use this tool versus update_heartbeat, get_heartbeat, or list_heartbeats, and no mention of prerequisites such as needing an existing notification target to reference. An agent must infer the create-vs-update distinction entirely from the naming convention.

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

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

Annotations already declare non-readOnly, non-idempotent, open-world, non-destructive, so the mutation/safety profile is covered structurally. The description adds nothing beyond that: no mention that all fields are optional, what happens when title is omitted (autogeneration), or what the response contains. It does not contradict 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?

A single front-loaded sentence with no waste. However, the size is achieved partly by omitting information rather than by compressing it, so it is not a 5.

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

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

An output schema exists so return values need no explanation, and annotations cover safety. But for a create tool with zero required parameters, the description should tell the agent that all fields are optional, that an incident is still created with no title, and what 'scoped' excludes (e.g., it cannot set status or assignee here).

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

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

Schema description coverage is 100% and each field carries its own description including title autogeneration and comma-separated ID formats. The description contributes no parameter meaning beyond the schema, which is the baseline 3 case.

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

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

States a specific verb and resource: create an incident. The phrase 'scoped set of fields' signals this is a limited-create endpoint vs update_incident, though the scope is not spelled out. An agent can tell it creates rather than updates.

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

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

No guidance on when to use this vs update_incident, or what to do when an incident already exists. 'For agent-driven workflows' is a vague hint, not a usage rule. Nothing about prerequisites or required IDs.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior, so the description only needed to add context such as validation rules or the custom-fields feature gate. It adds nothing: no mention that form_field_selections are silently ignored unless the org enables action-item custom fields, and no note that repeat calls create duplicates (idempotentHint=false).

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

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

A single short sentence is easy to scan, but "from provided data" is wasted space and the brevity here reflects under-specification rather than tight writing.

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 tool with a deeply nested JSON:API payload, ten-plus optional attribute groups (Jira linkage, assignees, custom fields), and no idempotency, the description omits nearly everything an agent needs to construct a valid call. The presence of an output schema and detailed nested property descriptions offset some of this, but the envelope and usage context are missing.

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

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

Schema description coverage is only 50%, and the undocumented half is the critical JSON:API `data` envelope with its fixed `type: incident_action_items` value. The description does not explain this envelope or the relationship between incident_id and the nested payload, so it fails to compensate for the coverage gap even though the nested attribute descriptions are rich.

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?

"Creates a new action item" names a specific verb and resource, but "from provided data" is pure filler and the description never anchors the action item to the parent incident, which is the defining characteristic versus siblings like update_incident_action_item or create_incident. It is barely more than the title restated.

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

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

There is no guidance on when to use this instead of update_incident_action_item or create_incident_event, and no stated prerequisite that the incident must already exist. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful lifecycle context (deprecation) but says nothing about write semantics such as duplicate-selection handling, validation failures, or whether the created selection is returned.

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

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

Two short sentences with the deprecation warning front-loaded, which is exactly the information an agent should see first. 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. However, for a deprecated mutation tool the most important omission is the migration path — which form field endpoint replaces it — leaving an agent without enough to avoid the wrong call.

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

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

Schema coverage is only 50%, and the description's only parameter-related content is the tautological 'from provided data'. It does not explain the incident_id scoping or that the nested attributes take their shape from the custom field's kind — that meaning lives only in the schema's inner field descriptions.

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

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

Names a specific verb and resource ('Creates a new incident custom field selection') and distinguishes itself from the sibling create_incident_form_field_selection by flagging itself as deprecated in favor of form field endpoints. The purpose would be a 5 if it named the exact replacement tool rather than the vague 'form field endpoints'.

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 deprecation banner is an explicit 'when not to use this' signal and points to an alternative family of endpoints. It stops short of naming the precise replacement sibling or any prerequisites, so routing still requires inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, and the description adds nothing on top of them. It does not say whether the event is appended to the incident timeline, whether visibility defaults are applied, what permissions are required, or what happens on repeated calls for a non-idempotent create.

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?

It is a single short sentence, so it is not bloated, but 'from provided data' is pure filler and no useful information is front-loaded. Brevity comes at the cost of substance rather than through efficiency.

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 mutating, non-idempotent create with a nested payload (and an output schema that covers return values), the description omits what an event represents, how visibility 'internal' vs 'external' affects exposure, and required preconditions. The output schema removes the need to document returns, but the input-side and behavioral gaps remain.

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 only 50%; incident_id and the nested event/visibility fields are documented in the schema, but the required `data` wrapper and its JSON:API-style `type: incident_events` discriminator are never explained. The phrase 'from provided data' is the description's only nod to the payload, so it does not compensate for the coverage gap.

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 restates the tool name almost verbatim ('Creates a new event' for 'Create Incident Event') and adds only the filler phrase 'from provided data'. It never explains what an incident event actually is (a timeline/summary entry on an incident) or how it differs from siblings like create_alert_event or create_incident_action_item.

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 guidance, no prerequisites (e.g., that incident_id must reference an existing incident), and no mention of alternatives such as create_incident_action_item or create_alert_event. The agent must infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it does not say what happens on a duplicate selection (non-idempotent), whether existing selections are replaced, or what the required payload shape means for the many selected_* arrays.

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

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

One front-loaded sentence with no padding, but "from provided data" is filler that conveys nothing. The brevity is closer to under-specification than to efficiency.

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?

An output schema exists so return values needn't be described, and annotations cover safety. But for a nested-payload creation tool whose input schema only half-documents its parameters and whose idempotency is false, the description leaves the agent without the kind-to-field mapping or the duplicate-handling behavior it needs to call this correctly.

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

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

Schema coverage is only 50% and the payload is a nested object, yet the description adds zero parameter meaning beyond "from provided data." It never explains that which selected_* arrays to populate depends on the custom field's kind (text uses value, select/multi_select uses the id arrays), which is the single most important semantic an agent needs here.

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

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

The description names a specific verb and resource ("Creates a new incident form field selection"), so the agent knows exactly which entity is being written. It does not, however, distinguish this from the adjacent siblings create_incident_custom_field_selection or update_incident_form_field_selection, which an agent could easily confuse with it.

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

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

There is no guidance on when to use this tool versus create_incident_custom_field_selection, nor any prerequisites such as the incident existing or the form field needing to be placed on the form. The phrase "from provided data" gives no routing 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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond this – no mention of validation behavior, what happens if a name already exists, or whether the operation can partially fail.

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 short sentence is concise and front-loaded, but it is under-specified rather than efficiently informative. It earns its brevity at the cost of being nearly content-free.

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 a complex nested request body, a required name field, and deprecated fields like slug, the definition should say more than "from provided data." The output schema covers returns, but the description leaves too much of the input contract and mutation semantics unexplained.

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 single top-level parameter "data" has no schema description (0% coverage) and the description's "from provided data" is tautological. The nested schema documents individual fields like name and color, but the description does not explain the required structure or that name is mandatory.

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?

It states a concrete verb and resource ("Creates a new incident_type"), which is clear enough, but there is no differentiation from siblings like create_incident, update_incident_type, or create_catalog_property. The phrase "from provided data" adds no distinguishing information.

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

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

There is no guidance on when to use this tool, no prerequisites, and no reference to alternatives such as update_incident_type or list_incident_types. The agent must infer everything from the name alone.

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 annotations already declare this as a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds no behavioral context beyond 'from provided data'—it does not mention side effects, required permissions, phone-number prerequisites, or what happens when the router is enabled.

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

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

The description is a single front-loaded sentence, which is structurally efficient. However, for a complex create operation with many nested configuration options, it is under-specified rather than appropriately concise.

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?

This is a complex creation tool with nested paging targets, phone routing options, and a referenced phone-number generation prerequisite. The description does not explain those dependencies, the creation context, or when this tool should be selected, leaving it incomplete despite having annotations and an output 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?

The description only says 'from provided data' and does not explain the single top-level data parameter or its required nested attributes. Although the nested schema contains field descriptions, the tool description itself adds no semantic meaning beyond the parameter name.

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

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

The description states a specific verb and resource: it creates a new Live Call Router. It is clear what the tool does, but it does not distinguish this create operation from sibling tools such as get_live_call_router, list_live_call_routers, or update_live_call_router.

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 guidance on when to use this tool versus alternatives or when not to use it. It also omits prerequisites, such as whether a phone number must first be generated before creating the router.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent with open-world behavior, so the basics of a write are covered. The description adds nothing beyond that — it says nothing about required auth level, what happens if a role with the same name exists (relevant given idempotentHint=false), or the fact that the slug is derived and ignored. For a mutation creating a permissions-bearing object, that is a real gap.

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 short sentence with no waste, so it is not bloated, but it is under-specified rather than concise — the trailing "from provided data" carries zero information and no useful detail replaces it.

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?

An output schema exists, so return values need not be described. However, this is a high-complexity nested create with ~28 permission fields, zero schema description coverage, and only minimal annotations, so the description should have covered the permission model and the derived-slug behavior; as written it leaves the agent under-equipped.

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?

There is a single top-level `data` wrapper (JSON:API-style with `type` and `attributes`), and the description never explains that structure or that `slug` is deprecated and ignored. Roughly two dozen `*_permissions` array fields carry no description at all, so the description needed to add meaning about the permission model and instead adds none.

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 pairs the concrete verb "Creates" with the specific resource "On-Call Role", which clearly separates it from sibling readers like get_on_call_role and list_on_call_roles. The qualifier "from provided data" is filler and the definition does not explicitly name update_on_call_role as the alternative, but the core purpose is unambiguous.

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

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

There is no guidance on when to use this versus update_on_call_role, list_on_call_roles, or get_on_call_role, and no prerequisites such as the admin-level permissions typically needed to mint a role. The agent must infer everything from the tool name alone.

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=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds nothing beyond the verb, not explaining what a shadow configuration is, whether the schedule must exist, or any side effects of creating one.

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

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

The description is a single front-loaded sentence with no repetition. However, "from provided data" is effectively filler and the extreme brevity leaves important context unstated.

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 create mutation with a required nested data object and schedule_id, the description does not explain required inputs, the meaning of shadowable_type, or expected effects. An output schema exists, so return values need not be described, but the creation context is substantially incomplete.

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 roughly 50%, with descriptions for schedule_id and most nested shadow attributes. The description adds no meaning beyond the schema and does not explain the nested data envelope or the shadowable_type/shadowable_id relationship, so it neither compensates for gaps nor harms understanding.

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 ("Creates") and resource ("on call shadow configuration"), so an agent can identify the operation. It does not explicitly distinguish itself from sibling create/update/list shadow tools, but the create intent 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?

There is no guidance on when to use this tool, what prerequisites are required, or how it differs from alternatives such as update_on_call_shadow or list_on_call_shadows. The only clue is the verb "Creates", leaving usage context entirely implicit.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false and openWorldHint=true; the description reinforces the read-only claim by promising a recommendation list plus a 'ready-to-use override payload' rather than a mutation. It adds real behavioral content the annotations do not: candidates are filtered by load, results are sorted lowest-load-first, and a top pick is pre-assembled. No auth, rate-limit, or empty-result behavior is described.

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

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

Four short sentences, front-loaded with the purpose and followed by the ranking rule and the return shape. No filler, though the phrase 'ready-to-use override payload' could have been spent naming the tool that consumes it.

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?

An output schema exists, so return values do not need spelling out, and the read-only safety profile is covered. However, a recommendation-only tool whose output is explicitly a payload omits the single most useful piece of context: which tool to call with that payload. The agent is left to infer the create_override_shift handoff.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including exclude_user_ids. The description adds conceptual context — that the date period and schedule drive the load calculation — but never references a parameter by name or clarifies how exclude_user_ids interacts with the load filter. 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: 'Recommend replacement responders for an override shift', then narrows the candidate pool to users in the same schedule rotation who are not heavily loaded. The critical disambiguation — that despite the 'create_' prefix this only recommends, returning a payload rather than writing anything — is conveyed. It stops short of naming create_override_shift as the sibling that actually performs the write.

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 scenario is implied clearly (you need a replacement for an override shift), but there is no explicit when-to-use vs when-not, and no alternative is named. Given siblings create_override_shift and check_responder_availability exist, the agent must infer the division of labor between 'recommend', 'check availability', and 'create'.

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

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

The description gives useful behavioral detail (overlap deletion/replacement, idempotency on identical user and time range), but it directly contradicts annotations: it claims the endpoint is idempotent while idempotentHint is false, and it says existing overlapping overrides are automatically deleted while destructiveHint is false. Per the rules, a description that contradicts annotations scores 1.

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

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

Three sentences, front-loaded with the core action and followed by the two important behavioral exceptions. No filler, though the idempotency sentence is somewhat long and would benefit from being separated from the overlap replacement behavior.

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

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

For a mutation tool with an output schema and annotations, the description covers overlap replacement and idempotency but misses key context: permission requirements, what exactly is replaced, and whether replacement is scoped to the same user or schedule. The annotation contradictions also reduce confidence in the stated behavior.

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

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

Schema description coverage is only 50%, and for a nested two-parameter request the description does not explain schedule_id, the data wrapper, or required attributes such as user_id, starts_at, and ends_at beyond incidental mentions of 'user' and 'start/end time'. It does not compensate for the low schema coverage.

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

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

States a specific verb and resource: 'Creates a new override shift from provided data.' Clear, but does not differentiate this from sibling tools like update_override_shift or list_override_shifts, so an agent must infer the boundary from the name alone.

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?

Implied usage is creation of an override shift, and overlap-replacement behavior is described, but there is no explicit when-to-use guidance versus update_override_shift, create_override_recommendation, or other schedule tools. An agent knows what the tool does but not clearly when it is preferred over alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say whether creation fails on duplicate titles, what permissions are needed, or what the response contains — a notable gap for a non-idempotent 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?

A single short sentence with no filler, so it is front-loaded and efficient. However, its brevity comes from under-specification rather than tight writing — the one clause present ('from provided data') is essentially empty.

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?

This is a mutation with a deeply nested payload, an output schema, and multiple write siblings; the description should at minimum outline the required envelope and mention that it is a non-idempotent create. Because the output schema exists, return-value explanation is not required, but payload expectations and sibling routing are missing.

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

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

Schema description coverage is reported at 0%, and the description does not compensate: it says only 'from provided data' and never mentions that the payload must contain a 'type' discriminator and an 'attributes' object with a required 'title'. The agent must open the schema to learn the envelope shape, and the description offers no hints about kind/content/external_url relationships.

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 verb and resource ('Creates a new playbook'), which is more than a bare tautology, but 'from provided data' adds no distinguishing information. It never differentiates this from the sibling write tools update_playbook or the read siblings get_playbook/list_playbooks, so the agent must infer the boundary from the name alone.

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

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

There is no guidance on when to call this versus update_playbook or get_playbook, and no prerequisites or context are given. The only implied usage is the obvious 'creating something new', which the name already conveys.

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, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavior beyond that: it says nothing about retry semantics for a non-idempotent create, required permissions, side effects such as attaching services/environments, or validation failures.

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 short sentence with no filler and the operation front-loaded, so it is not padded. However, brevity here comes from omission rather than efficiency, leaving only a tautological restatement of the title.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains missing is essential: what a pulse represents, the required shape of the nested payload, and any prerequisites or side effects for a non-idempotent, open-world create.

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 reported as 0% at the top level, and the single `data` parameter is a deeply nested JSON:API-style envelope (type/attributes with summary, refs, labels, timestamps, service_ids, environment_ids) whose purpose the description never explains. The phrase "provided data" is circular and leaves the agent to reverse-engineer the envelope from nested field descriptions alone.

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?

"Creates a new pulse" gives a clear verb and resource, but "pulse" is an undefined domain concept and "from provided data" adds nothing. It does not distinguish this from siblings such as list_pulses, get_pulse, or update_pulse beyond the implied write verb.

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

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

There is no guidance on when to create a pulse versus using another tool, no preconditions (e.g., whether an incident or service must already exist), and no mention of alternatives. The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond that—it does not explain what 'provided data' contains, what permissions are needed, or what happens on duplicate creation.

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?

It is a single short sentence with no redundant words, so it is concise and front-loaded. However, this is achieved through under-specification rather than useful compression—the sentence does not earn its place because it merely repeats the 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?

Given the nested schema, required copy_from parameter, and multiple matching-criteria options, the description is far too thin. It provides no guidance on required fields or what the tool returns, though an output schema exists so return values need not be explained. The input side is critically under-described.

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 single top-level parameter 'data' has no description in the schema or the tool description, and the stated schema description coverage is 0%. The phrase 'from provided data' gives no meaning about the required nested fields (e.g., name, copy_from, matching criteria). The description does not compensate for the coverage gap.

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 restates the tool name and title almost verbatim: 'Creates a new retrospective process from provided data.' It names a verb and resource, but 'from provided data' is filler that adds no discriminating information. It does not differentiate this create tool from the many sibling retrospective tools (get, list, update).

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites or required inputs such as copy_from, and no exclusions. The agent is left to infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the mutation/safety profile is covered structurally. The description adds nothing beyond that — no mention that repeated calls create duplicates (non-idempotent), no note on permission requirements, and no hint that several attribute flags are silently forced to false when slack_channel is absent (that logic lives only in the schema).

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

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

One short, front-loaded sentence, so there is no bloat — but "from provided data" is dead weight and the sentence is under-specified rather than efficient. Conciseness here comes at the cost of information rather than from discipline.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. However, for a tool taking a deeply nested payload with two required attributes and several conditional flags, the description omits nearly everything an agent would need before calling it, leaving the schema to carry the entire burden.

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 single top-level parameter "data" is an undocumented nested envelope, and the description only says "provided data", adding no meaning. The leaf properties do carry schema descriptions, but the description does nothing to help the agent understand the required type/attributes wrapper or the relationship between name and owner_user_id.

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?

"Creates a new schedule" gives a specific verb+resource, but "from provided data" is pure filler and nothing distinguishes it from siblings like update_schedule, create_schedule_rotation, or list_schedules. An agent knows the operation type but not the scope of what a schedule contains or what creating one requires.

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 update_schedule (existing schedule) or the rotation-creation tools that populate a schedule. No prerequisites (e.g., that an owner_user_id must exist) or sequencing guidance is given.

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

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

Annotations already declare it non-read-only, non-idempotent, non-destructive, and open-world, so the safety profile is partly covered. The description adds no behavior beyond that: no mention that retries will duplicate rotations (idempotentHint=false), that rotation members require a feature flag, that time_zone must match the schedule's, or any validation/rejection 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?

A single short sentence with no wasted clauses, but it is under-specified rather than efficient — nothing is front-loaded that an agent could not already read from the 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?

This is a nested create with an anyOf discriminator, a feature-gated members array, and cross-field time_zone constraints; the description covers none of it. The output schema excuse does not apply here because the gaps are on the input/behavioral side, not the return-value side.

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?

Only 2 top-level parameters but 50% schema description coverage, and the description contributes nothing — "from provided data" is filler. It does not explain the wrapper structure (type/attributes), the schedule_id requirement, or the anyOf branching in schedule_rotationable_attributes, which is the hardest part of the call to get right.

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?

"Creates a new schedule rotation" gives a clear verb and resource, but the rest ("from provided data") adds nothing and the sentence is essentially a restatement of the name/title. It does not distinguish this from siblings like update_schedule_rotation, list_schedule_rotations, or get_schedule_rotation, nor does it say what a rotation consists of.

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

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

There is no guidance on when to use this versus update_schedule_rotation or the schedule_rotation_active_day / schedule_rotation_user tools, and no mention of prerequisites (e.g., schedule nesting feature required for members). The agent must infer all routing from the name alone.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world, non-destructive write. The description adds nothing beyond them: it does not say what happens if an active day already exists for that rotation/day_name (notably relevant given idempotentHint=false), whether permissions are required, or what the created resource returns.

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?

It is a single short sentence with the verb and resource front-loaded, so it is not bloated. However, 'from provided data' is dead weight in an already minimal sentence, leaving the whole sentence with essentially one clause of content.

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?

This is a mutating tool with nested objects and an output schema, so the schema side is fine, but the description is incomplete: it does not explain the relationship to the parent rotation, duplicate-day behavior, or when to create versus update an active day. For a creation tool in a complex scheduling domain, that leaves meaningful gaps.

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 50%, so the description is expected to compensate, yet it only says 'from provided data' — zero information about schedule_rotation_id or the nested day_name/active_time_attributes payload. The schema itself documents the key fields, so an agent can still call it, but the description contributes no semantic value at all.

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 verb+resource pair ('Creates a new schedule rotation active day') is specific enough to identify the operation, but the trailing 'from provided data' is pure filler and adds nothing. There is no differentiation from nearby siblings such as create_schedule_rotation, create_schedule_rotation_user, or update_schedule_rotation, which an agent must choose between in the same domain.

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

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

The description offers no when-to-use guidance, no prerequisites (e.g., that the rotation must already exist), and no mention of the alternative siblings like create_schedule_rotation_user or list_schedule_rotation_active_days. The agent has to infer all routing decisions from the name alone.

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=false, idempotentHint=false, and openWorldHint=true, so the mutation and non-idempotency profile is covered structurally. The description adds nothing on top — no mention of duplicate-user handling, position collision behavior, or permission requirements, which matter given idempotentHint=false.

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

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

It is a single short sentence with no wasted clauses, so it is concise. But the brevity reflects under-specification rather than efficiency — the one phrase beyond the name ("from provided data") conveys no information.

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