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?

Goes well past the annotations: it explains exactly what is cleared (Lock Screen and Notification Center on every device), that notification history is retained (softening the destructiveHint=true framing), that iOS/iPadOS clearing is asynchronous, and that a success result means the dismissal was recorded rather than propagated. It also discloses the pre-1.17.0 fallback behavior and idempotency, all of which an agent could not infer 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?

The core action and identifier source are front-loaded, then device behavior, result semantics, and edge cases follow in a sensible order. Four paragraphs is on the long side, and the legacy app-version caveat is the one passage an agent is least likely to need.

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 mutation with an output schema already available, the description covers the remaining gaps an agent would care about: asynchronous propagation, what a success result actually guarantees, idempotency, and the irreversibility of the dismissal. 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?

Schema coverage is 100% and the single parameter already documents that it is the notification_id returned when the notification was sent. The description reinforces the provenance but adds no format, validation, or edge-case 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?

Opens with a specific verb and resource ('Dismiss a Push Notification that was already sent') and ties the identifier to its origin, send_push_notification. That makes it immediately distinguishable from the sibling write tools send_push_notification 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 a concrete when-to-use condition ('when a notification no longer needs attention, for example after a question you asked was answered somewhere else') and states that repeat calls are safe. It implies but never explicitly names replace_push_notification as the alternative for updating content, since 'a dismissed notification cannot be replaced' only hints at 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 mark this as destructive and open-world, but the description adds important context beyond them: it removes the stream key, ending remotely consumes the device's ActivityKit push budget, and repeatedly ending and recreating a stream to refresh it should be avoided. These are exactly the operational caveats an agent needs before invoking a destructive lifecycle operation.

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

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

The description is front-loaded with the action and scope, then immediately routes to the alternative and adds the lifecycle/budget caveat. Every sentence contributes useful selection or safety 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?

Given the destructive annotations, rich 7-parameter schema, and presence of an output schema, the description supplies the remaining decision-critical context: what gets removed, when to prefer the sibling pause operation, and the push-budget consequence of repeated end/recreate cycles.

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 detailed parameter semantics are already supplied by the input schema. The description reinforces the stability and lifecycle meaning of stream_key, but it does not add materially beyond the schema for the other six parameters, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: ending the current Live Activity for a managed stream and removing its stream key. It clearly distinguishes the operation from sibling alternatives such as pause_live_activity_stream and set_live_activity_stream, so an agent can select 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?

It gives explicit when-to-use guidance: use when tracked work is finished, whereas pausing is for temporarily stopping updates while keeping the key. It also clarifies lifecycle behavior by noting that a later set_live_activity_stream call with the same key starts a new Live 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 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 establish readOnly, non-destructive, closed-world behavior, and the description adds real context on top: the error mode ("Returns a not found error for an unknown ID") and the scoping to sent notifications on this account. It does not cover auth requirements or rate limits, so it falls short of the richest disclosure, but it adds genuine behavior beyond the annotations.

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

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

Three sentences, front-loaded with purpose, then usage, then error behavior — a sensible ordering with no filler. The long enumeration of returned fields (content, delivery status, device count, errors, Tags, metadata, replacement count, dismissal time) is largely redundant given an output schema exists, which costs it a point.

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 an output schema, everything an agent needs is present: what it returns, when to call it, the alternative for browsing, and what happens on a bad ID. 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 coverage is 100% and the single public_id parameter is already fully documented, including its origin in list_push_notifications and equivalence to the send_push_notification notification_id. The description only restates "by its public ID" and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get one sent Push Notification from this account by its public ID") and then enumerates what comes back, so the agent knows exactly what it is fetching. It explicitly distinguishes itself from list_push_notifications, which is the nearest 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?

Gives both the positive case ("inspect a specific notification, for example before calling replace_push_notification") and the exclusion with a named alternative ("To browse or filter history, use list_push_notifications"). The routing decision is fully resolved without opening either schema.

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

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

Annotations already declare readOnlyHint=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?

Beyond the read-only annotations, it discloses ordering and tie-breaking, pagination continuation via meta.next_offset, stopping condition, and that results can change between requests. This is unusually rich behavioral context for a list endpoint.

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

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

The description is front-loaded with purpose and routing guidance, then gives ordering and pagination mechanics. Every sentence contributes either selection guidance or invocation semantics, 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?

Given the read-only annotations, full schema coverage, and an output schema, the description supplies all the additional context an agent needs: sibling routing, ordering, defaults, pagination flow, and data freshness. 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 coverage is 100%, so the schema already documents all five parameters well. The description adds useful pagination semantics and repeats key defaults and the maximum limit, but it does not add much detail for tags, status, or tag_mode beyond what the schema provides.

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

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

The description gives a specific verb and resource ('List Live Activities') and states account scope, ordering, and returned fields. It also explicitly distinguishes this tool from get_live_activity and the stream tools, so an agent can select it without inspecting 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?

