Reflecto

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

The description goes well beyond the annotations by explaining that the server does not store reminders, the call is fire-and-forget, and unknown or already-fired reminders are silently ignored. This concretely explains the idempotentHint and openWorldHint annotations and defines error behavior.

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

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

Two tight sentences. The primary action is front-loaded and the essential caveat follows in the second sentence without any filler.

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

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

For a single-parameter tool with a documented parameter and an output schema, the description covers what the tool does, how cancellation behaves, and what to expect with invalid ids. Nothing essential is missing for correct invocation.

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

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

The schema already documents reminder_id as the id returned by remind_me, so the baseline is 3. The description adds meaningful parameter behavior: an invalid or already-fired reminder_id is silently tolerated, which helps agents predict outcomes and avoid over-thinking errors.

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 action (Cancel) against a specific resource (previously scheduled reminder) identified by reminder_id. This clearly differentiates it from sibling remind_me, which schedules 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?

Clear context: use this to cancel a reminder that was created earlier. It does not name alternative tools or explicit when-not conditions, but the fire-and-forget caveat tells agents that invalid or expired ids will not produce errors, which meaningfully shapes when this tool 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?

The description discloses important behaviors beyond the annotations: server-side waiting up to wait_seconds, early return on user response, and the three possible return states. It also explains the default and maximum wait durations, which is exactly the kind of runtime behavior an agent needs to know. Annotations already signal read-only/idempotent/non-destructive, and the description enriches that with polling semantics.

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

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

The description is a single information-dense paragraph with no filler. It front-loads the core purpose, then packs in the wait behavior, looping guidance, and return-state semantics in a logical order. 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?

Given the two parameters, a blocking wait, and three return states, the description covers all essential behavioral context an agent needs to call the tool confidently. The output schema exists and the description also summarizes the return states, making the tool's expected behavior fully specified.

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 input schema documents wait_seconds but leaves request_id essentially bare beyond being a required string. The description compensates by making wait_seconds meaningful ('waits up to wait_seconds', default 20s, max 45s) and by tying the request to 'a pending request_approval.' It does not explicitly say the request_id is the value returned by request_approval, but the intended relationship is clear.

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: 'Poll for the user's answer to a pending request_approval.' This clearly distinguishes the tool from its sibling request_approval by framing it as the polling counterpart. The return states (pending, answered, expired) further pin down exactly what the tool observes.

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 clear operational guidance: call it back-to-back in a loop and do not add your own delay, because each call waits server-side and returns as soon as the user answers. It does not explicitly state when to use an alternative tool, but the connection to request_approval is clear enough via context.

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

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

The description goes beyond annotations by disclosing the fire-and-forget nature, noting the server cannot confirm the phone rang, only that the request was sent. This is critical behavioral context not captured in 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 concise, front-loads the key action, and adds necessary caveats in a structured way. Every sentence provides useful information without redundancy.

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 parameters and a simple action, the description fully covers its purpose, usage, and limitations. The output schema and annotations cover the rest, making this complete.

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

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

The tool has no parameters, and the schema coverage is 100% (vacuously). The description adds context about the behavior but doesn't need to explain parameters since none exist.

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

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

The description clearly states the tool's action: ringing the phone at full volume for up to 60 seconds, even on silent or Do Not Disturb. It provides specific details about the behavior and scope, making it easy to understand what the tool does.

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 use this tool: when the user asks to locate or ring their phone. It also implicitly indicates it is not for other device-locating tasks, and the fire-and-forget nature sets expectations about limits.

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, and destructiveHint, but the description adds valuable behavioral context beyond them: reading does not consume items, items repeat until expiry, and a lost response loses nothing. It also reinforces the closed-world scope consistent with openWorldHint false. This is exactly the kind of transparency that helps an agent predict side effects.

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

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

The description is three purposeful sentences with no filler. It front-loads the core purpose, then adds exclusions, and closes with pagination guidance. 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?

