ActivitySmith

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

Annotations only declare the safety profile (readOnly=false, destructive=true, idempotent=true, openWorld=true). The description adds substantial context beyond that: the iPhone Live Activity updates, the user loses the ability to approve/reject, any wait_for_approval call returns the cancelled state, and non-pending requests are returned unchanged. This is rich side-effect disclosure that annotations alone could not convey.

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

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

Front-loaded with the core action, then side effects, then the non-pending caveat, then the retry exclusion. Every sentence carries distinct information, though the closing 'Returns the approval's resulting state' is mildly redundant given an output schema exists.

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

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

For a one-parameter mutation with an output schema and full annotation coverage, the description covers purpose, side effects, edge cases (non-pending), and the retry anti-pattern. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single approval_id parameter is already documented as coming from request_approval. The description adds no additional syntax or format detail beyond the schema, so the baseline of 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 ('Cancel a pending approval request') and immediately scopes it to 'pending' requests, which distinguishes it from request_approval, get_approval, and wait_for_approval. An agent can tell exactly what this tool does without opening any schema.

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

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

Gives explicit when-to-use ('no longer needed... agent changed plans or the operation already happened'), explicit when-not ('Do not cancel to retry; use wait_for_approval to keep waiting'), and names the sibling alternative. It also clarifies the no-op case for already-decided/timed-out/cancelled approvals, removing ambiguity about retry behavior.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the details that actually matter for a secret-issuing tool: the secret is returned exactly once, keys survive disconnection of this MCP session, revocation happens in the web app, and a specific permission ("Manage API keys") is required via an approval screen. It also states a safe-handling procedure (secret manager or git-ignored env file, never commit or print in chat).

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 sentences, front-loaded with purpose, then secret handling, then lifecycle, then the scope caveat and permission. No sentence is padding — each carries a fact an agent would otherwise get wrong (printing the secret in chat, assuming the key dies with the session).

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-shape explanation is not required. What remains — auth/permission requirements, one-time secret exposure, persistence beyond the session, and where to store the value — is all covered, which is exactly the risk surface for a credential-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?

Schema coverage is 100%, so the baseline is 3. The description still earns above baseline by linking scope_mode "channels" to channel_slugs with a decision rule (subset of recipients) that the schema's field-level text does not state as explicitly, and by surfacing the name/permission context an agent needs before filling in the parameters.

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 opens with a specific verb and resource ("Create an ActivitySmith API key") and immediately scopes the audience for that key (CI job, server, script). This distinguishes it cleanly from siblings like rename_api_key, delete_api_key, and list_api_keys without needing the schema.

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

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

It gives a concrete conditional rule for the risky parameter: "Use scope_mode 'channels' with channel_slugs only when the key should reach a subset of recipients." That is real when/when-not guidance. It stops short of naming sibling alternatives (e.g., list_api_keys for existing keys), so it falls just under 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, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the created channel is empty, creation fails on duplicate slug, and the response contains public_id and slug. It does not discuss permission/auth requirements, which is the only notable 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?

