ComingUp Today

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

Annotations already declare non-readOnly, idempotent, non-destructive behavior. The description adds useful behavioral context by indicating ordered batching and dependency on expectedVersion from get_lists, which implies optimistic concurrency, though it does not explain conflict 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 front-loaded sentence with no wasted text. The usage condition and prerequisite are stated immediately.

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

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

Given the rich schema, annotations, and output schema, the description gives enough context to call the tool correctly. It could further explain version-conflict or partial-failure behavior, but the essentials are 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description reinforces the source of listRef and expectedVersion and the ordered-batch nature of labels, but adds little beyond what the schema already 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: append one or more items in one ordered batch. The word 'append' distinguishes it from edit_list_item, remove_list_item, and change_list without ambiguity.

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

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

Gives clear usage context: when appending one or more items in an ordered batch, and explicitly says where to obtain listRef and expectedVersion. It also includes a negative instruction not to call get_list first, though it does not explicitly compare against edit_list_item or change_list.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful lifecycle context ('temporary compatibility tool'), but does not explain optimistic-concurrency failure behavior, what expectedVersion conflicts do, or that removals are excluded here despite the destructive flag.

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 with no filler; the deprecation status and the migration targets are front-loaded before any detail. Every clause carries routing value.

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 an output schema, full schema coverage, and annotations present, the description needs only to orient the agent, which it does well through migration guidance. A small gap remains around version-conflict and idempotent-replay semantics for a destructive legacy mutation, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% and each conditional parameter already states when it is required (name for rename, label for legacy add/edit, checked for set_item_checked). The description adds only the operation routing guidance, which is already largely restated in the operation enum's own description, 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 the specific resource (a list), the specific operations (rename, edit/check an item), and frames itself as a temporary compatibility surface. It immediately distinguishes itself from the modern siblings by naming them, so an agent can route 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 says who should use it (existing clients only) and gives the exact alternatives for each intent: rename_list, edit_list_item, set_list_item_checked for new integrations, add_list_items for additions, remove_list_item for removals. 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety and replay profile is covered. The description adds the deduplication workflow constraint, which is genuinely useful context, but says nothing beyond annotations and schema about duplicate-name behavior or what a successful save 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?

A single sentence with the precondition front-loaded and zero filler. Nothing is repeated from the title or the schema, and the actionable part (check find_contacts first) leads.

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?

An output schema exists and parameter semantics are fully covered by the schema, so the description only needs to carry intent and sequencing, which it does. The remaining gap is the create-vs-update decision boundary, which matters given update_contact is a sibling.

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 every one of the nine parameters, including idempotencyKey and the nested phone/address objects, is already documented in the schema. The description adds no parameter-level meaning, so the 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?

The description names a specific action and resource ('save a reusable contact'), which maps cleanly onto create_contact and distinguishes it from the read-side sibling find_contacts. It is framed as usage rather than a direct 'creates a new contact record' statement, so the create-vs-update distinction against update_contact is left implicit.

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 an explicit trigger condition and prerequisite: only create after find_contacts confirms the contact does not already exist. That is real routing guidance with a named alternative, but it stops short of saying what to do when the contact does exist (update_contact instead), which is the main competing path.

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=false, destructive=false, idempotent=true and openWorld=false, so the safety profile is covered. The description usefully adds the write-scope boundary (ComingUp-owned only, no provider calendar writes), but says nothing about permissions, what happens on replay with a duplicate idempotencyKey beyond the schema's one-liner, or notification side effects.

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

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

Two sentences, no filler, with the usage condition and its exclusion front-loaded before the time-interpretation caveat. Every clause carries information the schema and annotations do not.

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 nested, oneOf-heavy create tool with 8 parameters, an output schema, and rich annotations, the description covers the two things structured data cannot: the ownership boundary and the instant-vs-local time trap. It could go further on permissions or recurrence expectations, but nothing essential for a correct call 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?

At 75% schema coverage the schema does most of the work, but the description contributes a genuinely non-obvious semantic point: startAt/endAt are instants rather than local clock values, which changes how an agent constructs them. The advice to prefer displayTime.label in the household timezone is helpful but references a field absent from this input schema, which risks confusion about where that value comes from.

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 ("create a ComingUp-owned event") and immediately bounds it with a negative scope ("cannot create or write provider calendar events"), which cleanly separates it from write paths that touch external calendars. It stops short of naming the sibling it hands off to, or of distinguishing itself explicitly from update_event/get_event, so it is clear but not fully sibling-differentiated.

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?