Given an output schema and rich annotations, the description is fully complete for invocation: it defines the item scope, excludes unrelated phone data, explains non-destructive repeated reads, and explains pagination with the cursor. Nothing an agent needs 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 parameter names, ranges, and defaults are already documented. The description adds practical meaning to `since` by explaining that returning the cursor yields only new items. This goes beyond the schema's 'Opaque cursor from a previous call' and justifies a score above the baseline.

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: 'Read items the user deliberately shared from their phone to you' via 'Share to Agents'. It actively excludes text messages, notifications, and other phone data, making the tool's scope unmistakable. This clearly distinguishes it from siblings like check_reply or find_my_phone.

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 clear context on what to use it for and explicitly what not to use it for: 'This does NOT read their text messages, their notifications, or anything else on the phone.' It also explains cursor reuse by instructing the agent to pass the returned cursor back as `since`. It does not name a sibling alternative, but the exclusions are strong enough to guide 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 already mark this as read-only and idempotent, but the description adds valuable nuance beyond that: a phone counts as reachable with a live push registration even when asleep or off, statusReportedAt is the reliable recency field, and lastSeenAt is coarse for phones. It also clarifies it never returns message or notification content.

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?

Every sentence earns its place: scope, reachability, recency guidance, safety, and usage routing are each a separate needed piece. The description is longer than minimal but wastes no words and front-loads the core 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?

For a zero-parameter read-only tool with an output schema, the description covers all important operational caveats: reachability semantics, recency field choice, and deviceId/label handling. An agent has enough to invoke it correctly and act on the results.

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 are no parameters, so the schema leaves nothing to explain. The description still adds relevant semantics around output identifiers—deviceId versus label—which indirectly helps correct downstream use, keeping this above the baseline.

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: 'List the user's own paired Reflecto devices... and whether each is reachable.' It clearly differentiates this tool from siblings like send_notification by scoping it to device enumeration and status, not sending or locating.

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 states when to use this tool: 'Call this before send_notification when you need to pick a specific device.' It also provides a concrete usage warning—pass the deviceId, not the label, because repeated labels deliver to all—which prevents a common mistake.

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 are thin (readOnly=false, destructive=false), so the description carries the behavioral burden — and it delivers: the alarm is inexact to preserve battery, delivery is best-effort, and a phone that never receives the setup message never arms the reminder. These failure-mode and timing disclosures go far beyond anything the annotations express.

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 in the first sentence, and each subsequent sentence earns its place: when to use, parameter units/range, timing inexactness, delivery failure mode, and return-value routing. At roughly 110 words it is not minimal, but the density of operational caveats justifies the length.

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 2-param tool with an output schema, nothing material is missing. The description covers trigger phrase, parameter constraints, timing guarantees, the delivery failure mode, and how the return value is consumed. An agent can invoke this tool correctly and set expectations appropriately without any further research.

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?

Even with 100% schema coverage, the description adds the crucial semantic that `at` is an absolute Unix timestamp in SECONDS within 60 seconds to 365 days from now. The 'from now' relative constraint and seconds-units clarification prevent real invocation bugs that the schema's bare integer bounds cannot convey.

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

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

Opens with a specific verb+resource: 'Schedule a notification to appear on the user's phone at a specific future time.' This cleanly separates it from siblings like send_notification (immediate delivery) and cancel_reminder (cancellation), and the closing sentence explicitly ties the return value to cancel_reminder.

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 use: 'Use this when the user asks to be reminded of something later.' It also names the complementary sibling (cancel_reminder). However, it never explicitly says when NOT to use it versus send_notification, though the scheduled-vs-immediate distinction is strongly implied.

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 idempotency_key parameter description states 'duplicate calls don't double-prompt', which indicates idempotent behavior, but the annotation declares idempotentHint=false. This directly contradicts the annotation and misleads the agent about whether repeated calls are safe. This is a serious inconsistency, so the score is 1.

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

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

