LFG Alarm

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

Annotations declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds real behavioral context beyond them: it overwrites 'what that slot had', runs an upload check, is size-capped at 28M chars/~20MB subject to the person's plan, and gates video wallpapers behind a paid plan. The only unaddressed trait is idempotency, and 'replaces what that slot had' sits in mild tension with destructiveHint=false, though slot media is typically replaceable.

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 slot semantics before constraints, and most sentences carry a distinct fact (source, size, overwrite, plan gating). It is slightly dense with asides like 'LFG checks it like any upload', but nothing is materially wasteful.

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 5-parameter mutation tool with full schema coverage and no output schema, the description covers source constraints, size limits, overwrite behavior, and plan gating well. It omits any indication of what the call returns (e.g. the created upload reference), which would help an agent chain follow-up calls.

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 meaning beyond the schema: it interprets maxLength as 'about 20MB' and warns the plan may allow less, and it ties the enum values to concrete media roles. It does not document the optional 'name' default or content_type examples beyond what the schema already lists.

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 concrete verb and resource: 'Puts a file sent in this call on an alarm the person made', enumerating the three slots (wallpaper, song, voiceover). It clearly separates itself from a URL-based sibling by requiring 'a file this AI app has in hand', though it never names add_media_from_url explicitly, so the differentiation is inferred rather than stated.

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 positive condition (file in the AI app's hand) and a clear exclusion ('a file only on the person's phone can't be sent this way'), which is the practical when-to-use boundary. It stops short of naming the alternative tool to use in the excluded case, leaving that inference to the agent.

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 annotations covering safety flags, the description still adds real value: it fetches the file, validates it like any upload, replaces the existing slot content, adds it to the user's uploads, gates video wallpapers behind a paid plan, and defines error behavior for unfetchable/invalid links. This is unusually rich behavioral disclosure.

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

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

Front-loads the core action and keeps to a handful of sentences, each carrying distinct information (routing, fetch/validate/replace behavior, paywall, errors). A slightly awkward second sentence ('For a file at a public https link...') costs it 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?

No output schema, but the description covers the mutation's side effects, the paywall constraint, and error outcomes, and annotations cover the open-world/idempotency profile. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mildly enriches the `use` values by tying them to the resource (wallpaper/song/voiceover) and stresses that the url must be public https, but does not add syntax beyond 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?

States a specific verb + resource (put a file from a public https link onto an alarm as wallpaper/song/voiceover) and implicitly distinguishes itself from add_media_file by scoping to URL-sourced files only. An agent can tell exactly what this does 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 explicitly routes the alternative case: 'a file only on the person's device needs the one-time page instead,' which is a clear when-not condition. It stops short of naming the sibling tool, so it's a strong 4 rather than 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?

Adds real behavioral context beyond the annotations: letting someone in adds them and notifies them, declining silently clears the request, only the creator is authorized, and letting in a vanished request errors. None of this is derivable from readOnlyHint=false, idempotentHint=true, destructiveHint=false.

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 side-of-request routing, then per-branch behavior, then the authorization/error caveat. Every sentence carries information, though the wording is slightly dense and could be split for faster scanning.

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 three-parameter mutation with no output schema, the definition covers authorization, notification side effects, and the failure case. It does not say what happens on decline if the request is already gone or what a success response contains, leaving a small gap for an agent reasoning about error handling.

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 id, user, and let_in are already documented, including 'true to let them in, false to decline.' The description only adds the downstream consequence of each let_in value (notify vs. silent clear), which is a modest enrichment over the schema 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?

States a specific verb and resource (answer a person's request to join an alarm) and explicitly scopes it to the creator's side, noting the inverse case is separate. An agent can distinguish this from join_alarm / use_invite_code / list_join_requests 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 a clear when-to-use condition (only the alarm's creator answers) and distinguishes the opposing flow ('asking to join someone else's alarm is separate'). It stops short of naming the sibling tool for that opposing flow or pointing to list_join_requests for discovering pending requests, so the alternatives remain inferable rather than explicit.

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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them: the fields returned (name, creator, ring time, riders, hearts, link), the page limits ('Up to 25, 10 when not given'), and the empty-result note ('Returns a note when none match') — helpful behavioral detail for a 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?

Dense and front-loaded, leading with what it lists before the qualifiers. The colon-heavy sentence is slightly awkward to parse but no sentence 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?

For a read-only, no-output-schema list tool, the description covers result shape, limits, ordering, and the empty-result case, and its annotations carry the safety profile. Nothing essential for correct invocation is missing, though it could note whether results are paginated.

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 kind, sort, limit, and search. The description restates those semantics in prose ('newest or most joined first,' 'optionally matching words or of one kind,' 'Up to 25, 10 when not given') but adds no syntax or format detail beyond what the schema provides — 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 ('Lists public alarms anyone can join') with clear scope (public, joinable by anyone). It also distinguishes itself from the sibling list_my_alarms by noting 'the person's own alarms are a separate list,' so an agent can tell the two apart 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 scopes usage to 'public alarms by anyone' and points to the separate own-alarms list as the alternative, which routes the agent correctly. It stops short of a full when-to-use/when-not framing, but the context is 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 flag destructiveHint=true, but the description goes well beyond by disclosing two distinct outcomes: an owned alarm is deleted for all joiners and cannot be undone, while a joined alarm is left and still rings for others. It even states that the response indicates which branch occurred, which is behavioral context 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?

The core action is front-loaded in the first sentence, and the following sentences each carry distinct behavioral weight (the disable alternative, owner-versus-joiner semantics, return value). It is slightly longer than minimal but no sentence is 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?

There is no output schema, and the description compensates by explaining what the return value distinguishes ('Returns which of the two happened') while covering the destructive, irreversible side effect and the permission-scoped behavior. An agent has everything needed to call and interpret it.

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 a single required 'id' parameter that the schema already documents. The phrase 'by its id' adds no meaning beyond the structured field, so the baseline score 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 up front ('Deletes an alarm by its id'), and explicitly distinguishes itself from the closest sibling by contrasting deletion with switching off. An agent can separate this from turn_alarm_on_off, update_alarm, and the set_*_alarm tools 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?

Names the key alternative ('Switching an alarm off instead keeps it'), giving the condition that drives the choice between deleting and disabling. It lacks guidance versus the other mutation siblings (update_alarm, join_alarm) or any explicit prerequisite, but the critical fork is 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 readOnly/idempotent/openWorld, but the description adds information they cannot: a result cap of 8 matches, the fields returned per match (chain, contract, price, market cap, id/symbol/name), the empty-result behavior ('No match returns a note'), and the disambiguation rule that contract addresses separate tokens sharing a name or ticker.

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 front-loaded: purpose first, then return shape, then disambiguation. Slightly redundant, though — the idea that a wallet is not a token appears twice ('a person or wallet trading is not a token' and 'A wallet address is said to be a wallet'), and that second sentence is awkwardly phrased.

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?

There is no output schema, so the description correctly shoulders the burden of describing results: match count limit, per-match fields, and the no-match note. For a one-parameter read-only lookup, nothing an agent needs to invoke or interpret it 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% for the single 'query' parameter, and the description's 'name, ticker or contract address' merely restates the schema wording with examples already present ('pepe', 'SOL'). No additional format or normalization detail is supplied, 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 (finds crypto tokens) plus the accepted lookup keys (name, ticker, contract address). It also carves out the boundary against neighboring tools by noting it 'sets nothing' and that a wallet/trader is not a token, so an agent can distinguish it from set_price_alarm and set_trader_alarm 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?

Explicitly frames the use case: 'For looking up a token before a price alarm,' which routes the agent to this tool as the prerequisite step for set_price_alarm. It also gives an exclusion ('a person or wallet trading is not a token'), so both when-to-use and when-not-to-use are 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds useful scope context: it is the caller's OWN invite, unbound to any alarm, and it lists the returned artifacts including the card image address. It adds meaning beyond the annotations, though it omits any note on permissions or freshness of the code.

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 action and scope, and every clause carries information; the nesting in "invite card picture (their handle, a QR code to the link and their code) with its address" is dense but self-explaining. Slightly overlong as a single sentence.

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 must (and largely does) describe the returned payload in detail. Combined with the annotations covering safety and idempotency, an agent has enough to call it correctly; only minor gaps remain around permissions or link expiry.

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?

Zero parameters and 100% schema coverage, so the schema carries no semantic burden. The description correctly adds no param detail, though it could have clarified that no arguments are needed for this identity-scoped 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?

States a specific verb and resource ("Gets the person's own invite to LFG Alarm") and immediately scopes it as "not tied to any alarm," separating it from alarm-related siblings. It also enumerates the concrete contents returned (invite link, referral code, message, invite card picture with address), so an agent knows exactly what this tool yields.

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 when-to-use ("For the person's own invite to send") and an exclusion ("using someone else's code is separate"), which implicitly routes to use_invite_code. It does not name the alternative tool explicitly, so it falls just 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 only declare the mutation/idempotency profile; the description adds genuinely new behavior: the link is single-use and expires in an hour, a human picks or records the file on the page, and it lands on the alarm on completion. It also discloses the return shape (page link plus direct send address), 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-loads the core action and keeps each sentence purposeful, but is somewhat dense with parenthetical clarifications and a slightly awkward colon-chained first sentence. Efficient overall, mild wordiness.

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 still covers the return values, the interaction flow, the single-use/one-hour constraint, and the alternatives for files not on the device. Everything an agent needs to invoke and reason about the result is present.

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 both parameters are already documented, and the description's elaboration of the enum values (wallpaper as picture or short video, voiceover as a recorded voice message) largely duplicates the schema descriptions. Baseline 3 for high-coverage schemas.

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 ('Makes a one-time lfg.gm page link for putting a file...on an alarm') and scopes exactly which alarm media slots it serves (wallpaper, song, voiceover). An agent can distinguish this from add_media_file and add_media_from_url 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?

Explicitly names the condition for this tool ('a file only on the person's own device') and the exclusion ('a file at a public link, or one this AI app has in hand, can go on directly'), which routes the agent to the sibling upload tools. Both when-to-use and when-not 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the 24-hour window, the empty-state behavior ('Returns a note when nothing rang'), and the richness of the returned scoring data (order, times from the ring, snoozes, titles, still-asleep).

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 purpose and scope are front-loaded in the first clause, and every sentence contributes (what's shown, when it applies, what it accepts, empty-state). The second sentence is a dense run-on combining usage, parameters and return content, which costs a little readability.

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-value burden and does so: it enumerates the wake-order fields, titles, snooze info, still-asleep status, and the no-data note. Combined with the single optional parameter and full annotation coverage, an agent has everything needed to call 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 coverage is 100% and the id parameter's description already states that its absence means every alarm from the last 24 hours. The description restates that same semantics ('One alarm by id, or every alarm that rang... in the last 24 hours') without adding format or syntax 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?

States a specific verb+resource: showing the wake-order leaderboard for alarms that already rang, including times, snoozes and titles. This is clearly distinct from siblings like show_alarm (single alarm detail) or list_my_alarms (scheduling), 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?

Explicitly scopes the tool to alarms that already rang and redirects future-alarm information ('when an alarm rings next is on its card and in the alarm list'). It also explains the two retrieval modes (single id vs. last-24-hours sweep), though it doesn't name a specific sibling tool as the alternative.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds genuine context beyond them: that the heart count is publicly visible on the alarm and that the call returns its heart count, which an agent needs to know about the side effect.

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?

It is short and front-loads the core action, but the opening sentence is awkward and laborious ("the person can open, or takes the heart back, from its link or code"), which costs clarity per word. Most sentences do carry information, so it is adequate rather than wasteful.

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 toggle with full schema coverage and no output schema, the description covers the action, the alternate use case (comments for text), and the return value. Nothing essential to invoking it correctly appears to be 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 both the 'on' toggle and the 'link' string are already fully documented in the schema, making 3 the baseline. The description reiterates the toggle semantics without adding format or syntax 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 states a specific verb (heart) and resource (an alarm) and clarifies it is a toggle from a link or code, which distinguishes it from siblings like show_alarm, update_alarm, and post_comment. The phrasing is slightly garbled ("Hearts an alarm the person can open") but the operation is unambiguous.

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?

Usage is only implied: it routes text content elsewhere ("For a heart; words go in a comment"), telling the agent to use a comment tool when prose is needed. It never states when to choose this over sibling alarm tools or any prerequisite conditions, so guidance is partial rather than explicit.

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 (readOnly=false, destructive=false, idempotent=true, openWorld=false), but the description adds real behavioural context beyond them: the ask flag triggers a request sent to the creator, and two distinct failure states are disclosed. It does not clarify what happens without ask on a friend's alarm the person isn't on, leaving one behaviour 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?

Dense but earns nearly every clause, and the primary purpose is front-loaded. There is mild redundancy: 'For an alarm someone else made, by its link or code' restates the opening sentence, and the phrasing is occasionally awkward ('A friends alarm the person is not on can't be joined').

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?

No output schema exists, and the description compensates by stating the return ('the alarm's name, creator and when it rings') along with preconditions and side effects. For a two-parameter, non-destructive action, 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the link parameter can carry an alarm link, the message it arrived in, or a code, and explicitly excludes referral codes. That sharpens the accepted input beyond the schema's 'link (lfg.gm/a/...), the message it came in, or its code'.

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 ('Joins someone else's alarm') plus the observable effect ('it rings on the person's phone too'). The clause 'a referral code is not an alarm' separates it from the sibling use_invite_code, so an agent can route correctly without opening either schema.

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

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

Gives clear preconditions and exclusions: only an alarm someone else made, a friend's alarm the person isn't on 'can't be joined' unless ask is set, and an alarm that already rang its last time can't be joined. It routes away from referral codes but never names the alternative tool (use_invite_code) explicitly, so it falls just short of full when/when-not/alternatives 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the person is excluded from the list, and a note is returned when there are no friends yet. This is useful edge-case disclosure, though nothing about ordering or limits is given.

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 purpose, then the distinguishing constraint, then the sharing rationale and empty-state note. Four sentences is slightly more than needed, but each carries real information and there is 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 no parameters and no output schema, the description carries the burden of describing what comes back (usernames, group names, empty-state note) and it does so adequately. Only minor gaps remain, such as return ordering or pagination.

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?

Zero parameters, so there is nothing to document and the baseline is 4. No parameter meaning is needed or missing.

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 ('Lists the person's friends... and their friend groups with each group's members by username') and explicitly distinguishes this list from the alarm-member list ('the people on one alarm are a separate list'). An agent can tell exactly what set is returned without opening anything else.

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 context for when this applies ('For the person's own friends and groups') and a reason to call it ('the ones a friends alarm can be shared with'), while ruling out the alarm-member case. It stops short of naming an alternative tool explicitly, so not a full 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the returned shape (username + day asked) and the edge case that a note is returned when nobody is waiting.

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

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

Front-loads the core action, then layers scope and edge case in short clauses. Slightly fragmentary punctuation ('For people still waiting;') costs a little readability, but there is 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 no output schema, the description carries the return-value burden and does so adequately, describing both the success shape and the empty case. It could say more about ordering or volume, but 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 single 'id' parameter is already documented ('Leave out for all of them'). The description reinforces the omitted-id behavior in prose but adds no new semantics or format detail beyond the schema. 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 ('lists the people asking to join a friends alarm'), including the scope of what is returned. It distinguishes the 'still waiting' set from 'the people already on an alarm are a separate list'. It never names the actual sibling tool that shows that other list, so differentiation is conceptual rather than explicit.

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 implied routing via 'For people still waiting' and clarifies the broad scope when no id is passed. However, it never states when to pick this over close siblings like answer_join_request (acting on a request) or list_my_alarms, leaving the caller to infer the boundary.

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 safety is covered. The description adds real behavioral context beyond that: the returned field set, that alarms deleted by their creator are omitted, and that a note is returned when the list is empty.

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 return contents, then sibling routing, then edge-case behavior. Every clause carries information; nothing 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?

With no output schema, the description compensates by listing the fields returned (name, type, reach, on/off, next ring, link, id), the deleted-alarm exclusion, and the empty-result note. Nothing an agent needs to call and interpret 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No parameter syntax or filtering options are needed.

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 (lists the person's alarms) and scopes it to both owned and joined alarms, enumerating the returned fields. It explicitly contrasts itself with show_alarm, list_riders and get_wake_board by noting those are 'separate reads', so an agent can distinguish it from siblings 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?

Clear routing: use this for the whole list, and note that 'one alarm's card, its riders or its wake board are separate reads', which steers the agent to show_alarm/list_riders/get_wake_board. It stops short of naming those siblings explicitly or stating exclusions beyond deleted alarms.

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, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the fields each item carries (id, name, source), preview inclusion, and the empty-result note. It stops short of mentioning pagination or result 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?

Front-loaded with purpose, then scope, then return content, then the preview and empty-state caveats. Sentences are dense but each carries information; the repeated 'For the person's own uploads' phrasing is mildly redundant with the opening clause.

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 responsibly covers return contents, ordering, preview behavior, and the empty case for a simple two-parameter read tool. Pagination or result-count limits are the only meaningful omission.

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. The description restates the enum values ('pictures', 'sounds') and the previews=false behavior without adding syntax or format detail beyond the schema, matching the baseline 3.

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

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

States a specific verb and resource ('Lists the person's own uploads') and immediately scopes it against alternatives by noting that LFG's library and KLIPY GIFs are separate searches. An agent can distinguish this from search_library and search_gifs 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?

It gives clear context for when to use it (the person's own uploads) and excludes the alternative sources (library, KLIPY GIFs) as separate searches. It does not name the sibling tools explicitly nor state any prerequisites, so it falls short of a full 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 cover readOnly/idempotent/non-destructive, so the description's value-add is the error condition ('an alarm the person is not on returns an error') and the guaranteed ordering of results. It doesn't mention pagination or result-size limits, which is the remaining behavioral 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 purpose and ordering, then a scoping clause, then scope of returned data, then the error case. Slightly padded by 'Usernames only, nothing else about anyone,' which partially restates the first sentence's field list, but every sentence contributes.

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 correctly describes return values (usernames plus join day, in creator-then-newest order) and the failure mode. It is complete enough to invoke correctly; only pagination/truncation behavior for large alarms is unaddressed.

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% for the single UUID `id` parameter, so the schema carries the parameter documentation. The description adds no format, constraint, or auth detail about the id beyond what the schema states, making baseline 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?

Specific verb+resource ('Lists everyone on an alarm') plus the returned fields (username, join day) and sort order (creator first, then newest). It also distinguishes itself from the pending-request sibling by stating 'people still asking to join are a separate list.' An agent can identify this tool without opening a schema.

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

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

Gives a clear usage condition ('For people already on one alarm') and explicitly excludes the adjacent case (pending join requests). It stops short of naming the sibling tool list_join_requests, so the routing signal is descriptive rather than a direct pointer.

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, destructiveHint=false, and openWorldHint, and the description reinforces this with 'Changes nothing' and 'Only reads' – some overlap, but it adds genuine value by documenting the error path and the per-type payload contents (owner, ring time, riders, joinability). It stops short of describing idempotency or caching behavior explicitly, so a 4 rather than 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 the core action, then a tight enumeration of resolved link types. The detail about return contents is justified because there is no output schema, but the sentence is long and slightly list-heavy; still, every clause 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?

With no output schema, the description usefully documents what each link type yields and covers the error case. Combined with annotations covering safety and openWorld behavior, an agent has enough to invoke it correctly; only pagination/rate details are absent, which are not relevant here.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'The link, or the message it came in.' The description restates this dual-input semantics ('a link ... or a whole message with a link in it') but adds no format, length, or parsing constraints beyond the schema. 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 (reads/identifies) and resource (a link or message containing one), then enumerates the exact types it resolves: LFG alarm, LFG invite with referral code, Partiful/Luma event. This clearly distinguishes it from siblings like join_alarm, use_invite_code, and get_invite_card without needing to open their 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?

Explicitly bounds the scope: 'Only reads; joining an alarm or using an invite code are separate steps,' routing the agent toward join_alarm and use_invite_code. It also states the failure condition ('Any other link returns an error'), so the agent knows when this tool is not the right choice.

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 this is a non-destructive, non-idempotent write. The description adds genuinely new behavior that annotations cannot carry: the comment is visible to everyone who can open the alarm and the alarm's creator is notified. It does not address auth requirements or failure modes, so it falls 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?

Four compact sentences with the action and target front-loaded, and no repetition of the title. The fragment 'For words; a heart is separate' is slightly telegraphic, which costs a point on structure but not on 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?

With no output schema, the description still covers purpose, audience, notification side effect, character limit, and the sibling alternative, which is most of what an agent needs to call it. Missing only permission/auth expectations and confirmation of what a successful call returns.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured data; the description's 'from its link or code' merely echoes the schema's link/comment definitions. The 280-character limit is reinforced but already enforced by the schema's maxLength. 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?

States a specific verb (posts) and resource (comment) scoped to an alarm the person rides or made, retrieved via its link or code. It also explicitly separates itself from a sibling: 'For words; a heart is separate' distinguishes it from heart_alarm, and the read/write contrast distinguishes it from read_comments.

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?

'For words; a heart is separate' routes the agent to heart_alarm for reactions, and 'an alarm the person rides or made' gives the eligibility condition. It stops short of stating when-not to use it or naming the alternative tool verbatim, but the context is clear enough to act on.

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 safety profile is covered. The description adds real behavioral context beyond that: ordering (newest first), a result cap (up to 30), the returned fields (heart and comment counts), and a conditional visibility note about commenting after joining. It does not explain what happens past 30 comments, leaving a small 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?

The key facts (scope, ordering, cap, returned counts, read-only nature) are front-loaded and dense, with no filler sentences. The closing line 'Comments are other people's words' is a stylistic observation rather than operational information and slightly dilutes the otherwise tight prose.

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, read-only tool with no output schema, the description covers ordering, result cap, returned counts, and the read-only boundary, which is nearly everything an agent needs. The one missing piece is whether older comments beyond the 30-item cap can be retrieved at all.

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 required parameter with 100% schema description coverage ('The alarm's link or code'), and the description repeats that same meaning ('from its link or code') without adding format, prefix, or resolution details. With the schema doing the documentation work, this is the baseline case.

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 ('Reads an alarm's comments') plus scope details (newest first, up to 30, includes heart/comment counts). It explicitly distinguishes itself from the write siblings: 'Only reads; posting and hearting are separate,' which separates it from post_comment and heart_alarm.

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 context for use (fetching an alarm's comment thread) and explicitly excludes posting and hearting by pointing out they are separate operations. It does not name the sibling tools directly, but the separation of read vs. write 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 cover the read-only, idempotent, non-destructive, open-world profile, and the description adds real behavioral context beyond them: page size of 24, that GIFs stream from KLIPY and are never stored by LFG, and that a no-match search returns a note rather than an error.

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

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

Front-loads the core action and the empty-query behavior in the first clause. The remaining sentences are dense but each carries information; "the address and id a GIF wallpaper takes" is slightly awkward phrasing but not 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?

With no output schema, the description usefully covers the return shape (address and id per result) and the empty-result case. It does not mention pagination bounds (max page 20) or result ordering, minor gaps for a two-parameter search 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 description coverage is 100%, so both parameters (page of 24, query with empty=trending) are already documented in the schema. The description's "24 to a page" and empty-query behavior restate the schema rather than adding syntax or format detail, 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+resource ("Searches KLIPY's GIFs for a wallpaper") plus the alternate trending mode, and carves out scope by noting LFG's own sounds and looks are a separate search. It never names the sibling tool that handles that other search, so differentiation is implied rather than explicit.

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?

Clearly explains the two modes: search for a wallpaper when a query is given, trending when the query is empty. It also signals that this tool is not for LFG's own sounds/looks, but stops short of naming the alternative or stating explicit 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?

With readOnly/idempotent/non-destructive annotations already covering the safety profile, the description adds genuine behavioral context: result ceilings (up to 10 sounds; up to 3 vibes yielding 8 pictures and 6 drawn looks each) and the fact that each result carries the id an alarm consumes. It omits error/rate-limit behavior, so 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?

The core purpose is front-loaded, but the middle is a dense run-on ("sounds: over 500 songs, voices, tones and themes, each tagged with the moods it fits...") and the looks clause nests colons within colons. Most content earns its place, yet the phrasing is heavier than needed.

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 5-parameter read tool with no output schema, the description supplies the missing return-shape information (counts and the id an alarm takes) and the empty-query fallback, which is enough for an agent to call it correctly. Minor gaps remain around error handling and pagination, but nothing critical is absent.

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 kind, query, voice, energy and category including their enums and the empty-query behavior. The description mostly restates those semantics ("a category lists a whole shelf, and an empty search lists staff picks") without adding syntax or constraints beyond them, 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 opening sentence states a specific verb and resource ("Searches LFG's own library") and immediately carves out the boundary against siblings by declaring that KLIPY GIFs and the person's own uploads are separate searches. An agent can distinguish this from search_gifs and list_my_media without inspecting 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?

It gives clear when-to-use context (LFG's own sounds and wallpapers) and an implicit when-not (GIFs and personal uploads live elsewhere), plus special-case guidance that an empty query lists staff picks or every vibe. It stops short of naming the alternative tools directly, so routing still requires a small 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 the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the lower bar applies. The description adds real value beyond them: it lists the fields read from the link, the derived defaults (picture→wallpaper, page→button, description→note), and the two error conditions.

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 purpose and free of filler, with the scoping constraint and error cases placed sensibly. Slightly dense across five sentences, but each sentence (derivation, error, return) 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?

For a 21-parameter tool with 95% schema coverage and no output schema, the description covers the essential behavior: what is read from the link, what gets derived, failure modes, and the return value. The many optional styling/social params are left to the schema, which documents them adequately.

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 95%, so the baseline is 3. The description goes beyond the schema by explaining how the link auto-populates several parameters (title, note, wallpaper, button link) and that a supplied note overrides the derived one — semantics the per-field descriptions don't state.

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+source ('Sets an alarm for an event from its Luma or Partiful link') and immediately scopes the input type. It explicitly distinguishes itself from the sibling 'time alarm' for any other moment, so an agent can route 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 for Luma and Partiful event links; any other moment on the clock is a time alarm' gives clear when-to-use plus one named alternative. It doesn't fully address the other alarm siblings (post/price/trader/webhook), but the scope constraint is explicit.

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

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

Adds meaningful behavior beyond the annotations: it replaces the existing wallpaper, plays from KLIPY, is never stored by LFG, and returns an error for a non-KLIPY address. These are exactly the side effects and failure modes an agent needs, and they are consistent with idempotentHint=true and destructiveHint=false.

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 the action, then scope, then side effects and error behavior. Slightly dense in the opening clause but every sentence contributes.

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 write tool with no output schema and annotations covering the safety profile, the description supplies replacement, storage, and error semantics. Only the return/confirmation behavior is left implicit, which is minor here.

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; the description only loosely references 'address and id'. Baseline 3 applies when the schema carries the parameter 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 states a specific verb and resource – making a KLIPY GIF the wallpaper of an existing alarm – and scopes it precisely ('KLIPY GIFs only'). An agent can distinguish it from generic media tools like set_media or add_media_from_url 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?

It says 'For KLIPY GIFs only' and that a library look or own upload goes on 'by its id', which implies an alternative path but never names the sibling tool that handles it. Usage conditions are present but only implied, not routed explicitly.

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 read-only/idempotency/open-world, but the description adds genuinely new behavior: it overwrites the existing slot ('It replaces what that slot had') and defines the failure mode ('An id that matches nothing returns an error'). It also scopes the voiceover slot to the person's own sounds. The overwrite disclosure sits in mild tension with destructiveHint=false, though replacing an assignment (not deleting the underlying media) is arguably reversible and idempotent.

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, but the text is wordy and partly redundant ('by its id' recurs; 'already in LFG' appears twice) and the second sentence is a fragment that restates the first before pivoting to alternatives. It is readable but not tight.

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 no output schema, the description covers purpose, sibling routing, slot semantics, overwrite behavior, and the error case. Only minor gaps remain (e.g., ownership/permission prerequisites beyond 'an alarm the person made').

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 a constraint not present in the schema: 'use' selects wallpaper/song/voiceover and voiceover is limited to the person's own sounds. It also clarifies that media_id can be a library sound id, a drawn look id, or an upload id.

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 ('Puts something already in LFG on an alarm ... a library sound, a drawn look or theme picture, or one of the person's own uploads'), and enumerates the accepted media classes so the tool is distinguishable from set_gif and the add_media_* family. An agent can tell what it does 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 conditions: use this for something already in LFG with an id, whereas 'a new file goes on by link, as a file, or through the one-time page, and a KLIPY GIF by its address'. The alternatives are described functionally rather than named (add_media_file, add_media_from_url, set_gif), so the agent must map descriptions to sibling names itself.

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 this is a non-read-only, open-world, non-idempotent write. The description adds useful context beyond them: a nonexistent channel returns an error, the return is the alarm and its link, and the watch_for/moment parameters are platform-scoped. It does not address permissions, side effects on existing alarms, or rate limits, but the annotation coverage lowers the bar.

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 behavior (what rings the alarm and for which platforms) before moving to differentiation and platform-scoped caveats. Each sentence carries distinct information with no filler, though the platform-scoping sentence is slightly dense and could be tighter.

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?

No output schema exists, and the description supplies the missing return information (the alarm and its link) plus error behavior for unresolvable channels. With 21 parameters at 95% schema coverage and a clear platform/trigger model, an agent has enough to select and 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?

Schema coverage is 95%, so parameter meaning is largely carried by the schema, but the description contributes cross-field semantics the schema does not state: watch_for is honored only for X, and moment only for Twitch/YouTube. That conditional coupling between the account/platform parameter and the trigger parameters is genuinely additive.

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 (sets an alarm) plus the exact trigger condition (X account posts something matching, Twitch/YouTube goes live or posts a video). It explicitly distinguishes itself from the sibling alarm tools by naming the other alarm domains: "a token's price, a trader's trades and an event link are different alarms."

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?

Clearly states the condition under which this alarm applies (X posts, Twitch/YouTube live/video) and routes other cases away from it by naming the competing alarm categories. It also states per-platform applicability of watch_for and moment. It stops short of naming the sibling tools (set_price_alarm, etc.) directly, so the routing is category-level rather than tool-level.

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 a non-read-only, non-idempotent, open-world write, and the description adds genuinely non-obvious traits: the alarm 'rings once and then stops for good' (one-shot, not recurring) and requires exactly one trigger parameter. These are behavioral facts beyond the annotation flags.

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 trigger, then constraints, then return behavior. Slightly loose in the middle ('a trader or wallet trading, or anyone trading a token') which restates the same exclusion twice, but overall tight and well-ordered.

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 24-parameter write tool with no output schema, the description covers the essentials: the trigger semantics, the required identity fields, the one-of constraint, the one-shot behavior, and even the return contents ('the alarm, the price it started from and its link'). The many cosmetic params (vibe, theme, snooze) are left to the schema, which is acceptable given 96% coverage.

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 96%, so the baseline is 3, but the description adds a real constraint the schema does not encode: exactly one of target_price_usd or percent must be supplied, and token_id/symbol/name are the required identity triple. That mutual-exclusivity rule is meaningful value beyond 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?

States a specific verb+resource+trigger: 'Sets an alarm that rings... when a token reaches a target price, or moves a percent from its price now.' It also distinguishes itself from the sibling set_trader_alarm by noting a trader/wallet trading alarm 'is a different alarm,' so an agent can route correctly 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 clear context ('For one token's price') and contrasts with the trader/wallet alarm case, plus the selection constraint 'exactly one of target_price_usd or percent.' It stops short of naming the alternative sibling explicitly, so it's clear but not fully routing-complete.

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 the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds genuinely useful behavior: friends added are notified, email addresses without an LFG account receive an invitation, and the call returns the alarm, its next ring time, its link and a share picture. The 'date or repeat days, never both' constraint is also disclosed, which is exactly the kind of cross-field behavior the schema does not state.

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 front-loaded sentences: purpose first, then boundary conditions, then side effects and return value. Dense with clauses but every sentence carries distinct information; 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?

Despite 23 parameters, nested objects and no output schema, the description covers the required inputs, the one-off vs repeating split, side effects on added people, and the return payload. The many optional styling fields (vibe, theme, snooze, wallpaper) are left to the 96%-covered schema, which is a reasonable division of labor.

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 96%, so the per-field semantics are already handled; the baseline would be 3. The description rises above it by stating the mutually exclusive pairing of date vs repeat_days and the required time + IANA time zone, a schema-level relationship no individual property description captures.

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 with scope: an alarm that rings at a clock time, either once on a date or on repeating weekdays. It also explicitly carves itself out from the sibling family, noting it 'does not watch anything online' and that an event with a Luma/Partiful link is a different alarm, so an agent can separate it from set_event_alarm, set_webhook_alarm, set_post_alarm and the price/trader alarms.

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 ('a wake-up, a meeting, a reminder') and an explicit exclusion for link-watching / event-link alarms. It stops short of naming the sibling tool to use instead (e.g. set_event_alarm), so routing is implied rather than fully specified.

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 the generic write/open-world/not-idempotent profile, and the description adds real behavior: a 15-minute quiet period after ringing ('a run of trades is one ring'), wallet alarms are never public, and it returns the alarm and its link. It does not note auth requirements or what happens on a duplicate alarm, 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?

Dense but front-loaded: trigger semantics first, then the target exclusivity rule, then the cooldown, then the return value. Sentences each carry content, though the middle sentence about trader handle sourcing (FOMO/KOL/GMGN) is slightly convoluted.

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 23-param tool with no required fields and no output schema, the description covers the decision-critical parts: what rings it, the mutually exclusive target, the cooldown, and the return value. Remaining gaps (cosmetic params) are fully documented in the schema at 96% coverage.

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 96%, so the baseline is 3, but the description contributes real semantics the schema lacks: the exclusivity constraint among trader/token_address/wallet_address (there is no oneOf in the schema), the FOMO-vs-GMGN trader distinction, and the cooldown behavior tied to the watch targets. Most of the 23 cosmetic params (vibe, theme, wallpaper) are left entirely to 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?

States a specific verb+resource (sets a trader alarm) and enumerates the exact trigger conditions: a trader buying/selling/posting a thesis, anyone on FOMO trading a token, or a wallet buying/selling. It also explicitly disambiguates from the sibling set_price_alarm by saying 'a token reaching a price is a different alarm.'

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 selection rule: 'Takes exactly one of' a trader handle, token contract address, or wallet address, and scopes thesis to FOMO only and wallet alarms to never-public. It sets context well but does not name the alternative tools (set_price_alarm, set_event_alarm) or state when a trader alarm is the wrong choice beyond the price case.

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 the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=false). The description adds genuinely useful behavior beyond them: quiet-time suppression ('Calls within its quiet time after a ring are ignored'), the paid-plan requirement, the private/friends-only visibility constraint, and the returned payload (alarm, address to call, link).

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 purpose, then constraints and return values in a compact block of roughly 100 words for an 18-parameter tool. Sentences are long and list-heavy at points, but almost nothing is wasted.

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

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

For a complex mutation tool with 18 params and no output schema, the description covers purpose, prerequisites, key runtime behavior (quiet time), visibility limits and return values. It leaves the many cosmetic parameters (theme, vibe, snooze, wallpaper) to the schema, which is fair at 94% coverage, but a little more on the callable web address would help.

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 94% schema description coverage, the schema already documents the 18 parameters in detail, so the baseline is 3. The description restates a few of them (quiet time, private/friends) but adds no syntax or format meaning 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?

States a specific verb and resource ('Sets an alarm that rings... whenever its private web address is called') with the triggering mechanism spelled out. It differentiates from siblings by naming the parallel alarm types ('a time, a post, a price, a trade or an event link each has its own alarm'), which maps to set_time_alarm, set_post_alarm, set_price_alarm, set_trader_alarm and set_event_alarm.

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 selection condition ('For something only another system can see happen') and prerequisites (paid plan; private or friends, never public). Alternatives are implied by pointing at the other alarm types, but it never says explicitly to use set_time_alarm etc. instead, 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add genuinely new behavior: the error returned for an id that isn't the person's alarm, the point-in-time ('as it is now') semantics, and the MCP Apps card rendering. It does not mention rate limits or pagination, but neither is relevant for a single-record fetch.

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 the core verb+resource, then constraints, then return shape. Every clause carries information an agent needs; nothing is redundant with 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?

With no output schema, the description compensates by enumerating the returned fields (name, type, reach, on/off, next ring, link) and disclosing the error case for foreign ids. Combined with annotations, an agent has everything needed to call and interpret this 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 description coverage is 100% and the single uuid parameter is fully specified by the schema, including format and pattern. The description reinforces that the id must belong to the person's alarms but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Shows one of the person's alarms by its id') plus the exact scope of what is returned, and explicitly separates itself from listing/searching siblings. An agent can distinguish it from list_my_alarms or update_alarm 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 clear usage context (requires an id) and an explicit exclusion ('it does not search by name or list alarms'), which steers the agent away from misuse. It stops short of naming the alternative tool (e.g. list_my_alarms) as the way to obtain an id, so it is clear but not fully routing.

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 write/idempotent/non-destructive, but the description adds real behavioral context beyond them: it keeps the alarm and all its contents, deleting is permanent and separate, and for a joined alarm it only toggles ringing for that user. It also discloses the return ('the alarm as it is now'). This is exactly the extra context 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?

Four short sentences, each carrying distinct information (scope, preservation, scope of access, return). The core action is front-loaded and there is 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 two-parameter toggle with full schema coverage and confirming annotations, the description supplies everything an agent needs: what changes, what is preserved, who it applies to, and the return shape. 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%, so both parameters ('id' and 'on') are already fully documented in the schema. The description adds no syntax or format detail beyond restating the on/off toggle, 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+resource ('Turns an alarm on or off') and immediately narrows scope ('without changing anything else about it'), which cleanly distinguishes it from update_alarm and delete_alarm. An agent can tell what it does 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 clear usage context by noting it works on both owned and joined alarms, and that deleting is 'permanent and separate' – implicitly steering away from delete_alarm. It stops short of explicitly naming the alternative tools or stating when-not-to-use conditions, so it is a strong 4 rather than 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?

Adds real consequences beyond the annotations: riders of a friend's alarm are told of a new look and asked whether to stay after a time change, removed people lose the alarm silently, and public alarms freeze after joins. It also declares the return value ("Returns the alarm and its link"), which the tool has no output schema for. The destructiveHint=true annotation is consistent but the description doesn't explain why it is flagged destructive (e.g. remove_people) as sharply as it could.

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 verb, resource and the full set of mutable facets, then the boundaries, then side effects — good ordering with zero filler. The long enumeration of fields is dense but earns its place given 22 parameters; a slight trim would improve scanability.

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 22-parameter mutation with no output schema, the description covers preconditions, partial-update semantics, notification side effects, a hard block condition, and the return value. What it omits — mutual exclusivity of date and repeat_days, and the people_confirmed requirement — is documented in the schema, but would have been valuable to surface here given the tool's breadth.

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 95%, so the schema already carries field-level meaning; the description's list of changeable facets largely restates parameter names. It adds some framing ("whether it is a surprise", "who is let in or taken off") but does not clarify interactions such as date vs repeat_days exclusivity or the people_confirmed gate, which remain in the schema text only. Baseline 3 for a high-coverage 22-parameter 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?

Opens with a specific verb+resource ("Changes an alarm") and enumerates the mutable facets: title, time/days, wallpaper, theme, note, button link, snooze, reach, surprise, membership. It explicitly carves out the neighbouring operations ("it does not make new alarms, and on or off alone is a separate switch"), which cleanly separates it from set_time_alarm, turn_alarm_on_off and delete_alarm 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?

States the precondition ("For an alarm that already exists and that the person made"), names the alternatives it is not (creation, toggling), and gives the constraint that blocks a call ("A public alarm cannot change once anyone has joined it"). It also supplies the partial-update rule: "Fields left out stay as they are."

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-readonly/non-idempotent, but the description adds substantial context beyond them: the one-time-per-account limit, the self-referral prohibition, irreversibility ('it cannot be undone'), the deferred welcome-gift side effect, and the error on an invalid code. This is rich behavioral disclosure.

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?

Dense and front-loaded, leading with the core action and constraints before the edge cases. Every sentence carries information, though the gift/error sentences could be slightly tighter.

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 no output schema, the description covers action, constraints, irreversibility, deferred effects, and error behavior. 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 'code' parameter is fully documented in the schema. The description only echoes the LFG-… format and adds the referral-vs-alarm distinction, so it adds little beyond the structured field.

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 ('Uses a friend's LFG referral code'), and explicitly distinguishes itself from the alarm-joining path ('an alarm's link or code is joined, not used here'). An agent can separate this from join_alarm 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 a clear selection condition: use this for a referral code (LFG-…), while an alarm's link/code is joined elsewhere. Constraints (once per account, never your own code) further scope usage, though it does not name the alternative sibling tool outright.

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