"Use this when you need to create a ComingUp-owned event" gives an unambiguous trigger, and the provider-calendar exclusion states when not to use it. It does not point at an alternative tool for the excluded case, leaving the agent to find that path 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 readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond creation scope — it does not mention the idempotency-key replay behavior or what happens on a duplicate name, which would be the highest-value addition for a mutating tool.

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 semicolon-joined sentence with zero filler. The trigger condition comes first and the alternative-tool pointer follows, which is the right ordering for an agent scanning for a match.

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?

An output schema exists, so return values need not be explained, and all parameters are covered by the schema. For a simple three-parameter create tool with full annotations, the only meaningful omission is what the idempotency key buys the caller in practice.

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 all three parameters (name, category, idempotencyKey) are already documented in the schema, including the enum values. The description only echoes the category vocabulary and adds no constraints or format guidance beyond it — 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?

The description names a specific verb and resource ('create a … list') and immediately scopes which kinds exist ('shopping, to-do, or miscellaneous'), which matches the category enum. It distinguishes the tool from the list-write siblings by noting they handle 'later changes', though it does not address the other create_* tools in the family.

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?

'Use this when you need to create a shopping, to-do, or miscellaneous list' gives a positive trigger condition, and the clause 'use focused list-write tools for later changes' rules out using this tool for subsequent edits. No explicit exclusions for e.g. batching or duplicate names, but the create-vs-modify boundary 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and idempotency profile is carried by structured data, and an output schema exists so return values need not be described. The description adds only the create-vs-update distinction and the "private" attribute; it does not explain replay semantics of idempotencyKey, what happens on key collision, or any limits beyond those 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?

A single compact sentence that front-loads the use condition and then the alternative, with no filler or repetition of schema/annotation content. 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 full param coverage, rich annotations and an output schema, the description needs only to establish purpose and routing, which it does. The one residual gap is the unresolved "private note" vs. "household note"/personRefs tension, which an agent could misread when deciding whether to attach people.

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 title, tagNames, personRefs, bodyMarkdown and idempotencyKey all documented in the schema, so the baseline is 3. The description contributes no additional parameter meaning — notably nothing about tag replacement behavior or how personRefs should be sourced — beyond what the schema already states.

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 ("create a private Markdown note") and names the sibling it is not (update_note), so an agent can distinguish it without opening schemas. The only softness is the qualifier "private," which sits oddly against the title "Create Household Note" and against the schema's personRefs/"shown to the household" fields, leaving mild ambiguity about the note's audience.

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 gives a when-to-use condition (creating a note) and a concrete alternative for the other case ("use update_note with a current version for changes"), which correctly implies this tool is for new notes only. It omits prerequisites an agent would want — e.g., that personRefs come from find_contacts and idempotencyKey must be unique per attempt — but the core routing guidance 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 declare non-destructive, idempotent, closed-world write semantics, and the idempotencyKey parameter description covers replay safety. The description's only added behavioral context is the word 'private' (visibility scoping), and it says nothing about what happens on a duplicate key or how the recipe is scoped to the household.

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?

One sentence, zero waste, with the usage trigger front-loaded before the sibling redirect. Nothing is repeated from the schema or annotations.

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?

An output schema exists, so return values need no explanation, and full schema coverage removes the parameter-documentation burden. What remains thin is mutation behavior — visibility scope, household-wide effect, and duplicate-key outcome — which matters for a 10-parameter write 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 all 10 parameters including the required idempotencyKey are already documented in the schema; baseline 3 applies. The phrase 'with a current version' hints at entity versioning that no parameter in this schema exposes, but it does not clarify any of this tool's own inputs.

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 and resource: 'save a private structured recipe'. It also differentiates from the sibling update_recipe, so an agent can choose between create and update 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?

Explicit when-to-use trigger ('use this when you need to save...') paired with the named alternative ('use update_recipe with a current version for changes'). The create-vs-update decision is fully routed.

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 that the tool is destructive, idempotent, and not read-only. The description adds useful workflow context about obtaining listItemRef and using the current list version, but it does not add much behavioral detail beyond that.

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

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

The description is a single front-loaded sentence with no wasted text. It gives the primary use case first and then the key reference/version prerequisite.

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

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

Given the full parameter schema, rich annotations, and an output schema, the description provides enough context for correct invocation. It could be slightly stronger by clarifying version-conflict behavior or explicitly noting that only the label text changes.

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 five parameters thoroughly. The description reinforces where listItemRef comes from and the need for the current list version, but it adds little semantic detail 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 and resource: changing the text of an existing list item. This clearly distinguishes the tool from siblings such as add_list_items, remove_list_item, and set_list_item_checked.

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 says when to use the tool: when you need to change an existing list item's text. It also gives prerequisite guidance for obtaining listItemRef and the current list version, though it does not name alternatives or exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful notion that results are 'reusable' and can be passed along as references, but says nothing about matching semantics, result limits, or behavior on zero matches.

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?