It provides explicit when-to-use guidance: review recent activity or find an activity_id. It also names the alternative for a single known activity and the stream tools for changing a running activity, covering the relevant sibling routes.

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

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

Annotations already establish readOnly/non-destructive/non-open-world, so the description is free to add value beyond them - and it does: it discloses the sort tie-breaker ('Equal creation times use descending ID order'), the pagination loop protocol (continue via meta.next_offset with the same filters, stop when null), and the important caveat that 'Results can change between requests', implying offset paging over a live set. These are operational traits an agent cannot infer 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?

Roughly four tight sentences, front-loaded with the verb, resource and ordering, then use cases, then pagination mechanics. No filler or restatement of the title; every clause conveys a fact an agent needs.

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

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

An output schema exists, so return shape needn't be described, and the description still covers the pieces it must: eligibility scope (whole account), ordering and tie-break, defaults and maximums, and the full pagination termination rule. Nothing required to call this list 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?

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond by spelling out the continuation contract between 'offset' and 'meta.next_offset' (same filters preserved, terminate on null) and by stating defaults and the 100 cap in one place, though it repeats values already present in the schema and adds nothing specific about tags/tag_mode semantics.

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

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

States a specific verb and resource ('List Push Notification history for the account') plus the ordering ('newest first'), and explicitly names the sibling get_push_notification as the single-item alternative. An agent can distinguish it from list_channels, list_tags, and get_push_notification 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 three concrete use cases (review what was sent, find a notification's public_id, filter by Tags) and an explicit routing rule: for one known notification use get_push_notification. That is a when-to-use plus a named alternative, not an implied one.

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?

Beyond the mutation/openWorld annotations, the description discloses real behavioral constraints: media cannot be combined with actions, actions cap at 4, blocked/unsafe schemes are rejected, custom schemes have no web fallback, webhook actions require HTTPS, and iOS version gates apply to some features. It also explains that the response returns notification_id, which is the key behavioral fact for follow-up calls.

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

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

Well structured and front-loaded: purpose, then targeting, then redirection/actions, then media constraint, then follow-up lifecycle, then rendering and urgency. It is long for a 14-parameter tool and some content duplicates schema descriptions (media/actions incompatibility, redirection scheme examples), but the prose is paragraph-scoped by topic and skimmable rather than rambling.

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 high-parameter, open-world mutation tool with nested objects, the description covers the gaps that matter: action payload shape, scheme policy, exclusivity constraints, urgency semantics, and what to do with the returned notification_id. Since an output schema exists, it correctly avoids restating the full response shape.

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 earns an increment by explaining interaction rules the schema states only per-field (media vs. actions exclusivity), the intent behind interruption_level values, and concrete worked examples of action objects with open_url and webhook shapes. The icon explanation ('next to a smaller ActivitySmith app icon; iOS may hide the subtitle') adds rendering context not present in the schema.

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

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

The opening sentence states a specific verb and resource ('Send an ActivitySmith Push Notification to this account') and immediately adds the scoping option ('optionally target channel slugs'). Later it names the sibling tools this one feeds into (replace_push_notification, dismiss_push_notification), so an agent can place it in the notification lifecycle without opening other 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?

Clear routing guidance: capture notification_id and pass it to replace_push_notification when an incident resolves, or dismiss_push_notification to clear it. It also gives a decision rule for interruption_level ('use time-sensitive only for things the user must see now') and for target_channel_slugs (omit for account-wide default). It stops short of stating when this tool is the wrong choice versus unrelated siblings like set_live_activity_stream or request_approval.

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?

Beyond the annotations, the description discloses critical behavior: each non-noop operation may send a remote ActivityKit push, iOS budget and throttling can affect delivery even after APNs accepts the request, success means APNs acceptance rather than device display, and changing content_state.type or target channels rotates to a new Live Activity and consumes another push-to-start operation. These are exactly the non-obvious operational and side-effect details an agent needs before calling a mutating remote-push 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?

The description is long but front-loads the highest-risk operational constraint, the remote delivery budget, before lifecycle details, supported types, presentation capabilities, actions, and examples. Most sentences earn their place because they prevent incorrect update frequency or unnecessary push-to-start consumption. It could still be tightened, especially where examples repeat details already present in the schema, but the structure is purposeful rather than bloated.

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

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

For a complex 8-parameter tool with nested content_state and action objects, the description covers lifecycle semantics, update cadence, noop behavior, type rotation, push budgets, supported content_state types, icon and badge compatibility, action and secondary_action behavior, and concrete examples. An output schema exists, so the description need not explain return values. The definition is complete enough for an agent to call the tool correctly and avoid the main failure modes.

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

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

Schema description coverage is 100%, so the schema already carries substantial parameter documentation, including stream_key stability, content_state types, icons, badges, actions, metadata, and target channels. The description still adds value beyond the schema by explaining the lifecycle semantics of stream_key, noop on identical payloads, rotation when type or target channels change, and practical timer guidance to send timer fields once and let the device render locally. It adds meaningful non-schema semantics, though much of the type/icon/badge/action field guidance is repeated from the schema.

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

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

The description starts with a specific verb and resource: 'Create or update a managed Live Activity stream by stable stream_key.' It clearly distinguishes the upsert behavior from a pure create or pure update operation, and the stable-key concept is central throughout. An agent can identify this as the Live Activity stream mutation/update tool 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?

The description gives unusually concrete when-to-use guidance: one stable stream_key per real-world activity, update on meaningful user-visible state changes, send event-driven transitions promptly, and avoid polling, heartbeats, per-second ticks, unchanged values, and churn. It also explains that repeating the same payload returns 'noop' and that retrying a successful call will not force display. It does not explicitly route the agent to sibling tools such as pause_live_activity_stream, resume_live_activity_stream, or end_live_activity_stream, so it is strong on operational usage but not fully complete on alternative selection.

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 it is a non-destructive write; the description adds real substance: value overwrite semantics, ~15-minute refresh latency, auto-creation with inferred format, that deleted-metric keys are not recreated, and billing errors on trial/plan limits.

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

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

Purpose and usage are front-loaded in the first two sentences with no filler, but the remainder is one dense run-on covering creation, formats, deletion, billing, and return value that could be split for scannability.

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 3-parameter mutation tool with an output schema, the description covers everything an agent needs: idempotent-style overwrite behavior, latency expectations, creation side effects, prerequisites, and failure modes (billing, deleted keys). Return-value explanation is redundant but harmless.

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

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

Schema coverage is 100% so the baseline is 3, and the description adds some meaning: that the key drives creation, that the value replaces the prior value, and how numeric/text values are treated. Format-parsing details and the timestamp default are already in the schema, so the gain is modest rather than large.

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 (record/set) and resource (Lock Screen Widget metric value) keyed by metric key, and distinguishes itself from create_widget_metric and update_widget_metric by describing auto-creation and value replacement explicitly.

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

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

Gives explicit triggers ('whenever the tracked number or text changes'), an exclusion with an alternative ('for an immediate alert, use send_push_notification'), and a prerequisite routing rule ('call create_widget_metric first for a currency, percent, or unit format or a custom label').

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 readOnly=false, destructive=false, openWorld=true; the description adds genuinely new behavior — the update is silent (no Push Notification), the value replaces rather than increments so the call is idempotent, and 0 clears the badge. It does not cover what happens with an invalid channel slug or what the response confirms, so it stops 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?

Front-loads the core purpose, then alternatives, then semantics, then the optional parameter — a logical order with no filler. The only mild redundancy is 'Send 0 to clear the badge', which the schema already states, but it earns its place as a usage hint.

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 silence, idempotency, clearing, and the sibling alternative — everything needed to call a two-parameter mutation correctly. Minor room remains around channel-slug resolution and failure behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented, including 'Send 0 to clear it'. The description adds the important replacement-versus-increment semantics for badge, but only restates the optional channel slug targeting without explaining slug resolution or default scope beyond what the schema says.

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 ('Set the number shown on the ActivitySmith App Icon Badge') plus the target platform ('iPhone or iPad'), with concrete examples of what the number represents. It is immediately distinguishable from send_push_notification, which is named explicitly.

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

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

Explicitly routes the agent: use send_push_notification 'when the user should be alerted', or that tool's badge field 'to set both at once', versus this tool for silent badge-only updates. The when-not and the alternative are both spelled out, 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 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description usefully adds the 45-second timeout, early return on decision, and the fact that a pending result is not an error but a retry signal. It does not state what happens when the wait times out versus when the approval expires, though the output schema likely carries that.

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

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

Three short sentences, front-loaded with the duration and the early-return behavior, with the retry instruction last. No redundant restatement of the tool name or 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 one-parameter blocking tool with an output schema, the description covers duration, early return, and the retry pattern, which is what an agent needs to invoke it in a loop correctly. Only the enumeration of possible approval states is absent, and that is reasonably delegated 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 coverage is 100% and the schema already explains that approval_id comes from request_approval. The description adds the reuse semantics ('call this tool again with the same ID'), which is mild extra value but not new syntax or format detail; baseline 3 is appropriate.

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

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

States a specific verb and resource plus a concrete bound: wait up to 45 seconds for a pending approval, returning early when the user decides. An agent understands this is a blocking poll. It does not explicitly distinguish itself from get_approval or request_approval, so sibling differentiation is left to inference.

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

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

Gives a clear operational rule: if the result is still pending, call again with the same ID, which defines the intended polling loop. It stops short of saying when to prefer this over get_approval (e.g., non-blocking check) or what to do once a terminal decision arrives.

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