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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds useful behavioral detail: the category-mismatch fallback behavior and the semantics of reminders ('days before the due date'). It does not disclose what the response looks like or that repeats need an interval (that is only in the 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?

Three sentences, front-loaded with the core action and scope, no filler. Slightly dense but every sentence carries usable information.

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

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

For an 11-parameter mutation tool with no output schema and only 55% schema description coverage, the description covers the headline concept and two tricky parameters but leaves return behavior and several optional parameters 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 coverage is 55%, so the description must carry some burden. It clarifies category (name-based with fallback) and reminders (offset in days before due date), but says nothing about interval, costVaries, expectedCost, or calculateFrom, leaving several parameters documented only by 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 ('Add') and resource ('item to Due Again'), then defines what an item is ('something that comes due on a date, once or on a schedule') with concrete examples. This clearly separates it from siblings like due_again_complete and due_again_items.

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?

Provides real workflow guidance for the category parameter — give the name and, if it does not match, the reply lists valid categories to choose from. However, it gives no explicit when-to-use vs. alternatives guidance (e.g., when to create vs. look up existing items with due_again_items).

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 give the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real behavioral content on top: the system auto-derives the next due date from the schedule, and the date cannot be in the future. It stops short of saying whether repeat calls create duplicate completion records, which the non-idempotent hint implies but does not confirm.

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 action, then the side effect, then the id provenance and the date constraint. Nothing is padding.

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

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

Covers the action, its automatic side effect, id provenance, and the date bound for a 4-parameter mutation tool with no output schema. Gaps are minor: the cost/note parameters and the expected response are never characterized.

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 only 50% schema coverage, the description carries weight: it establishes itemId provenance (must come from due_again_items) and adds the 'cannot be in the future' constraint on date that the schema's pattern alone does not express. cost and note are still left undocumented in both schema and description, so compensation is partial.

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

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

States a specific verb+resource pair ('Record that a Due Again item was done') and immediately distinguishes itself from due_again_add_item / due_again_history by naming the completion event. 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?

Points the agent to due_again_items as the source of the item id, which is the key prerequisite. It does not explicitly state when not to use it (e.g. vs. due_again_history for viewing past completions), but the completion framing makes the context 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?

With only readOnlyHint=true from annotations, the description does real work by disclosing the shape of the payload — historical events with timestamps and event kinds, and a 'cost' value. That is genuinely additive since no output schema exists, though ordering (oldest vs newest first) and the effect of the limit parameter remain undisclosed.

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

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

A single front-loaded sentence with no filler; the return content is stated up front in a compact colon-list. Slightly terse for a tool whose parameters are undocumented, but 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 two-parameter read tool with no output schema, the description covers what comes back but says nothing about the limit/pagination contract or ordering, which an agent needs to page correctly. Read-only annotations cover the safety profile, so the remaining gap is moderate rather than severe.

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 0%, so the description must compensate and it does not: itemId is only obliquely implied by 'one Due Again item', and 'limit' is never mentioned, leaving its meaning (most recent N? oldest N?) and default of 20 unexplained.

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 names a specific resource — the completion history of one Due Again item — and enumerates the event types it contains (done, skipped, rescheduled) plus a cost field. That is enough to separate it from due_again_items and due_again_complete, though it never states a verb or explicitly contrasts with those siblings.

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

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

Usage is only implied: reading an item's history is the obvious reason to call this, and 'one Due Again item' hints that an itemId must be known in advance. There is no explicit when-to-use, no prerequisite about resolving an itemId via due_again_items first, and no mention of alternatives.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It does add the returned fields (status and next due date), but says nothing about result limits, pagination, or ordering for what could be a long list of recurring items.

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

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

Two sentences, front-loaded with the core purpose and followed by the filtering capability. No filler, no redundancy.

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

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

For a low-complexity, zero-required-parameter read tool with a fully documented schema and readOnlyHint, the description covers purpose, domain, and returned fields. Only pagination/result-size behavior is left unstated.

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 search, status (with its enum), and withinDays are already fully documented, including the note that overdue items are included. The description only restates the status and look-ahead filters and omits the search parameter entirely, so it adds little 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 (List) plus the resource (items in Due Again) and even explains the domain in a parenthetical, so an agent knows it is a read of recurring commitments with status and next due date. It does not explicitly distinguish itself from the nearby due_again_history list tool, which keeps it short of a 5.

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 second sentence ('Filter by status or look ahead a number of days') implies when the filters are useful, but never states when to choose this tool over due_again_history or the mutation siblings. Usage is inferred rather than prescribed, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/non-idempotent profile is covered. The description adds genuinely useful behavior beyond that: fuzzy person-name matching with a fallback reply listing candidates. It does not state what a successful save returns or whether duplicates are allowed.

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

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

Two compact sentences, front-loaded with the action and the person-matching behavior; nothing is wasted. The trailing field list is terse but slightly fragmentary ("Optional link, price, notes and priority").

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 mutation tool with no output schema, the description covers the input surface and the name-mismatch path, which is the most important failure case. It omits the success response shape, duplicate-handling, and any permission context, leaving meaningful gaps.

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 0%, so the description carries the burden, and it names all six fields (idea, person, link, price, notes, priority) plus flags which are optional. It adds no format, length, or enum-value detail beyond the schema, so it stops short of 5.

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

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

States a specific verb and resource ("Save a gift idea") scoped to Gift Keeper and keyed by person name, which separates it from siblings like gift_keeper_people and gift_keeper_upcoming. It does not explicitly name an alternative tool, but the action 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 context is implied (add a gift idea for a known person) and it gives one concrete failure-mode instruction: a non-matching name returns a list of people to choose from. There is no explicit when-to-use-this-vs-siblings guidance or prerequisite statement.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say whether marking is reversible, whether the gift leaves the upcoming list, or why idempotentHint is false (repeat calls may error or duplicate). For a mutation with a notable non-idempotent flag, that is a real 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?

Two short sentences, zero filler, with the action stated first and the parameter-sourcing hint second. 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 one-parameter mutation with no output schema, the description covers the action and where to get the id. It is missing the post-condition (what state the gift ends in) and confirmation of non-idempotent behavior, which an agent would want before retrying a call.

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 0% for the single giftId parameter, so the description must carry the meaning. It does partially compensate by naming the source tool ('gift_keeper_upcoming'), which is genuinely useful for obtaining a valid id, but it says nothing about id format or what an invalid id does.

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: 'Mark a gift in Gift Keeper as given.' An agent can tell it is a state-change on a gift, distinct from siblings like gift_keeper_add_idea or gift_keeper_upcoming. It does not explicitly contrast itself with alternatives, but the action 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?

The second sentence tells the agent where to source the required id ('from gift_keeper_upcoming'), which implies the workflow: pick an upcoming gift, then mark it given. However, it gives no explicit when-to-use condition, no when-not guidance, and no statement about what happens if the gift was already marked.

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 readOnlyHint=true annotation already tells the agent this is a safe read with no side effects, so the description does not need to restate that. It does add useful content transparency by listing the kinds of fields returned, but says nothing about result size, ordering, or what an unknown name yields.

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

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

Two sentences, no filler, with the resource described first and the parameter behavior second. The first sentence is slightly awkwardly phrased ('with what helps choose a gift'), which costs a point but does not obscure the meaning.

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 the resource, the returned fields, and the optional filter. The remaining gap is the absence of any tie-in to the other Gift Keeper tools, which matters given how many siblings share the prefix.

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 0%, so the description carries the entire burden for the single 'name' parameter. It does this well: it states the parameter is optional and that supplying it scopes the result to one person versus returning everyone, which is meaningfully more than the bare schema maxLength constraint.

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 identifies the resource (people in Gift Keeper) and enumerates the attributes it exposes (relationship, interests, sizes, preferences, things to avoid), which makes it clearly distinguishable from siblings like gift_keeper_upcoming or gift_keeper_add_idea. It never uses an explicit verb such as 'list' or 'get', leaving the operation type to be inferred, and it does not name any sibling for contrast.

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 only guidance offered is about the parameter ('give a name for one person, or leave it out for everyone'), which is parameter behavior rather than when-to-use-this-tool guidance. There is no indication of when this is preferable to gift_keeper_upcoming or how it relates to the other Gift Keeper tools.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing the shape of the returned data — who the occasion is for, gift-chosen status, budget, and spend — which is genuinely useful since no output schema exists. It stops short of mentioning sorting, result caps, or date/timezone handling.

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

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

A single well-formed sentence that front-loads the resource and then lists the payload fields. Nothing is padded, though the parenthetical enumeration of occasion types is slightly list-heavy for the amount of information conveyed.

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 compensates by describing the return contents, and the two parameters are fully specified in the schema. Minor gaps remain around ordering, result count, and how 'upcoming' is bounded by default, but an agent has enough 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?

Both parameters (person, withinDays) are fully documented in the schema at 100% coverage, so the schema does the heavy lifting. The description adds no filtering or format detail beyond what the schema already states, so the baseline 3 applies.

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

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

The description names a specific resource (upcoming occasions) and enumerates the occasion types it covers (birthdays, anniversaries, holidays, custom dates), which the agent can map to the Gift Keeper domain. It is clearly distinct from gift_keeper_people, though it never uses an explicit verb like 'list' or 'retrieve' and does not directly contrast itself with any sibling.

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

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

Usage is only implied: an agent can infer this is the tool for looking ahead at coming occasions, but there is no explicit when-to-use or when-not-to-use guidance, and no alternative (e.g. gift_keeper_people) is named for the person-centric 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?

With no annotations, the description carries the full burden, and it does disclose two useful traits: the action launches an external desktop app (a side effect beyond a data read/write) and that consent is required first. It omits other behaviorally relevant facts such as what happens if the app is already open, whether it errors on invalid values, or what the call returns.

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

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

Two short sentences, no filler. The core action leads, and the consent constraint directly follows, so the most decision-relevant information is front-loaded.

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

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

For a one-parameter launcher with no output schema and no nested structures, the description covers the essentials: what it does, the reason to call it, and the consent precondition. A note on idempotency or the already-open case would close the remaining gap.

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 0%, so the description offers no semantics for the single 'app' parameter. However, the parameter is fully constrained by an enum ('due-again', 'gift-keeper') whose values are largely self-describing, which limits the practical gap; the description still never mentions the parameter or what distinguishes the two apps.

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 ('Opens one of the Tiong Creative apps on this Mac') and immediately explains the payoff ('so its tools can be used'). That framing distinguishes it from the sibling app-specific tools (due_again_*, gift_keeper_*), which are only usable after this launcher runs.

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

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

Gives an explicit gating condition: 'Only call this after the user has agreed to open it.' This tells the agent when invoking is permitted. It doesn't spell out the ordering relative to specific siblings (e.g., call this first, then due_again_items), so it stops short of full when/when-not/alternative 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?

With no annotations, the description carries the full burden. It discloses the return content (overdue and due items, each tagged with its app) which is genuinely useful, but says nothing about read-only safety, response shape, item limits, or the meaning of days=0.

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

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

Two tight sentences, zero filler, and the scope statement is front-loaded ahead of the usage cue. Every phrase 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 single-optional-param, read-only aggregation tool with no output schema, the description conveys enough to call it correctly and even sketches the return content. Only minor gaps remain around result limits and the edge case of days=0.

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

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

Schema coverage is 100% and the schema documents days as "How far ahead to look," so the baseline is 3. The description's "within a number of days" restates the schema without adding format or boundary semantics.

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

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

The description states a specific verb+resource: aggregating overdue and due items across the Tiong Creative apps, enriched with the owning app. The cross-app scope implicitly distinguishes it from per-app siblings like due_again_items and gift_keeper_upcoming, though it never names them explicitly.

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

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

"Start here for 'what needs my attention'" gives clear entry-point guidance for the agent. It gives positive usage context but offers no exclusions or explicit alternate routing to the sibling tools.

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