One front-loaded sentence with no filler. The phrase 'attaching a returned reference' is slightly jargon-y but earns its place by describing the downstream use of results.

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 an output schema present, return values need no explanation, and parameters are fully documented in the schema. What remains thin is behavioral fidelity around matching and scoping, so it is not fully complete but is adequate for a simple 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 (query, limit) are fully documented in the schema. The description adds no additional syntax, matching rules, or defaulting guidance beyond that, making the 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?

States a specific verb and resource ('search reusable contacts') in plain terms. However, it doesn't clarify the 'household' scope implied by the title, nor how it differs from contact-related siblings beyond an implicit reference to creating one.

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 concrete triggering condition: search before creating a contact, or before attaching a returned reference. It stops short of naming the alternative (create_contact) explicitly or stating when not to use it, but the intended call moment 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context — that results can be truncated and that displayTime.label should be preferred for timed events in the household timezone while startAt/endAt are UTC-style instants. However, it says nothing about result ordering, default limit, or what a truncated response looks like.

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 front-loaded sentences with no filler; the 'Use this when' condition leads and the timezone caveat follows. The second clause of sentence one ('narrow a truncated result') is slightly compressed but still 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 7-parameter, zero-required, read-only search tool with a full output schema and complete annotations, the description covers purpose, trigger conditions, and the main interpretation pitfall (timezone handling). Only minor gaps remain around pagination/truncation mechanics, which are partly covered by the limit parameter in the schema.

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 every parameter is already documented (patterns, lengths, date formats), which sets the baseline at 3. The description gestures at the searchable facets but does not map them to specific parameters or clarify interactions such as query vs locationQuery or startDate vs endDateExclusive.

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 (search/find) and resource (events) plus the dimensions searchable — text, person, contact, date. It does not explicitly distinguish itself from siblings like get_event or get_schedule, but the resource+verb combination makes the function clear.

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?

Opens with an explicit 'Use this when...' clause and adds a concrete workflow condition ('narrow a truncated result'), which tells the agent when this tool is the right follow-up call. No exclusions or named alternatives (e.g., use get_event for a single known event), which keeps it at 4 rather than 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, closed-world behavior, so the safety profile is covered. The description contributes one genuinely non-obvious behavioral fact — results are lightweight note references requiring a follow-up get_note — but says nothing about limits, matching scope, or empty-result behavior.

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

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

A single sentence with the usage trigger front-loaded and the follow-up action second; every clause earns its place with 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 read-only search tool with a complete schema, rich annotations, and an output schema, the definition covers the essential decision (search here, fetch content via get_note). It is close to complete; only the fact that matching spans titles and content, or the tag/person filter affordances, are left entirely to the schema.

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 all four parameters documented (limit, query, tagNames, personRef), so the schema carries parameter meaning. The description adds no syntax, defaults, or combination semantics beyond that, which is the expected baseline when coverage is complete.

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 (search) and resource (private notes), and explicitly contrasts with get_note for full content, so the agent can distinguish it from that sibling. It does not hint at the available filter dimensions (query, tags, person), which would have sharpened the purpose further.

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 condition for use ('when you need to search private notes') and names the follow-up alternative ('get_note with its returned note reference'). It stops short of explicit when-not guidance, e.g. that public content belongs to search_public_product_content.

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 genuinely new behavioral context: results are truncated, and narrowing the query is the remedy, with get_recipe as the drill-down path. It doesn't quantify the truncation limit, which the schema's limit max=50 only partially clarifies.

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 compact sentence that front-loads the trigger and packs in the truncation caveat and the follow-on tool. 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description supplies the one non-obvious workflow fact (truncation, then narrow, then get_recipe), leaving only minor gaps like result ordering.

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 query and limit are already documented in the schema, establishing a baseline of 3. The description's 'narrow a truncated result' hints that query is the narrowing lever but adds no syntax, matching rules, or limit guidance 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: searching private recipes, and names the detail-fetch sibling get_recipe. The 'private' qualifier implicitly distinguishes it from the public-content search sibling, though it doesn't name that sibling 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?

'Use this when you need to search private recipes' gives a clear trigger, and 'then use get_recipe for details' names the follow-on alternative. It also tells the agent what to do when results are truncated. No explicit when-not-to-use guidance, so not 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds genuine value by disclosing that large details are truncated and that provider events are immutable. The displayTime.label vs startAt/endAt guidance is real response-interpretation context beyond what annotations 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?

