NudgeBell

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral detail: it names exactly what is deleted, says nothing is archived, and confirms there is no undo from either the API or the dashboard. This goes well beyond the annotations and gives the agent a clear safety picture. No contradiction with 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 description is front-loaded with the destructive warning and deletion scope, then provides crisp usage guidance and a clear alternative. Every sentence contributes meaningful information; the length is justified by the irreversible nature of the operation.

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 strong annotations and no output schema, the description covers what is deleted, irreversibility, recovery impossibility, and exactly when to avoid it. No critical information needed 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?

There is only one parameter, reminder_id, and the input schema already describes it with 100% coverage. The description does not add parameter-specific semantics, but the baseline of 3 applies because the schema carries the full burden.

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

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

The description opens with 'DESTRUCTIVE AND IRREVERSIBLE' and states a specific verb and resource: 'Cancelling permanently DELETES the reminder, its escalation steps and its entire delivery history.' It clearly differentiates itself from pause_reminder, so an agent can distinguish this destructive tool from its sibling without ambiguity.

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 explicit when-to-use criteria ('only use this when the user explicitly says delete, cancel for good, or stop permanently'), concrete counterexamples ('not right now', 'skip today', 'hold off', 'I'm on holiday'), and routes uncertainty to pause_reminder. This is exemplary decision guidance.

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

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

Beyond the annotations (readOnly=false, idempotent=false), the description discloses that reminders fire from NudgeBell's own servers and survive agent/machine/conversation loss, that acknowledging any step cancels all remaining steps, and that recipient-selection attempts are rejected. These are high-value behavioral traits an agent cannot infer from annotations or schema alone.

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 dense but every sentence contributes: opening behavior, escalation-chain rules, acknowledgment semantics, and the no-recipient/timezone guardrails. The most important behavioral contract is front-loaded before lower-level constraints.

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 seven-parameter creation tool with rich schema descriptions, the text covers scheduling semantics, constraints, and edge cases (acknowledgment cancels remaining steps, no recipient, timezone fallback). It does not state the return shape, which matters slightly more because there is no output schema, but the omission is minor for an intuitive create operation.

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 every property, its constraints, defaults, and channel-specific behavior. The description adds useful global guardrails (no recipient, don't add steps) but no new parameter-level meaning, so the high-coverage baseline applies.

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

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

The description opens with a specific verb and object: 'Schedule a reminder that escalates the way the user set it and stops when they acknowledge.' It also clarifies the resource as a multi-step escalation chain, which naturally distinguishes it from sibling tools that cancel, list, pause, or retrieve reminders.

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

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

There is no explicit comparison such as 'to view reminders use get_reminder', but the creation intent is unmistakable and the description gives strong usage guardrails: build only requested steps, don't add a recipient because NudgeBell only contacts the account owner, and normally omit timezone. This gives clear context without formal exclusions.

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 read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations by explaining that contacts are 'the only places a reminder can ever be delivered,' and enumerates the data fields returned. This clarifies the semantic significance of the account data without contradicting 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 description is two sentences: the first states what the tool returns, the second states when to use it. Every phrase earns its place and the most decision-relevant information ('verified contacts', 'credit balance') appears first.

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

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

For a parameterless read with no output schema, the description enumerates the returned fields and provides a clear use case. The sibling tools are all reminder operations, so there is no missing information needed to select or invoke this tool 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?

The tool has zero parameters, so the schema fully documents the input surface. The description does not need to explain parameters; instead it focuses on the returned data, which is appropriate for a parameterless read.

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 clearly identifies the tool as reading the account's verified contacts, timezone, plan, credit balance, and active-reminder limit. The verb 'read' and the specific data fields distinguish it from the reminder-operation siblings, all of which target individual reminders rather than account state.

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 explicitly states when to call it: 'Read this first if you are unsure whether a phone call is possible or whether there are enough credits.' Since none of the sibling tools provides account-level information, there is no alternative to disambiguate; the guidance is unambiguous and actionable.

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, idempotentHint=true, and destructiveHint=false, so the description doesn't need to reiterate safety. The description adds value by clarifying the scope to the 'current occurrence' and listing content, which is useful behavioral context. However, it doesn't mention pagination or error cases, but for a single-item read with these annotations, 3 is fair.

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

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

A single, well-structured sentence that front-loads the core purpose and enumerates specific content. No wasted words, and it reads naturally. Excellent structure for a retrieval tool.

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

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

For a simple read tool with one parameter, annotations covering safety, and no output schema, the description is complete. It tells the agent what content to expect (steps, message, timing, occurrence status) and is sufficient for correct invocation. Nothing essential 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 schema has 100% coverage for the only parameter, reminder_id, so description need not explain it. The description adds no new parameter-specific detail, but that's acceptable given the schema coverage. Baseline of 3 is correct because the description doesn't need to compensate for any gaps.

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 clearly states the tool retrieves the full detail of a single reminder, specifically enumerating the content (steps, message, timing, and occurrence status). This distinguishes it from list_reminders (listing) and get_reminder_status (status only), even though siblings are not named. The verb 'Read' and the resource 'one reminder in full' are precise.

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 implies usage for retrieving complete details of a reminder, and the title reinforces 'in full' versus status summaries. It does not explicitly state when not to use it (e.g., for status only, use get_reminder_status), but the sibling names and the word 'full' provide clear context. Lacks explicit alternatives, so a 4 is appropriate.

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, and the description adds meaningful behavioral context: acknowledgment is read-only and can only be set by the human through a specific action. This goes beyond the annotations by explaining the mutability boundary and the mechanism for acknowledgment.

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 compact and front-loaded: the first sentence states the core behavior and output, the second gives the use cases, and the third clarifies a key constraint. No redundant wording or filler is present.

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

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

For a simple status-checking tool with two parameters, the description covers the domain, the read-only constraint, and the status vocabulary. It does not detail the exact return shape, but since no output schema exists, a bit more formatting detail would be helpful; overall it is still adequate.

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 reminder_id and step sufficiently. The description does not add significant new parameter semantics beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description clearly identifies the tool as reporting per-step delivery and acknowledgment status for a live occurrence, naming the exact statuses it returns. This distinguishes it from siblings like get_reminder and list_reminders by focusing on delivery/acknowledgment state rather than reminder content or collection.

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 explicitly states the tool answers 'did that reminder go out?' and 'have they responded yet?', which are concrete use cases. It does not name alternative tools or explicit when-not-to-use conditions, so it stops short of full routing guidance.

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

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

Annotations already establish this as read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by disclosing what the response contains: next trigger time, escalation-chain progress, and acknowledgment state. It does not mention ordering or pagination, but the safety profile is fully covered by annotations.

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

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

Two tight sentences: the first states scope and output, the second gives real user intents. No filler or repeated schema content, and the most important purpose information is front-loaded.

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

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

Given the tool has no output schema, the description compensates by naming the key returned fields and practical use cases. It is complete enough for an agent to select and invoke the tool, though sort order and empty-result behavior are not addressed.

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 limit and status already have clear descriptions, so the description adds little parameter-level meaning. The baseline of 3 applies because the schema carries the parameter documentation weight.

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 uses a specific verb and resource: 'List the account's reminders' and names the concrete output fields returned. It clearly differs from sibling tools like get_reminder by positioning itself as the multi-item list action and even mentions finding an id before cancel/pause, so an agent can distinguish it from the single-item getters.

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 explicitly says when to use it: to answer 'what am I being reminded about?' or to find a reminder id before cancelling or pausing. It gives clear context but does not explicitly state when not to use it or name alternatives such as get_reminder_status, so it stops just short of a 5.

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

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

The annotations already indicate non-read-only (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds valuable behavioral context: it explains the effect (cancels pending steps, keeps history), reversibility, and how to resume (via dashboard). The only gap is not detailing the exact return behavior or if any side effects beyond pending steps occur, but the annotations cover the core safety profile, so the description adds sufficient 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?

The description is concise: three sentences that each serve a purpose. The first sentence states the action and effect, the second mentions reversibility and how, and the third gives usage prioritization. It is well-structured and front-loaded with the most important information about the default usage.

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

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

The tool has a simple single-parameter schema with full coverage, annotations capturing key traits, and no output schema. The description fully explains the action, the difference from the main sibling, and reversibility. No missing information prevents an agent from calling 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?

The schema description coverage is 100%, meaning the parameter 'reminder_id' is already documented in the schema. The description does not add extra detail about the parameter format or semantics beyond what the schema provides, so the baseline of 3 is appropriate as the description doesn't need to compensate.

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 clearly states the verb ('Stop'), the resource ('a reminder'), and the scope ('cancel its pending steps') while distinguishing it from cancel_reminder by mentioning what is preserved (reminder and history). This differentiates it from the sibling tool and leaves no ambiguity about its primary function.

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 provides when-to-use guidance by stating it is the 'DEFAULT way to stop a reminder' and names the alternative (cancel_reminder) with a clear condition ('unless the user explicitly asked to delete it or stop it permanently'). This gives direct decision criteria, which is excellent usage guidance.

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