Front-loaded with the verb and a definition, then the decision rule, then the follow-up. Most sentences earn their place, though the closing line about return values ('Returns the channel's public_id and slug') is partly redundant given an output schema exists.

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

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

For a single-parameter creation tool this is fully sufficient: it defines the concept, gives the create-or-not decision rule, names the follow-up tools to populate the channel, states the duplicate-slug failure mode, and notes the return payload. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the slug's normalization rules (lowercasing, dash substitution, 64-char truncation) are already fully documented in the schema. The description only implies the slug is the targeting handle via 'target_channel_slugs', adding no new syntax or constraint detail. Baseline 3 applies.

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

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

States a specific verb+resource ('Create a channel') and then defines what a channel actually is — a named recipient group targetable via target_channel_slugs and scopeable by API keys. This conceptual grounding lets an agent distinguish it from siblings like create_api_key or create_widget_metric even though the name alone is generic.

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 states when NOT to use it ('Channels are optional; without them, deliveries go to every device') and when to use it ('Only create one when the user wants to route deliveries to some people or devices'). It also names the follow-up tools (set_channel_users, set_channel_devices) needed to make the channel useful.

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

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

Annotations only establish that this is a non-read-only, non-destructive, closed-world write. The description adds what the annotations cannot: the duplicate-key failure mode, the postcondition that the new metric has no value and nothing appears on the Lock Screen until a widget is added, and that the response includes public_id. That is meaningful behavioral context beyond structured fields.

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

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

Front-loaded with the purpose, then routing, then semantics, then failure mode and return value in descending priority. Five sentences where none is filler, though 'Create each metric once' partially duplicates the later 'Fails if the key already exists,' a small overlap.

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 6-parameter create tool with full enum/default coverage, an output schema, and sibling routing, the description covers what the schema cannot: lifecycle, idempotency failure, and side-effect timing. Nothing needed to invoke it correctly is missing, and return values are additionally summarized despite the 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?

Schema description coverage is 100% with enums and defaults, so the baseline is 3; the description earns an extra point by tying the key parameter to its cross-tool contract ('using the same key' shared with set_widget_metric_value) and by identifying label/format as the mutable fields via update_widget_metric.

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

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

States a specific verb+resource ('Create a Lock Screen Widget metric') and then defines the concept concretely ('a named value ... shown in an ActivitySmith widget on their iPhone or iPad Lock Screen'). It explicitly distinguishes itself from the two closest siblings, set_widget_metric_value and update_widget_metric, so an agent can pick correctly without opening the schema.

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

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

Gives explicit routing: create each metric once, then use set_widget_metric_value with the same key to send values, and use update_widget_metric to change label or format. It also states the creation precondition (fails if the key already exists), which is the when-not condition.

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

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

Annotations already flag destructiveHint=true, but the description goes further with what the agent cannot learn from them: 'Anything still using it starts failing immediately', 'cannot be undone', and the 'Manage API keys' permission granted on the approval screen. That is exactly the extra context a destructive call needs.

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, irreversibility and blast radius front-loaded, then the guardrail, then the permission prerequisite. No sentence is redundant and nothing is buried.

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

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

An output schema exists so return values need no explanation, and the description covers the remaining gaps an agent needs: irreversibility, downstream breakage, the confirmation step, and the required permission. Nothing material is missing for a single-parameter destructive 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 single public_id parameter and its 16-character constraint are already documented, including its 'from list_api_keys' provenance. The description's only added signal is the instruction to confirm the key name with the user, which is a procedural caution rather than parameter semantics, so the baseline 3 applies.

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

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

States a specific verb ('Permanently delete') and resource ('ActivitySmith API key') in the first four words, which cleanly separates it from create_api_key, rename_api_key and list_api_keys without needing to name them.

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 precondition ('Confirm the key name with the user before deleting a key you did not create in this session') and a permission requirement, which tells the agent when the call is legitimate. It stops short of naming an alternative such as rename_api_key when the intent is a modification rather than removal.

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?

Beyond the destructiveHint=true annotation, the description details the exact blast radius: disappearance from list_channels, broken slug targeting, lost user/device assignments, API-key delivery stopping, and the reassurance that users/devices themselves survive. It also states irreversibility through MCP and the return payload — context annotations alone do not provide.

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 delete action is front-loaded, followed by consequences, non-consequences, the irreversibility warning, and the return value. Every sentence carries distinct information about scope or safety, with no filler.

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

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

With destructiveHint and no-readOnly annotations covering the safety profile, 100% schema coverage, and an output schema present, the description fills the remaining gaps: consequence scope, irreversibility, and confirmation requirement. An agent has everything needed to invoke 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 100%, so both slug and public_id (including the 'provide one or the other, both must match' rule) are already fully documented in the schema. The description adds only an incidental note that the slug stops working for targeting, not new parameter 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?

The description opens with a specific verb+resource ('Delete a channel') and immediately enumerates concrete effects (removal from list_channels, slug stops resolving, assignments stop applying), leaving no ambiguity about what operation this is. Though it never names a sibling explicitly, 'delete_channel' is unmistakable among update_channel/create_channel.

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 one real usage guideline: 'This cannot be undone through MCP, so confirm with the user first.' However it never states when to delete versus update/deprecate a channel, nor any preconditions beyond confirmation, so usage is only partially covered.

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?

Although annotations already flag destructiveHint=true, the description goes well beyond them by enumerating concrete downstream effects: removal from list_widget_metrics, set_widget_metric_value failing with 'Metric not found', and widgets silently stopping updates. It also states the change is irreversible via MCP and describes the return value.

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

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

Three sentences, front-loaded with the action, then consequences, then the alternative. Every sentence carries distinct information and none is padding.

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

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

For a single-parameter destructive tool with an output schema and destructive annotations, this covers effects, irreversibility, the alternative tool, and the return value. Nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100% and the single parameter's description already tells the agent where to obtain public_id (list_widget_metrics or create_widget_metric). The description adds no further syntax or format detail, which is the expected baseline when the schema does the work.

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 ('Delete a Lock Screen Widget metric') and immediately distinguishes it from update_widget_metric. An agent can tell it apart from the other delete_* siblings (delete_api_key, delete_channel) by the resource named.

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 routes the agent explicitly: 'to rename a metric or change its format, use update_widget_metric instead,' and warns it cannot be undone through MCP. It gives a clear alternative for the adjacent need but stops short of describing prerequisites (e.g., permissions) or any other when-not conditions.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, but the description adds real behavioral context beyond them: the stream key is removed, a later set_live_activity_stream with the same key starts a fresh Activity, and ending remotely consumes the device's ActivityKit push budget. That budget/lifecycle detail is exactly the kind of non-obvious consequence an agent needs.

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 action, then routing to the alternative, then a caution. Every sentence carries distinct decision-relevant information with no filler.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description fills the remaining gaps: lifecycle semantics, the key-removal consequence, and push-budget cost.

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 tags, alert, action, metadata, content_state, and stream_key thoroughly. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('End the current Live Activity for a managed stream') plus the concrete side effect of removing the stream key. It is immediately distinguishable from siblings like get_live_activity, list_live_activities, and pause_live_activity_stream.

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

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

Gives an explicit when-to-use condition ('when the tracked work is finished') and names the alternative for the opposite case ('to stop updates temporarily and keep the key, use pause_live_activity_stream'). It even adds a when-not-to-use warning against repeatedly ending and recreating a stream.

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/idempotent/non-destructive, and the description adds real behavioral context beyond them: the call is non-blocking ('without waiting'), it returns the decision time when available, and it discloses the error behavior ('Returns Approval not found for an unknown ID'). This is materially more than the safety profile the annotations provide.

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 tight sentences, front-loaded with the core action and return states, then usage, then the alternative, then the error case. No sentence is redundant against the schema or annotations.

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 needn't be restated, annotations cover the safety profile, and the description still supplies the non-blocking semantics, the routing to wait_for_approval, and the not-found error. An agent has everything needed 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 description coverage is 100% and the single approval_id parameter is fully documented in the schema (its provenance from request_approval), so the schema carries the burden. The prose adds no format, syntax, or lifecycle detail about the ID beyond what structured data already states — baseline 3.

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

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

Names a specific verb+resource ('Get the current state of an approval request') and enumerates the exact states returned (pending, approved, rejected, timed_out, cancelled). It also explicitly distinguishes itself from the sibling wait_for_approval, so an agent can select correctly without opening either schema.

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

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

Gives explicit when-to-use cases ('status checks', 'recover after losing track of a request') and an explicit when-not/alternative ('To block until the user decides, use wait_for_approval instead'). Nothing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description goes further by explaining the delivery semantics (a delivery reaches every active device of each assigned user plus individually assigned devices), which is genuine behavioral context beyond the annotations. It does not mention auth requirements or rate limits, but for a read tool that is acceptable.

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 action, then usage guidance, then return shape. Three sentences and every one carries weight; the delivery-semantics sentence is the most verbose but still informative rather than filler.

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

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

An output schema exists, so the description's return-value narration is technically redundant, yet nothing an agent needs is missing: purpose, when-to-use relative to the set_channel_* siblings, and the resource relationships are all covered.

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

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

Schema description coverage is 100%, and the schema already documents slug and public_id including the 'provide one, or both must match' rule. The description adds no syntax or format detail for the parameters beyond what the schema provides, so baseline 3 applies.

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

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

Specific verb (Get) plus resource (one channel) and explicit scope (with the users and individual devices assigned to it). It is easily distinguished from list_channels (plural, all channels) and the set_channel_* mutators named in the text.

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 states when to call it: 'Call this before set_channel_users or set_channel_devices, which replace the whole list, so you can keep existing assignments.' It names the alternatives and the condition that selects this tool over them, leaving nothing 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it enumerates the returned content and discloses the not-found error for an unknown ID.

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

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

Three tightly scoped sentences with the core action, returned contents, read-only guidance, and error behavior. Purpose is front-loaded and 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?

Given the simple single-ID schema, existing output schema, and read-only annotations, the description covers everything an agent needs: ID provenance, return contents, alternative tools for mutation, and error behavior. No material 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 100%, and the schema already documents that activity_id comes from list_live_activities. The description repeats that source but adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('one Live Activity') scoped to this account and identified by ID. It also names the source of the ID (list_live_activities) and distinguishes the operation from the stream-based update/end tools.

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

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

Explicitly says to use this for retrieval by ID and directs update/end operations to the stream tools. It also tells the agent where to obtain the required ID, making both the trigger and the alternative path clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuine behavioral context beyond that: the not-found error for an unknown ID and the fact that the record reflects a sent notification's delivery outcome (status, device count, errors). It stops short of describing pagination or failure modes beyond the 404-equivalent.

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, then usage routing, then the error case — every sentence carries information. Mild redundancy: the enumerated return fields partially duplicate what the existing output schema already defines.

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

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

For a single-parameter read tool with a full output schema and read-only annotations, the description covers purpose, sibling routing, and the one non-obvious behavior (unknown-ID error). Nothing an agent needs to select or call this correctly is missing.

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

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

Schema description coverage is 100% and the single parameter's provenance is fully documented in the schema (public_id from list, or the notification_id from send). The description repeats 'by its public ID' but adds no format, syntax, or constraint beyond the schema, so the baseline of 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?

Specific verb+resource ('Get one sent Push Notification ... by its public ID') with an explicit enumeration of the returned content (delivery status, device count, errors, Tags, metadata, replacement count). It is clearly distinguishable from siblings list_push_notifications and replace_push_notification.

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 both a use case ('inspect a specific notification, for example before calling replace_push_notification') and an explicit alternative for the other case ('To browse or filter history, use list_push_notifications'). This is exactly the when/when-not routing an agent needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful non-annotation context: the result ordering (active first, then recently updated/created, with stable tie-breakers) and the volatility note 'Results can change between requests.' It does not mention auth requirements or rate limits, keeping it from a 5.

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

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

The description is front-loaded with the tool's purpose and returned fields, then adds usage, ordering, pagination, and volatility notes. It is efficient overall, though the 'Defaults: limit 100, offset 0; maximum limit 100' sentence partially duplicates schema information, which slightly reduces the value density.

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, the description need not explain return values. It covers the practical needs for a paginated list tool: what is listed, why to use it, how results are ordered, how to paginate, and that results can shift between requests. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, and include_inactive fully. The description repeats defaults and the maximum limit, and mirrors the schema's guidance to continue with meta.next_offset, adding little beyond the structured fields. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'List the iPhones and iPads paired to this account,' and enumerates the returned fields. It clearly distinguishes this tool from siblings like list_account_users and list_channels by scoping to paired devices.

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 to use it to find device_id values for set_channel_devices, giving a concrete downstream consumer. It does not state when not to use it or name alternative list tools, so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: deterministic ordering (owners, then admins, then members, each by email) and that all users are returned at once with no pagination. Only the absence of any auth/permission note keeps it from a 5.

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

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

Three sentences, each load-bearing: what it returns, when to use it and what to forward, and the ordering/pagination contract. The most decision-relevant fact (purpose) is front-loaded with no filler.

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

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

With an output schema present, return-value structure need not be explained, and the description still covers ordering, completeness of results, and intended downstream use. Nothing an agent needs to call this no-arg read tool correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The only 'pass their emails' remark describes what to send to sibling tools, not an argument of this one, so it neither helps nor hurts.

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

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

States a specific verb ('List') and resource ('people in this ActivitySmith account') and enumerates the returned fields (email, name, role, active device count), which cleanly separates it from list_account_devices and the other list_* siblings. An agent can identify the tool's scope without opening the schema.

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

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

Gives explicit downstream usage: 'Use it to choose users for set_channel_users, or device owners for set_channel_devices; pass their emails.' It names the two consuming siblings and tells the agent what value to hand them, which is exactly the routing guidance needed.

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?

Beyond the readOnly/destructive annotations, the description discloses concrete behavioral facts: results are ordered newest first, the exact fields returned, that secret key values are never returned, and that a specific 'Manage API keys' permission granted via the approval screen is required. This is meaningful auth and data-exposure context an agent cannot get from 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?

Four short sentences, front-loaded with purpose and ordering, then returns and permission needs. No filler or 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?

For a zero-parameter list tool with an output schema present, the description is fully sufficient: scope, ordering, returned fields, permission requirements, and a security caveat are all covered. Nothing needed to invoke it correctly is missing.

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

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

The tool takes no parameters, so there is nothing for the description to clarify beyond the schema. The baseline for a zero-parameter tool applies.

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

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

States a specific verb and resource ('List API keys') plus scope ('for the authorized ActivitySmith account') and ordering ('newest first'). An agent can distinguish it at a glance from siblings like create_api_key, delete_api_key, and rename_api_key.

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 account-level scope and permission requirement imply when the tool applies, but there is no explicit guidance on when to prefer it over other listing tools (e.g., list_account_users, list_tags) or any stated exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns all channels at once, ordered newest first, with no pagination – an important disclosure for a list tool that agents would otherwise assume paginates.

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, each earning its place: what it returns, what a channel is/does, and which siblings depend on its output. The scoping fact (no pagination, newest first) is placed at the end where it reads as a caveat rather than burying the purpose.

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 the description still names the salient return fields, so the agent knows both the shape and the semantics. No parameters, no destructive behavior, and full sibling routing make this complete for a zero-arg list tool.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics for the description to compensate for. The mention of target_channel_slugs refers to sibling tools rather than this tool's inputs, which is clarifying but not 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?

Specific verb+resource ('List the account's channels') plus the exact payload fields returned (slug, public_id, assigned user/device counts). It also explains what a channel is, and implicitly contrasts with the single-channel get_channel sibling.

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 states the use case: find the slug or public_id required by get_channel, update_channel, delete_channel, set_channel_users, and set_channel_devices. This routes the agent through the dependency chain rather than leaving it to infer which sibling to call 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuine behavior: the tie-break rule for equal creation times, pagination continuation via meta.next_offset, and the volatility caveat "Results can change between requests." It stops short of describing auth or filter-combination internals, but goes well 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?

Front-loaded and mostly efficient, but "Equal creation times use descending ID order." is duplicated verbatim, wasting a sentence. That redundancy is a real structural flaw in an otherwise well-ordered description.

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 profile, so the description only needs to cover scoping, ordering, filtering and pagination — which it does. An agent has everything required 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 description coverage is 100%, so the schema already documents all five parameters including defaults and the tag_mode enum, making 3 the baseline. The description restates defaults (limit 50, offset 0, max 100) and adds only the continuation instruction "Continue with meta.next_offset and the same filters; stop when it is null," which is marginal added value.

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

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

Specific verb+resource ("List Live Activities sent from this account") with scope, ordering ("newest first") and returned fields declared. It is clearly distinguishable from get_live_activity and the stream 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?

Explicitly states two use cases (review recent activity, find an activity_id) and routes the agent to alternatives by condition: get_live_activity for one known activity, set_live_activity_stream and other stream tools for changing a running activity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: stable tie-breaking by descending ID, pagination continuation semantics, and the caveat that 'Results can change between requests' (non-snapshot reads). It does not cover rate limits or result-size characteristics, keeping it short of a 5.

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

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

Mostly dense and front-loaded, but the sentence 'Equal creation times use descending ID order.' is duplicated verbatim, which is wasted text and suggests an editing defect. The rest earns its place, so this is a modest rather than severe deduction.

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 description still supplies the one output detail an agent must act on: driving the next page from meta.next_offset. For a read-only, filter-and-paginate list tool, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so tags, limit, offset and tag_mode are already fully documented in the schema. The description only restates defaults (limit 50, offset 0, max 100) that the schema already carries, adding no new parameter meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('List Push Notification history for the account') plus ordering ('newest first'), and explicitly distinguishes itself from the sibling get_push_notification for single-notification lookups. An agent can route correctly without opening either schema.

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

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

Gives concrete use cases (review what was sent, find a public_id, filter by Tags), names the alternative for the single-notification case, and spells out the pagination loop: continue with meta.next_offset using the same filters and stop when it is null.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: alphabetical sort by slug then ID, pagination continuation via meta.next_offset, and the caveat that 'Results can change between requests'. No auth or rate-limit detail, hence not a 5.

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

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

Front-loaded with purpose, then usage, then sorting/pagination details — every sentence is informative. Slight redundancy in repeating the limit/offset defaults already present in the schema keeps it from 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-value explanation is unnecessary, and the description covers everything else an agent needs: purpose, sibling routing, sort order, pagination loop, and stability caveat. Nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%, so limit, offset, and query are already fully documented in the schema. The description largely restates the defaults (limit 50, offset 0, maximum 100) without adding syntax or semantics beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('List the account's Tags') plus the returned payload shape ('with how many Push Notifications and Live Activities use each one'). It explicitly names the sibling tools it complements (list_push_notifications, list_live_activities), so an agent can distinguish it from other list_* tools without opening schemas.

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

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

Gives concrete when-to-use conditions: finding Tag slugs for the tags filter of list_push_notifications and list_live_activities, or reusing existing Tags when sending. The alternatives are named directly and the purpose for calling is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds non-obvious behavior on top: deleted metrics are excluded, results are returned in full without pagination, and ordering is newest-first. It stops short of noting account/permission scope, but the added behavioral context is substantial.

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

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

Three tight sentences, front-loaded with what is returned before the routing guidance. Every sentence carries distinct information: contents, usage, and result-set 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?

An output schema exists, so return values need not be explained, yet the description still flags the non-paginated full result set and exclusion of deleted metrics. For a zero-parameter list tool with rich annotations, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description does not need to compensate for any schema 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?

States a specific verb ('List') and resource ('Lock Screen Widget metric'), plus the ordering ('newest first') and the fields returned (key, label, format, latest value). This cleanly separates it from siblings like list_channels or list_api_keys without opening any schema.

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

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

Gives explicit when-to-use guidance tied to three named alternatives: find public_id for update_widget_metric/delete_widget_metric, find key for set_widget_metric_value, or read the current value before changing it. Nothing 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?

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description discloses concrete side effects: a remote end may be sent, the device's ActivityKit push budget is consumed, and subsequent set_live_activity_stream calls are suppressed. It also names the recovery path (resume_live_activity_stream), which the annotations cannot convey.

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

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

Three sentences ordered as action, cautionary guidance, then state consequence. The scoping and budget warning is front-loaded and no sentence is redundant or padding.

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

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

For a destructive, budget-consuming operation with two documented parameters and an output schema, the description covers the important unknowns: what gets destroyed, what it costs, and what state results. Return-value detail is correctly left to the 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?

Schema description coverage is 100%, so stream_key and content_state are already documented, including key reuse and budget warnings in the schema itself. The description adds no parameter-level syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (pause) and resource (Live Activity stream) and clarifies the composite effect: ending the current activity when needed. It also implicitly distinguishes itself from set_live_activity_stream and resume_live_activity_stream by name, so an agent can separate it from its closest siblings without opening a schema.

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

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

Explicit when/when-not guidance: 'use it only for a genuine pause, not as update-rate control,' plus the consequence that future set_live_activity_stream calls are ignored until resume_live_activity_stream is called. This routes the agent to the correct sibling for rate changes and explains the state transition required to undo it.

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-destructive, idempotent, closed-world behavior, so the bar is lower. The description usefully adds that the secret and access are preserved and that an approval-screen permission is required, which annotations cannot express; it stops short of richer detail like failure modes or rename conflicts.

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

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

Three short sentences, front-loaded with the action, followed by scope and prerequisite. No filler or repetition 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?

An output schema exists, annotations cover the safety profile, and the schema fully documents both params. The description supplies the two things structured fields cannot: the permission prerequisite and the guarantee that the secret/access are untouched. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and both parameters carry their own descriptions (including the example name and the pointer to list_api_keys for public_id), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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 ("Rename an ActivitySmith API key") and immediately bounds the effect ("The key secret and its access do not change"), which separates it from the create/delete/list API key siblings in the same family.

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

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

Gives clear usage context: it names the required "Manage API keys" permission and what is unaffected by the operation, so the agent knows this is a metadata-only rename. It does not, however, explicitly contrast with list_api_keys or delete_api_key, and there is no update_api_key sibling to route away from.

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

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

With destructiveHint=true already declared, the description goes well beyond it: it explains what is destroyed (the old notification's slot on Lock Screen and Notification Center), how it is delivered (silently, no sound, no screen wake), the merge-vs-replace rule (content fields fully replaced; omitted metadata and tags keep stored values), and that recipients and history are preserved/updated in place.

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 purpose and identity, then delivery behavior, then the replace/merge rule — a sensible precedence order. Slightly long at four paragraphs, with mild restatement in the second paragraph, but every paragraph carries distinct information.

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

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

For a 12-parameter mutation tool with an output schema, the description covers the destructive effect, silent delivery, content-replacement semantics, recipient behavior, and history handling. Nothing an agent needs to invoke it safely is missing, and return values are covered by the 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?

Schema description coverage is 100%, so the baseline is 3, but the description supplies cross-parameter semantics the schema does not: which fields are wholesale replaced versus which retain stored values, and that the notification targets the original recipients. The tags/metadata omit-vs-clear behavior is largely duplicated from the schema, so it stops short of 5.

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 ('Replace a Push Notification that was already sent') and immediately binds it to the identifier source ('notification_id returned by send_push_notification'), which separates it cleanly from the send and get siblings. An agent can distinguish it without opening the schema.

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

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

Gives a concrete when-to-use scenario ('update a Push Notification you already sent, for example when an incident you alerted on is resolved') and ties it to the send_push_notification workflow that produces the id. It never states the inverse case (use send_push_notification for a brand-new notification), but the context is strong enough to infer.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) by disclosing the 45-second wait, the delivery fallback chain, and that the approval ID survives client timeouts and reconnects. The instruction to re-poll rather than re-request implicitly conveys the non-idempotent behavior that a repeat call would open a second request.

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 what/how/when are front-loaded in the first two sentences, and the remaining sentences carry concrete directives rather than filler. Slightly dense with five distinct instructions packed together, but every sentence earns its place.

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

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

An output schema exists, so return values need not be documented, and the description still usefully references the returned approval ID and pending state. For a 9-parameter tool with nested objects and a 45-second blocking wait, it covers polling, labels, and execution_context well; minor gaps remain on target_channel_slugs and appearance usage.

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 operating meaning: it explains when to choose action-specific approve_label/reject_label values ('Send/Cancel', 'Deploy/Hold') and when to include execution_context plus the most relevant scope. It does not address target_channel_slugs or appearance, which the schema handles 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?

States a specific verb and resource ('Ask the ActivitySmith account owner for a decision') and immediately explains the mechanism (Live Activity, Push Notification fallback, 45-second wait). An agent can distinguish this from siblings like wait_for_approval, get_approval, and cancel_approval without opening any schema.

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

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

Explicitly routes the follow-up case: 'If the result is pending, call wait_for_approval repeatedly with the returned approval ID.' It also gives conditional guidance for labels and for including execution_context/scope when approving a concrete command. It stops short of an explicit when-not-to-use rule (e.g., when to prefer send_push_notification or cancel_approval instead).

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 cover the safety profile (not read-only, not destructive, not open-world), so the bar is lower. The description adds real behavioral context beyond them: this tool itself does not restart the stream, and the subsequent set_live_activity_stream call consumes push-to-start budget, which is a cost/limit the agent should know about.

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

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

Two sentences, zero waste, with the scope qualifier and the downstream consequence each getting exactly one sentence. Front-loaded with the core action.

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 carry the safety profile. The description supplies the state precondition and the follow-up cost, but does not say what happens if the stream is not paused (an error/validation case) or whether any permissions are 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?

There is a single parameter with 100% schema description coverage, and that schema text already explains key stability and the push-to-start budget rationale. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline of 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 (resume) and resource (Live Activity stream), qualified by 'genuinely paused managed' to define the exact state being acted on. This cleanly separates it from pause_live_activity_stream, end_live_activity_stream, and set_live_activity_stream in the sibling list.

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

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

The phrase 'genuinely paused' implies the precondition for calling it, and the description explains the follow-up action (the next set_live_activity_stream call restarts the stream). It stops short of explicitly naming an alternative or stating what to do if the stream is not paused.

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 and openWorldHint=true, and the description does not contradict them. It adds genuine operational context beyond the annotations: no web fallback for custom schemes, unsafe and internal schemes blocked, iOS version/build floors (1.13.4 build 2, 1.16.0), and that the result carries a notification_id usable with replace_push_notification. Some of this restates schema property text, which keeps it from a 5.

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

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

The first sentence front-loads the purpose well, but the body is a long undifferentiated block and several paragraphs (redirection URL rules, media/actions mutual exclusion, icon rendering) substantially repeat the corresponding schema property descriptions. The action example block earns its place; the redundancy with structured fields 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?

For a 14-parameter tool with nested objects, one enum, and a 100%-covered schema, the description covers the hard parts: platform requirements, blocked schemes, option mutual exclusions, and the notification_id handoff to replace_push_notification. An output schema exists, so return values need not be explained, and nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, so 3 is the baseline; the description earns a point by supplying concrete, correctly-shaped action examples (open_url with a GitHub URL, a shortcuts:// scheme, and a webhook with method and JSON body) that show how the untyped 'actions' array items should be constructed. That is meaningfully more than the schema conveys, though the remaining 13 parameters get nothing extra.

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 ('Send an ActivitySmith Push Notification to this account') plus the optional targeting scope ('Optionally target channel slugs'). It also names the sibling that continues the workflow ('Pass it to replace_push_notification to update this notification later'), so an agent can distinguish it from replace_push_notification and list_push_notifications without opening a schema.

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

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

Gives conditional guidance on option selection: 'use time-sensitive only for things the user must see now', 'media can be combined with redirection, but media cannot be combined with actions', and routes follow-up updates to replace_push_notification. It does not state when to prefer this tool over siblings like list_push_notifications or get_push_notification, but for a creation tool the operative 'when' is largely covered.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds the exact replacement semantics the hints cannot: devices left out are removed, sending an empty list removes them all, and user assignments are preserved. This is the critical behavioral detail an agent needs before calling a full-replacement 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?

Front-loaded with the replacement purpose, then the sibling distinction, then the add-one-device procedure. Every sentence carries operational weight, though the closing line about return values is mildly redundant given the output schema exists.

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

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

For a destructive full-replacement mutation with an output schema present, the description covers purpose, alternative routing, replacement/removal semantics, and ID sourcing. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the schema already documents slug/public_id/devices and their sub-fields (baseline 3). The description adds a genuine validation constraint beyond the schema — 'Each device must belong to the given account user' — which tells the agent a mismatched device will fail, justifying a modest bump.

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 (Replace) and resource (full list of individually assigned devices in a channel), and immediately scopes it against the sibling set_channel_users. An agent can distinguish this from the user-assignment tool without reading either schema.

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

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

Explicitly names the alternative (set_channel_users) and the condition selecting this tool instead, explains the procedure for the common 'add one device' case (call get_channel first, resend existing plus new), and points to list_account_devices for valid device IDs. When-to-use, when-not, and prerequisites are all covered.

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 flag destructive=true and idempotent=true, but the description goes further by spelling out exactly what is destroyed (users omitted from the list are removed; an empty list removes all) and what is preserved (individually assigned devices from set_channel_devices). It also discloses the return payload, which annotations cannot convey.

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

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

Front-loaded with the replacement semantics, then prerequisites, then the add-one-user workflow. Dense and information-bearing, though the closing sentence about return values is slightly redundant given an output schema exists.

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

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

For a destructive, full-replacement mutation with zero required parameters, it covers the destructive scope, the empty-list edge case, the surviving device assignments, the required lookup tools, and the response. Nothing needed to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that an empty/omitted user list wipes all assignments and that the two user fields are combined into one logical set, plus the constraint that emails must belong to the account.

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 ('Replace the full list of users assigned to a channel') and immediately frames it as a full-replacement operation, which distinguishes it from sibling set_channel_devices (explicitly named) and update_channel.

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 explicit when-to-use guidance: to add a single user, call get_channel first and send existing users plus the new one. It names the alternative (set_channel_devices) and clarifies that device-level assignments survive, and states the prerequisite that users must belong to the account via list_account_users.

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?

Goes far beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false). It discloses APNs remote delivery budgets, device-dependent push-to-start throttling, noop-on-identical-payload behavior, rotation to a new Live Activity when type/channels change, and the crucial caveat that success means APNs accepted the push, not that the device displayed it.

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 purpose, then budget semantics, then lifecycle mechanics, then type enumeration and examples. Well organized, but the seven content-type and three action JSON examples are lengthy and partially duplicate what the schema already documents, which dilutes the density somewhat.

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, high-blast-radius mutation tool with nested objects, this covers lifecycle, budget behavior, payload stability, action surfaces, and type compatibility. An output schema exists, so return values need not be described, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: which content_state.type maps to which use case, icon/badge compatibility per type, action vs secondary_action shapes and their supported Live Activity types, and why stream_key must stay stable. The inline examples also clarify the nested content_state structure beyond the terse schema property 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?

Opens with a specific verb+resource+key: 'Create or update a managed Live Activity stream by stable stream_key.' It immediately distinguishes itself from the legacy start/update/end id workflow, so an agent can tell which path to take without opening a schema.

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

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

Rich when-to-use and when-not guidance: send updates on meaningful user-visible state changes, avoid sustained polling/heartbeats/per-second ticks, coalesce redundant changes, and don't retry a successful call. It does not, however, route the agent to the obvious siblings pause_live_activity_stream / resume_live_activity_stream / end_live_activity_stream for those lifecycle transitions.

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 context beyond the annotations: replacement semantics ('the value replaces the previous one'), ~15-minute propagation latency, explicit non-instant behavior, billing semantics ('counts as a billable metric update' with a billing error path), and the returned payload. This is exactly the operational detail an agent needs for a write tool.

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

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

Front-loaded with purpose and tightly organized: purpose, trigger, replacement/latency, alternative, prerequisites, billing, return. It runs long for a single paragraph, but nearly every sentence carries actionable information, so almost 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?

Given a write tool with an output schema, the description covers everything else an agent needs: prerequisites, latency expectations, an alternative for the urgency case, billing failure behavior, and confirmation that the updated metric is returned. No meaningful gap remains.

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 key, value, and timestamp are already well documented in the schema, including the number-vs-string value rules and the timestamp default. The description reinforces the key identification but adds no parsing or format detail beyond the schema, so baseline 3 applies.

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

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

States a precise verb and resource: 'Record the latest value of a Lock Screen Widget metric, identified by its key.' The framing (set/record a value, not create or update the metric itself) clearly distinguishes it from create_widget_metric and update_widget_metric.

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 says when to use it ('whenever the tracked number or text changes'), names the alternative for the immediate case ('for an immediate alert, use send_push_notification'), and points to prerequisites (list_widget_metrics, create_widget_metric). Both the trigger condition and the sibling routing are spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered, yet the description adds real value: it discloses the update is silent (no push notification), that the value replaces rather than increments (idempotent, safe to repeat), and that 0 clears the badge. It stops short of mentioning auth requirements or rate limits, but the added behavioral context is strong.

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

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

Front-loads the core action and resource, then layers in the alternative-tool routing, the clearing rule, the replace-not-add semantics, and targeting. Every sentence carries distinct information and the closing instruction on how to phrase results is useful rather than filler.

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

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

With an output schema present, return values need not be explained. Given only two parameters and full schema coverage, the description covers purpose, alternative-tool routing, edge cases (0 clears, replacement semantics), and scoping, so nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description's notes on Send 0 to clear and optional channel slugs largely restate what the schema already says, adding no syntax or format detail beyond it, which fits the baseline 3.

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

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

States a specific verb (set) and resource (App Icon Badge number) with concrete examples of what the count represents. It explicitly distinguishes itself from send_push_notification, so an agent can pick the right tool without opening either schema.

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

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

Gives explicit when-to-use routing: this tool for silent badge updates, send_push_notification when the user should be alerted, and the badge field of that tool to do both at once. Also documents the Send 0 to clear case, leaving little 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive context beyond them: what is preserved (assigned users, devices, API key scopes), what breaks (scripts/SDK calls/agents targeting the old slug stop reaching the channel), and the failure condition (new slug already taken). This is exactly the kind of behavioral 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?

Purpose is front-loaded, and each of the five sentences carries distinct information (scope, preservation, consequence, param patterns, failure, return). It is dense but not padded; slightly long, which keeps it from 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?

For a destructive mutation with full annotation coverage and an output schema, the description supplies the caveats an agent needs before invoking: preservation of attachments, breakage of old-slug senders, the failure mode, and the two valid parameter shapes. Nothing material is missing.

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

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

Schema description coverage is 100%, and the schema itself documents the convoluted dual-mode slug semantics. The description restates the two identification patterns ('public_id or current_slug ... as slug' vs. 'current slug as slug and new name as new_slug') without adding syntax or normalization detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Rename a channel by changing its slug') that immediately distinguishes it from siblings like rename_api_key, create_channel, or delete_channel. The exact mutation mechanics are stated, not implied.

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 clearly states when this applies and adds an explicit caution ('confirm with the user first') plus a concrete consequence for downstream senders. It does not name an alternative sibling (e.g., delete_channel vs. this rename), so it falls short of the explicit alternatives criterion for 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 flag destructive and idempotent, but the description goes well beyond them: full-replace semantics, the concrete breakage caused by a new key (scripts, SDK calls, agents), the latest-value purge when switching string/numeric formats, the ~15-minute refresh delay, and the duplicate-key failure. This is exactly the destructive-behavior context annotations cannot convey.

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

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

Front-loads the operation, then the destructive mechanics, then routing, then side effects and failure modes. Every sentence carries distinct information with no padding.

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

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

For a destructive, multi-param mutation tool this is complete: it covers replace semantics, recovery via list_widget_metrics, sibling routing, side effects, timing, and failure conditions, and an output schema plus the closing 'Returns the updated metric' handles the return value.

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 cross-field semantics the schema does not: that required fields must carry current values or they are silently dropped, and that key changes break downstream consumers. It does not restate format/currency_code interlock details, which the schema already 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+resource ('Change an existing Lock Screen Widget metric's definition') and enumerates the mutable fields (key, label, format, currency, unit). It explicitly names the sibling it is not (set_widget_metric_value) and distinguishes recording a value from editing the definition.

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: use set_widget_metric_value to record a value, and pull current values from list_widget_metrics before saving. It also states the pre-condition (all fields replaced) that determines whether the agent must first fetch existing state.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the 45-second cap, the immediate-wake mechanism ('wakes immediately through Redis when the user acts'), and the retry contract, all of which an agent needs to use a long-poll correctly. The retry guidance is consistent with idempotentHint=true.

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

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

Three short sentences, front-loaded with the action and its bound, followed by the mechanism and the retry rule. No filler or restatement of 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?

The description covers the blocking duration, wake behavior, and retry semantics, and an output schema exists so return values need not be explained. Nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema coverage is 100% and the schema already explains that approval_id comes from request_approval. The description adds the operationally important detail that retries must reuse the same ID, which the schema does not convey. With only one well-documented parameter, this is a modest but real addition.

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+resource ('wait ... for a pending approval'), the exact bound ('up to 45 seconds'), and implicitly distinguishes itself from the polling sibling get_approval via 'without polling the database'. An agent can tell what this does and how it differs from the other approval tools.

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

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

It gives a clear usage context (waiting on a pending approval) and an explicit follow-up rule: 'If the result remains pending, call this tool again with the same ID.' It gestures at the alternative ('without polling the database') but never names get_approval or states when not to use this tool.

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