Two sentences, no filler, and the selection condition is front-loaded. Slight inefficiency in that the opening clause states usage rather than purpose, pushing the actual tool behavior to the reader's inference.

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 an output schema present, the description needn't enumerate return fields, and it does cover the tricky interpretation cases (truncation, timezone/instant distinction, provider read-only). The remaining gap is sibling disambiguation against find_events and get_schedule, which a 2-param getter would benefit from.

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

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

Schema coverage is 100% and both eventRef and occurrenceRef are documented in the schema with patterns, so the baseline is 3. The description adds nothing about the two parameters — notably it never mentions occurrenceRef or that eventRef is required, so it does not supplement 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?

The description frames the tool by need ('when you need one event occurrence') rather than stating a verb and resource, so the actual operation (fetch a single event by reference) is only implied. It does distinguish singular occurrence retrieval from the list-oriented siblings like find_events or get_schedule, but only implicitly and without naming them.

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?

'Use this when you need one event occurrence' gives a positive selection condition, and the displayTime note steers interpretation for timed events. However, no alternatives are named (find_events, get_schedule) and there are no explicit exclusions, leaving the agent to infer when not to use it.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful extra context: large results disclose truncation and can be narrowed by name, which helps the agent anticipate result size and pagination-like behavior.

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

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

One compact sentence. The usage condition is front-loaded, and the truncation/narrowing behavior follows without wasted words.

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?

An output schema exists, so return values need not be explained. The description covers when to use it and one important behavioral trait (truncation), though it could say more about what 'active household and people' includes.

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 single nameQuery parameter is already documented. The description adds only a small amount of meaning by noting that narrowing by name helps with large results, so 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 the resource precisely ('the active household and people'), which is more specific than the title alone. It does not explicitly distinguish itself from siblings like get_user_context, so it stops 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?

'Use this when you need the active household and people' gives a clear triggering condition. It names no alternatives or exclusions, so it is not a full when/when-not guide.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is well covered. The description adds a usage caution but little additional behavioral context beyond what the annotations provide.

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

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

The description is a single tight sentence with the positive use case front-loaded and the exclusion immediately after. There is no redundant or wasted text.

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 one parameter, full schema coverage, rich annotations, and an output schema, the description needs only clarify when to use the tool. It does that well, though it could more explicitly distinguish this single-list read from get_lists.

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 single listRef parameter is already documented as an opaque list reference returned by ComingUp. The description adds no parameter-level detail, which is acceptable given the complete 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?

The description indicates the tool is used when existing item details or listItemRef values are needed, implying a read of list contents. It distinguishes itself from appending items, though it does not explicitly say it returns a single household list's details or name the get_lists 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?

It gives a clear use case ('when existing item details or listItemRef values are needed') and an explicit exclusion ('do not call it merely to append items'). It does not name the alternative tool, but the exclusion points clearly away from add_list_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?

The annotations already declare the tool as read-only, idempotent, non-destructive, and closed-world. The description adds valuable context beyond that: the output is used as input to list-write tools, and it returns the current version. It does not describe output shape in detail, but the output schema covers that.

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 efficient sentence with a semicolon separates the primary use from the alternative. The most important point, locating the list and retrieving its reference, 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?

With no parameters, rich annotations, and an output schema, the description provides all the extra guidance needed: why to call it, what it returns conceptually, and when to use the sibling instead. 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?

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for zero params is 4, and the description does not introduce confusing or extraneous parameter guidance.

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 action and resource: locating a list and retrieving the listRef and current version. It explicitly differentiates itself from the sibling get_list by saying get_list is only for item details or listItemRef values.

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 states exactly when to call this tool (to get the listRef and version needed by list-write tools) and when to prefer the alternative get_list (only when item details or listItemRef values are needed). No ambiguity remains.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the self-scoped ('their own') access boundary, which is useful beyond the annotations, but says nothing about result ordering, page size behavior, or what the returned report bundles contain.

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 conditional trigger comes first and the covered content list follows. It is slightly list-heavy but every clause identifies content the tool returns.

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

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

The output schema exists, so return-value explanation is not required, and the annotation set is rich. The remaining gap is significant: for a four-parameter, zero-coverage schema the description should tell the agent how to page and filter, and it does not.

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 four parameters (limit, cursor, status, reportRef), so the description carries the full burden — yet it never mentions pagination, the default/max of 10, the status filter, or that reportRef pins a single report. Only the vague notions of 'ticket status' and 'recent' hint at two of the four parameters.

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 ('review') and a specific resource scope ('their own recent ComingUp support reports'), plus the sub-content covered (ticket status, public responses, issue-pattern/incident status). It is distinguishable from the write-side sibling submit_support_report, though the sibling is not named explicitly.

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

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