The description is three sentences long and each sentence earns its place: what the tool does, when to use it, and how the async response works. It is front-loaded with the core mechanism and avoids repeating schema content.

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

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

For an async decision-gathering tool, the description covers purpose, usage context, return behavior, and the polling flow with check_reply. With an output schema and full parameter schema present, this is nearly complete, but it does not mention expiration behavior or what happens if the user never responds, which would round out the picture.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly, including constraints and defaults. The main description adds the default choices and the async return/polling behavior, but it does not meaningfully exceed what the schema already provides for parameter meaning.

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

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

The description states a specific action: 'Ask the user a question on their phone and get a tap back' with clear mechanics (2–4 answer choices). It clearly distinguishes this from siblings like send_notification and remind_me by focusing on obtaining a decision before consequential actions, and it even points to check_reply for polling.

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: 'Use this when you need the user's decision before a consequential or irreversible action' with concrete examples like deploy, destructive operation, or purchase. It also implies the alternative of using an in-conversation mechanism when the user is present, but it does not explicitly name or contrast an alternative tool.

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

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

The description adds substantial behavioral context beyond the annotations: content passes through Reflecto's servers, is NOT end-to-end encrypted, and has a practical size ceiling because the whole file must be sent as the call's argument. It also warns that .html/.svg files are disallowed because they can render or execute when tapped. This far exceeds what the annotations alone reveal.

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?

Every sentence earns its place: purpose, usage context, privacy/security behavior, and size constraint. The information is front-loaded and each clause adds new, operationally relevant detail without padding or tautology.

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 annotations, a rich input schema, and an output schema, the description is complete for an agent to decide when and how to invoke the tool. It covers the core action, the user-facing use case, transport/privacy caveats, file size limits, and filename restrictions. 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the delivery mechanism, the practical size ceiling for the content argument, and the security implications of the filename destination. This is valuable reinforcement rather than mere repetition.

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: 'Save a text file to the user's phone Downloads folder.' It also clarifies the intended use case with concrete examples (notes, reports, code, logs) and contrasts it with 'replying inline,' making the tool's role clear even among 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?

The description explicitly says when to use this tool: 'when the user asks you to write something out for them to keep on their phone.' It also gives a when-not signal via the 128KB cap ('well under what a person would call a large file'). It stops short of naming a specific alternative sibling, so it misses the highest bar for explicit alternatives.

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

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

Annotations already carry the mutation and non-idempotency profile (readOnlyHint=false, idempotentHint=false). The description adds useful scope context—the notification reaches the user even away from the chat—but does not disclose delivery guarantees, failure behavior, or rate limits. With annotations covering the basic safety profile, a 3 reflects the added but limited behavioral context.

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 targeted sentences front-load the core purpose, then provide usage triggers, a key behavioral trait, and an exclusion. There is no filler or repetition of schema details; 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?

Given the 9-parameter schema and existing output schema, the description covers purpose, scope, usage, and an important delivery behavior. It could be slightly more complete by referencing sibling tools (e.g., list_devices) for device targeting, but the schema already handles that detail, so the description is strong overall.

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

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

Schema description coverage is 100%, and every parameter (ttl, url, tags, title, device, actions, message, priority, url_title) already has a semantic description. The tool description itself adds no parameter-specific meaning, so it does not need to compensate; 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 first sentence names a specific verb and resource: 'Send a push notification to the user's own paired devices (their phone and desktop running Reflecto).' This clearly distinguishes it from siblings like remind_me, request_approval, and send_file by narrowing the target to the user's own devices and specifying the 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?

The description explicitly states when to use the tool ('when the user explicitly asks to be notified, pinged, or alerted, or asks you to let them know when a long-running task finishes') and when not to use it ('Do not use it for routine replies that belong in the conversation'). However, it does not name alternative tools for cases like scheduling a future reminder, so it lacks a full when-not/alternatives mapping.

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