beep.me

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

Annotations already declare mutating-but-non-destructive, idempotent behavior; the description adds the rate-limit consequence of wrong codes and the alternative confirmation path via the email link. That rate-limit disclosure is real behavioral value not present in 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?

Three tight sentences: purpose first, then the hard usage constraint, then the failure fallback. The explanatory clause about avoiding the email link earns its place by motivating the 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 two-parameter, fully documented input with annotations and no output schema, this covers purpose, constraints, and failure behavior. Only the post-success state (reminders now active) could be slightly more explicit.

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?

With 100% schema coverage, the schema already explains both parameters in detail. The description adds only a modest clarification that the email must be the one the reminder was created with, so baseline 3 holds.

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: switching on beep.me email reminders by submitting a 6-digit confirmation code. The mechanism is distinctive enough that an agent can tell it apart from remind_me or my_reminders, though no sibling 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?

It gives clear conditions for use (a code the user typed themselves, the address the reminder was created with) plus firm prohibitions against guessing or reusing codes, and a fallback (the email link still works). It lacks explicit routing against sibling tools such as remind_me.

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 by disclosing the double-opt-in flow: a confirmation email for a new address, reminders only starting after the link is clicked, and a stop-following link in every reminder. It also explains the beep.me signed-in variant where email is omitted and the follow is immediate with no confirmation. The idempotentHint is consistent with the fact that re-following an already followed team is harmless.

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 and scope, then layers alternatives, prerequisites, and the confirmation flow in short clauses. Despite the density, every sentence contributes a distinct operational fact, and none is redundant.

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 six-parameter mutation tool with no output schema, it covers everything an agent needs: scope, alternative tool, exclusion, email prerequisite, confirmation-email consequence, and the signed-in shortcut. Nothing material about invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds instruction-level meaning by telling the agent to collect and never guess the email, and by explaining that matches added or moved later are still covered. The beep.me/omit-email guidance largely restates the schema's own email description, which keeps it below a 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?

Opens with a specific verb and resource: 'Sign the user up for an email reminder before EVERY upcoming match of a football team.' The 'EVERY' scope plus the explicit sibling reference 'for one match, use remind_me' makes it impossible to confuse with remind_me or search_events.

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

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

Gives concrete trigger phrases ('every match, all matches, whenever <team> plays, or follow <team>'), names the alternative for the single-match case, and states an exclusion ('Only for teams, never for personal appointments'). It also states the prerequisite: ask the user for their email first, never guess.

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 the auth prerequisite and the content of what is returned. It does not cover ordering, pagination, or behavior on an empty list, which is the remaining gap for a list tool with no output schema.

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

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

A single front-loaded sentence: what is listed, what each entry contains, when to use it, and the auth requirement. No redundant restatement of the title or annotations, and every clause 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?

With no output schema, the description carries the return-shape burden and does so at a summary level (event email arrival times, followed teams) plus the sign-in requirement. Ordering, volume, and pagination behavior remain unstated, which is a minor gap for a zero-argument 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 there is no parameter meaning for the description to add and the baseline of 4 applies. The description correctly implies no filtering or scoping arguments 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?

States a specific verb and resource ('List the reminders on the signed-in user's beep.me account') and enumerates the two record kinds returned (upcoming events with email arrival times, followed teams). That enumeration clearly separates it from siblings like search_events or remind_me.

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

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

Gives an explicit trigger ('when the user asks what beep.me reminds them about') and an explicit downstream use ('before stop_reminder to find the id'), naming the sibling that depends on it. It also states the precondition (user signed in), so no inference is required.

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 (readOnlyHint=false, idempotentHint=true, openWorldHint=true), the description discloses the two-step activation state machine: a new address receives one confirmation email, and the reminder is only switched on once the link is clicked. It also describes the divergent beep.me signed-in path where no confirmation is needed, which is exactly the kind of behavioral detail 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 in the first clause, and each following sentence adds a distinct constraint (email confirmation, event-source restriction, beep.me exception). Slight redundancy remains: the beep.me 'leave email out' rule appears in both the description and the email property description.

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

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

For a six-parameter mutation with no output schema and a conditional confirmation flow, the description covers the mechanics an agent needs: prerequisite prompting, event sourcing, and the activation gate. It does not address re-submission behavior for an already-registered address or how to later modify/cancel, though stop_reminder exists as a sibling for part of that.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the two most consequential parameters: event_id must come from search_events, and email must be the user's exact address or omitted entirely under beep.me sign-in. Country, timezone, language, and remind_before_minutes are left to the schema, which is acceptable given full coverage.

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

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

States a specific verb+resource pair: signing the user up for an email reminder tied to a public event. It also pins the input source ('an event that search_events returned'), which separates it from stop_reminder and my_reminders without needing to open 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 (events from search_events), explicit when-not ('never for personal appointments'), and a named alternative path (beep.me connected with sign-in → omit email, no confirmation). It also specifies the prerequisite interaction: ask the user for their email and never guess 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 readOnlyHint=true and destructiveHint=false, and openWorldHint=false is consistent with the stated beep.me closed catalog. The description adds genuine value beyond that: it names the data source, states the result shape (id, date, link), and warns that only public events exist in the catalog. It stops short of covering empty-result behavior or catalog staleness.

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

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

Three sentences, front-loaded with the core verb and scope, then the trigger, then the exclusion. The event-type list is long but each item disambiguates a real category rather than padding; 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?

With no output schema, the description usefully summarizes the return shape, and with only three well-documented parameters the surface is small. Minor gaps remain around what happens when no event matches and how limit interacts with recency ordering, but 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 coverage is 100%, so query, limit and country are already documented in detail, including the keyword-style example and the country-ranking rule. The description adds no parameter-level meaning of its own, 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?

Opens with a specific verb+resource ("Find when a public event happens") and enumerates the concrete classes of events covered (match, film release, TV premiere, concert, festival, sale, deadline, holiday). An agent can immediately tell this is an event-date lookup and not a reminder or calendar operation.

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

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

Gives an explicit trigger ("Call it whenever the user asks when something people wait for will happen, or asks to be reminded or notified about it") and an explicit exclusion with a named alternative destination ("Not for personal appointments or private to-dos... use the user's own calendar or reminders for those"). Both the use case and the routing-away condition are stated.

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

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

Annotations already declare destructive=true, idempotent=true, openWorld=false, so the safety profile is covered; the description adds real context on top: an auth requirement ("Needs the user signed in to beep.me") and the differing blast radius of the two modes — one event vs. *every* match of a followed team. Silent on what happens if the ID no longer exists or on partial-failure 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 sentences, front-loaded with the action and its two modes, then the usage guard and auth precondition. No restatement of the title and 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?

For a destructive, unauthenticated-by-default mutation with rich annotations and no output schema, the description covers scope, auth, and the stop-only-when-asked rule. The one gap is that required_parameters is 0, yet neither an empty call nor an event_id+follow_id call is addressed, leaving a real invocation ambiguity.

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 semantics the schema does not: follow_id cancels all matches of a followed team rather than a single item, and both IDs originate from my_reminders. It does not state whether the two parameters are mutually exclusive or what the precedence is if both are supplied.

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

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

States a specific verb + resource ("Stop one reminder") plus the two addressing modes (event by event_id, followed team by follow_id), and anchors the IDs to my_reminders, a sibling tool. An agent can distinguish this from remind_me/follow_team 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?

"Only when the user asked to stop it" is an explicit gating condition that rules out proactive cancellation, and pointing at my_reminders tells the agent where the IDs must come from. It stops short of naming alternatives (e.g., unfollowing vs. stopping) or what to do when the user hasn't specified an ID.

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