The 'Use this when the signed-in user wants to...' framing gives a clear triggering condition and implicitly bounds it to the authenticated user's own data. It does not name alternatives or state exclusions (e.g., what to use for reports belonging to other users, or for submitting a report).

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 behavior, and closed-world scope, so the safety profile is covered. The description adds only the privacy aspect and the prerequisite of an opaque reference, without discussing invalid references, authorization, or retrieval failures.

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

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

The description is a single front-loaded sentence with no wasted text. The use condition and prerequisite reference are stated immediately and clearly.

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

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

For a simple single-parameter read tool with rich annotations and an output schema, the description is sufficiently complete. It explains the retrieval context and privacy scope; error behavior and return shape are reasonably delegated to annotations and the output schema.

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 single parameter is already described as an opaque note reference returned by ComingUp. The description reinforces that it is an opaque reference but adds no syntax, format, or validation detail beyond 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?

The description clearly frames the tool as retrieving a single private note's full content, and the name/title reinforce the verb-resource pair. It implicitly distinguishes itself from find_notes by requiring an already-obtained note reference, though it does not explicitly name that 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?

It gives a clear use condition: when you need one private note's full content after obtaining its opaque reference. The prerequisite of having a reference is useful, but it does not explicitly state when not to use it or name find_notes 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds only one real signal — that this returns the *complete* content rather than the snippet a search would yield — but says nothing about behavior when a slug is unpublished or missing, caching, or response size.

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 the condition first and the resource second; no filler, no restating of 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 only two fully-documented required parameters, rich annotations, and an output schema describing return values, the description covers what an agent needs to select and call the tool. The remaining gap — error/not-found behavior and the search-to-fetch workflow being only implied — is minor at this complexity.

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 enum of content kinds is documented inline, so the schema carries the load. The description adds marginal value by indicating the slug is 'stable' and originates from a search result, which hints at where to source the value, but no format or matching nuances beyond that.

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 ('complete published public content') scoped to a single item identified by slug and content kind. The retrieval verb is implicit rather than stated, but combined with the tool name an agent can tell it apart from search_public_product_content (search vs. fetch-by-slug).

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?

'Use this when you need the complete published public content for one search result' gives a clear usage trigger and, via 'one search result', implies the follow-up relationship to the search tool. It stops short of explicitly naming search_public_product_content as the prerequisite or stating when not to use it.

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

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

The annotations already cover read-only, idempotent, non-destructive semantics, and the description adds a trait the annotations cannot express: large fields and collections are shortened in the response. That truncation caveat is real behavioral value, though it is not quantified (what size triggers shortening, which fields).

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

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

One sentence, front-loaded with the usage trigger, with the truncation caveat attached rather than buried. Slightly awkward phrasing ('explicitly shortened') but no padding or 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?

An output schema is present, so return values need not be explained, annotations cover the safety profile, and the schema fully documents the lone parameter. The description's remaining burden — disclosing that payloads may be truncated — is met.

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 recipeRef parameter is fully documented (opaque reference, rcp_ pattern) in the schema itself. The description adds no additional semantics about the parameter, 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 the resource and cardinality precisely: retrieve a single private recipe, which separates it from the plural find_recipes sibling. It never names the alternative explicitly, so differentiation is implied by 'one' 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?

'Use this when you need one private recipe' gives a positive trigger condition but no exclusions or prerequisites (e.g., 'not for searching — use find_recipes'). Without the qualifier that the ref must come from a prior list/search call, the agent must infer the workflow.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds valuable non-obvious traits: dense ranges produce explicit truncation guidance and can be retried with a smaller range, and timed events expose displayTime.label in household timezone while startAt/endAt are instants. This meaningfully helps an agent interpret results and handle 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?

The response is two sentences and front-loads the usage trigger before operational caveats. The second sentence is slightly dense, bundling timezone guidance and time-value semantics, but every clause carries useful information without repetition.

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 an output schema present, the description needn't explain return values, and annotations cover safety. Combined with fully documented parameters, the added truncation and timezone semantics make the definition largely complete for correct invocation, though sibling differentiation remains a 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 coverage is 100%: both startDate and endDateExclusive are documented, including the exclusive boundary semantics and YYYY-MM-DD pattern. The description confirms date-range filtering but adds no syntax or boundary details beyond the schema, so 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?

The description clearly states the resource (household events) and scope (a date range), so an agent knows this is a filtered schedule lookup. However, it never names or distinguishes itself from the close sibling find_events, which also appears to retrieve events, leaving ambiguity about which tool to pick.

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 a direct usage trigger ('Use this when you need household events in a date range') and adds operational guidance for dense ranges (expect truncation, retry with a smaller range). It stops short of naming alternatives like find_events or stating when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without description help. The description adds genuine non-annotation value: a recommended call-ordering ('use this first') and a hard scope boundary against household content, which is behavior an agent cannot derive from the annotations. It omits anything about what the response contains, but an output schema exists to carry that.

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 sentence with the actionable instruction front-loaded and zero filler, which suits a zero-argument context tool. The clause list is long and reads as a run-on, slightly diluting the priority of 'use this first.'

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

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

With an output schema present, no parameters, and complete annotations, the description only needs to establish scope and trigger conditions, which it does. The one remaining gap is that it never says whose context is returned or under what auth assumptions (current authenticated user), leaving a small ambiguity for a troubleshooting entry point.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly adds no parameter noise, though it also does not clarify that no arguments are needed (e.g., that context is derived from the authenticated caller).

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 enumerates the domains the tool covers (sign-in, permissions, plan access, household availability, feature availability, calendar connection status), which effectively conveys that it returns account-level context, and it explicitly excludes household content. It never states a plain verb+resource like 'returns account context for the current user,' so the agent must infer the resource from the name and the enumerated topics.

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?

'Use this first when troubleshooting...' gives an explicit priority and trigger conditions, and '—not household content' explicitly carves out the exclusion, which routes the agent toward get_household. It stops short of naming the alternative sibling tools (get_household, get_my_support_reports) by name, so the routing is inferential 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 already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still earns credit by adding two facts not in annotations: the removal is permanent/irreversible, and it cannot cascade to the parent list. It does not address the expectedVersion conflict behavior, leaving that to 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?

A single sentence with the use-case trigger front-loaded and the scope caveat trailing it. Nothing is redundant or padded.

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 a fully documented schema, an output schema, and rich annotations, the description covers purpose, permanence, and scope limitation adequately. It leaves conditional-parameter nuance (listItemRef required only in item mode) and concurrency handling entirely to the schema, which is acceptable 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 explains mode, listRef, listItemRef, idempotencyKey and expectedVersion. The description only echoes the two modes at a high level and adds no format, precedence, or conditional-requirement detail beyond what the schema states.

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 ("permanently remove an item or clear completed items") and adds a scope boundary ("never deletes a list") that separates it from list-level siblings like change_list or rename_list. It does not explicitly differentiate from edit_list_item or set_list_item_checked, which are the closest neighbors, so it falls 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?

"Use this when you need to permanently remove an item or clear completed items" gives a clear trigger condition covering both enum modes. The clause "it never deletes a list" rules out one mis-invocation. No alternative tool is named for the edit-vs-remove decision, so no explicit exclusions beyond that.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered elsewhere. The description adds workflow context by telling the agent to obtain listRef and expectedVersion from get_lists. It does not explain the consequence of a stale expectedVersion or what the rename overwrites, which would be valuable for a destructive mutation.

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 compact sentence carries the purpose and prerequisite workflow with no wasted words. The usage condition is front-loaded and immediately actionable.

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

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

The tool has a full output schema and rich annotations, reducing the description's burden. The description supplies the key prerequisite that listRef and expectedVersion come from get_lists. It could be more complete by explaining optimistic-concurrency failure behavior, but it is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by identifying get_lists as the source for listRef and expectedVersion. It does not mention idempotencyKey or name semantics, but the schema already documents those clearly.

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

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

The description uses a specific verb and resource: 'rename an existing household list'. This lets an agent distinguish it from create_list or get_lists. However, it does not explicitly differentiate it from the sibling change_list, which may also mutate list properties, so it falls short of full sibling differentiation.

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 phrase 'Use this when you need to rename an existing household list' gives clear context for when to invoke the tool. It also names get_lists as the source for listRef and expectedVersion, which is useful prerequisite guidance. It lacks explicit when-not-to-use conditions or an alternative-tool comparison.

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 and openWorldHint=false, so the safety profile needs no restating. The description contributes only the word 'published', implying unreleased/private content is excluded — a useful but thin addition, with no mention of ranking, matching behavior, or empty-result 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 sentence with the use condition front-loaded and zero filler. Every clause maps to a distinct content need the agent might have.

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 an output schema, full parameter documentation and rich annotations, the description only needs to route the agent, and it largely does. The one real gap is that it never positions itself against get_public_product_content, leaving the agent to guess which retriever fits.

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%, with the enum, min/max limit and query length all documented in the schema, so the baseline of 3 applies. The description's enumeration of content topics loosely corresponds to the `kind` enum values but omits 'claim' and adds nothing about matching or limit 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 names the exact resource domain — published ComingUp product docs, integration/MCP setup, troubleshooting, FAQs, support guidance — so the agent knows what corpus is being searched. It never explicitly says this is a keyword search (the reader infers it from the name) and it does not distinguish itself from the sibling get_public_product_content, which retrieves similar content by another mechanism.

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 opens with an explicit trigger ('Use this when you need...') followed by five concrete content needs, which is clear positive guidance. There are no exclusions and no reference to the sibling retriever, so the agent is not told when to prefer this over get_public_product_content.

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 destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value by tying the call to the current list version, which hints at the optimistic-concurrency check behind expectedVersion. It does not discuss what a failed version match does, which keeps it below 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?

One compact sentence, with the usage condition front-loaded and the prerequisite data-sourcing guidance trailing. Nothing is wasted, though the semicolon packing of two distinct ideas slightly reduces scannability.

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 an output schema, full parameter coverage and rich annotations, the description covers what an agent needs: the action, the trigger, and where to obtain the required refs and version. The one gap is that it does not warn that other writers invalidate the version, so a retry needs a fresh read.

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 every parameter is documented in the schema itself and the baseline is 3. The description only loosely restates provenance for listItemRef and expectedVersion ('get listItemRef from get_list and use the current list version'), adding little beyond the schema's own notes.

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: 'mark a list item complete or incomplete.' That is unambiguous and distinguishable from siblings like add_list_items or remove_list_item, though it never names edit_list_item, the closest alternative for item-level changes.

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?

'Use this when you need to mark a list item complete or incomplete' gives a clear triggering condition, and the second clause supplies the prerequisite workflow (get listItemRef from get_list, use the current list version). It stops short of stating when to use edit_list_item or remove_list_item instead.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is structured. The description adds genuine context beyond that: a strictly sanitized diagnostic snapshot is attached automatically, the submission is private and internal only, and the user must be signed in. It stops short of noting rate limiting or that a submitted report cannot be withdrawn or edited, which the schema's SUPPORT_REPORT_RATE_LIMITED code hints exists.

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 tightly written sentences with no filler. The usage trigger and the privacy/no-side-effects constraints are front-loaded, and every clause carries information an agent would otherwise have to guess.

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

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

The output schema and annotations relieve the description of return-value and safety detail, and it covers the privacy and diagnostic-snapshot behavior well. But with 9 parameters at 11% schema description coverage, an agent still lacks guidance on how to populate the majority of required and optional fields, which is a meaningful completeness gap for a data-collection 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 only 11% — only idempotencyKey is documented. The description mentions issue kinds that correspond to the category enum, but it says nothing about affectedArea, the summary-vs-description split, attemptedTool, reproductionSteps, expectedBehavior, or observedPublicErrorCode. For a 9-parameter submission tool, the description leaves most field semantics to the bare types and enums.

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: it privately creates an internal ComingUp support ticket for a support issue. It also explicitly scopes the kinds of issues covered (bug, connection problem, unexpected behavior, data problem, feature request, other), which maps directly onto the category enum, so an agent can immediately distinguish this from sibling tools like get_my_support_reports.

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

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

Gives an explicit trigger condition ("Use this after reasonable troubleshooting when the signed-in user asks to privately submit...") and explicit exclusions ("does not send email, create a public issue, or contact a third party"). The agent knows both when to call it and what alternative paths it is not.

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 idempotentHint=true and destructiveHint=true, so the description earns credit for flagging that the contact itself is never removed and for tying the call to a versioned read. However, it omits the most consequential behavior for a 'destructive' mutation: that supplied phones and addresses replace the entire collection, which appears only in the schema. That tension with destructiveHint=true is resolved by the schema, not the description.

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, both front-loaded: the action and its prerequisite come first, the limit second. No restatement of the title or 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?

An output schema exists so return values need no explanation, and annotations cover safety and idempotency. But for a version-guarded mutation, the description never says what happens on an expectedVersion mismatch, nor does it warn that phones/addresses are wholesale replacements—the two facts an agent most needs before calling.

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%, including per-field descriptions and the note that omitted fields stay unchanged while collections are replaced, so the baseline is 3. The description's mention of 'its current version' echoes expectedVersion's own schema text about find_contacts rather than adding syntax, conflict, or retry 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?

States a specific verb and resource ('update an existing reusable household contact') and scopes it with the precondition that find_contacts supplies the current version, which cleanly separates it from create_contact and find_contacts in the sibling list. It also declares a hard boundary ('cannot delete the contact'), so the agent knows this is a modify-only path.

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 entry point ('after find_contacts returns its current version'), which tells the agent it must read before writing rather than guessing a contactRef. It also rules out deletion, but never names the tool that would handle removal, so the exclusion is stated without a forwarding 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 declare non-read-only, destructive, idempotent, and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the change must be against the current version (concurrency guard) and provider-owned events are off-limits. The phrase "cannot delete" is about the event resource itself and is not strictly contradicted by destructiveHint=true (which covers overwriting fields), but the interplay is left for the agent to infer.

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 dense sentences, front-loaded with the usage condition, then the time-handling caveat. No filler, though the second sentence packs two distinct ideas (timezone labeling and instant semantics) that an agent parsing quickly must disentangle.

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 a rich schema and an output schema present, the description need not restate fields or returns. It covers scope, concurrency, and time interpretation, which are the highest-risk gaps for a 6-parameter mutation with nested objects. Error handling for a version mismatch and the replace-vs-merge nature of the change sets are only in the schema, but the essentials for a correct call are 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 the baseline is 3; the description earns above that by clarifying expectedVersion semantics (must match the current version from a read) and the timed-event time semantics (startAt/endAt are instants with offset, not local clock values, and displayTime.label is the household-timezone representation). That last point references a read-side field not in this schema and would otherwise be easy to get wrong.

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 (change) and resource (ComingUp-owned event or occurrence) and immediately bounds scope: it cannot delete or write provider events. That distinguishes it cleanly from create_event, get_event, and the read-side siblings in a crowded tool 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?

"Use this when you need to change ... with its current version" plus the explicit exclusion of provider events and deletion gives real when-to-use guidance. It stops short of naming the sibling to use instead (e.g. create_event for new events, get_event to fetch expectedVersion), so the routing is implied rather than 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 already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is carried structurally. The description adds that a returned reference and current version are needed (an optimistic-concurrency requirement). It omits that fields like people and tagNames replace the existing set, which is the actual destructive behavior, and "cannot delete notes" mildly understates the destructive profile.

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 and the usage trigger first. It is arguably too terse for a seven-parameter destructive mutation, 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?

The tool has 7 parameters, a populated output schema and full annotation coverage, so the description needn't restate return values. Its real gap is update semantics: an agent cannot tell from the description whether omitted fields are preserved or cleared, which is essential before calling a destructive update.

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 every parameter is already documented, including the replace-set semantics of people and tagNames and the idempotency key. The description only echoes that a reference and version are needed, adding no format or conflict-handling 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 ("change a private note") and identifies the two handles required to do so (reference + current version). "It cannot delete notes" implicitly separates it from removal semantics, but no sibling tool is named 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?

"Use this when you need to change a private note" gives a usable trigger, and the description notes the no-delete limitation. However, it names no alternatives (create_note, get_note, find_notes) and gives no guidance on when to read first or when to prefer creation.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds useful scope information by stating the operation cannot delete or publish and that a current version is required. It stops short of explaining what happens on a version mismatch (conflict/rejection) or that field sets like ingredients and personRefs are replaced wholesale, which matters for a destructive update.

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 beginning with "Use this when" that packs the trigger, the preconditions, and the exclusion with no filler. Nothing could be removed without losing information.

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

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

With annotations covering idempotency and destructiveness, a full output schema, and 100% parameter coverage in the schema, the description only needs to frame intent and scope, which it does. The one gap is patch semantics — whether omitted fields are preserved and whether list fields are replaced — which is left to the nested schema descriptions.

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

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

Schema description coverage is 100% and every parameter is individually documented, including expectedVersion and idempotencyKey semantics, so the schema carries the burden. The description only gestures at recipeRef and expectedVersion ("returned reference and current version") without adding format or failure behavior beyond what the schema already says.

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 ("change a private recipe") and bounds the scope with "it cannot delete or publish", which separates it from creation or removal semantics. It doesn't name any sibling (create_recipe, get_recipe, update_note) to differentiate itself explicitly, so it stops 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?

"Use this when you need to change a private recipe" plus the requirement of a "returned reference and current version" gives a clear precondition for calling it, and "cannot delete or publish" declares an exclusion. No alternative tool is named for the cases it excludes, so it is context without routing.

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