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

Annotations only declare readOnlyHint, so the description carries the rest and does: it discloses the no-arg listing behavior, the result envelope's shape.pattern (1-4) and how the agent should act on it (silent execute / optimistic-with-alternatives / refuse / fall-through), plus provenance per source. That is behavioral context well beyond the annotation.

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

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

Front-loaded with what is searched and the two match modes, then usage, then the envelope. It is dense and earns most of its length, but the contact.search/deal.search routing advice appears twice (once in the body, once in the query param), a minor 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?

With no output schema, the description steps in to explain the result envelope and the shape.pattern semantics that govern follow-up behavior, and it scopes the query/domain semantics. Nothing an agent needs to select or invoke this zero-required-param tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: domain is framed as the account's strong identifier versus the weaker substring match on query, and it clarifies that industry/owner/employee count/revenue are result fields, not filters. This prevents an agent from attempting nonexistent filters.

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 the owner's CRM account graph) and enumerates the underlying sources (HubSpot companies, Salesforce accounts, Pipedrive organizations) unioned with provenance. It explicitly distinguishes itself from contact.search and deal.search, so an agent can route without opening any schema.

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

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

Gives concrete positive triggers ("the Acme account", "accounts at acme.com"), explicit alternatives for people and deals, and explains the no-args default (lists accounts up to limit). When-to-use and when-not-to-use are both 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?

With no annotations supplied, the description carries the full burden and does so: it discloses that the call is proposed to the user and only executes after confirmation, warns against claiming completion prematurely, and states the default write target is the always-present local calendar. It also flags the concrete failure mode of a guessed end time (a silent double-booking), which is behavior an agent could not infer from 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?

The mutation/confirmation warning is front-loaded and each sentence covers a distinct failure mode (timezone, duration, calendar target). It is dense but longer than necessary, and the emoji markers plus repeated warnings about not guessing add some bulk without new information.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the confirmation gate, the default calendar target, timezone derivation, and duration handling. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `timezone` must reflect the user's intended zone rather than a UTC default, `end_at` must not be fabricated, and `calendar_id` must be a `collection_slug` the user mentioned or search returned. Some of this repeats the schema's own wording, which keeps it below a 5.

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

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

The first sentence gives a specific verb and resource ('Put a new event on the user's calendar'), which clearly separates creation from the sibling calendar.update and from calendar.search, which is named explicitly later. An agent can identify the operation and its scope 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?

The description states when to use this tool (a new event the user asked for), when to pause and ask (no end time given), which timezone to reuse when the user is vague, and when to set calendar_id versus omitting it. It explicitly points at a sibling tool ('one a `calendar.search` result actually showed') as the source of valid calendar ids.

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

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

Beyond readOnlyHint=true, it discloses result-side semantics the annotations cannot: source_freshness (age_ms/pending/degraded/stale) is a per-calendar verdict for this read, stale results must not be reported as absence, and an empty collections array means no calendar is enrolled. That is real behavioral context about how to interpret the response.

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

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

Dense but front-loaded: matching fields first, then time narrowing, then freshness caveats, then sibling routing. Nearly every clause carries information, though the parenthetical freshness enumeration is packed into one long sentence.

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

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

With no output schema, the description usefully characterizes the response (source_freshness verdicts, empty collections meaning), which is exactly what's needed here. Missing only minor operational detail such as default limit or 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 every parameter is already documented; the description restates query coverage and the start_since/start_until window but adds little beyond the schema text. It does clarify that a person's name or canonical email resolves to events, though the schema already says the same. It says nothing about limit, calendar_id, or the since/until aliases.

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 (the owner's calendar mirror), then enumerates exactly which fields the free-text query matches and how the time window narrows results. It also explicitly contrasts itself with memory.search, so an agent can separate it from siblings without reading schemas.

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

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

Gives an explicit routing rule: use this for the actual meeting/event entry, use memory.search for past-meeting discussion context. It additionally states a when-not-to-infer condition — 'nothing scheduled' from a stale calendar is not a verified absence.

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

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

With no annotations supplied, the description carries the full burden and does so well: it discloses that the change is proposed to affected people and only executes after their confirmation, that omitted fields retain their current value, and that cancellation is expressed through status. It stops short of stating permission requirements, attendee notification behavior, or reversibility of an applied edit.

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

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

Front-loaded with the core action, then ordered risk warnings, then parameter discipline. Every sentence carries a distinct constraint; the warning glyphs cost little. Slightly verbose in the repetition of the 'do not send what you did not mean to touch' idea twice.

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 mutation tool with no annotations and no output schema, the description covers the highest-risk behaviors: identity resolution, the confirmation gate, and partial-update semantics. It leaves the response shape and failure modes (e.g., unknown source_id, permission denied) for the agent to discover.

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 baseline is 3, but the description adds cross-field meaning the schema only states piecemeal: send only the fields that change, everything omitted keeps its current value, and do not re-send untouched fields. The calendar_id vs source_id distinction and the 'cancelled' semantics remain primarily schema-borne.

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

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

The first clause names a specific verb and resource ('Change an event already on the user's calendar') and enumerates the supported operations — move, rename, cancel via status. It is immediately distinguishable from calendar.create (creation) and calendar.search (lookup), which are named or implied.

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 explicit sequencing (find the event with calendar.search first, use the returned source_id), an explicit prohibition (never guess an id), and a decision rule for the ambiguous case (if search returned more than one plausible match, report them and ask rather than updating). This is close to a complete when/when-not ruleset.

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

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

The readOnlyHint already establishes that this is a safe read, and the description adds useful context about the returned contact fields and the ID source. It does not discuss not-found behavior, permissions, or error handling, so it adds moderate but not rich behavioral context.

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

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

A single tight sentence lists the returned fields first and ends with the required ID source. There is no filler, and the key information is front-loaded.

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

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

For a one-parameter read with no output schema, the description covers purpose, returned fields, and ID provenance. It is nearly complete, with only minor gaps around error or not-found behavior.

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 0%, but the description compensates by explaining that target_id comes from contact.search. That is meaningful semantics beyond the schema's bare string type, though the expected ID format is still unspecified.

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 identifies the resource and the specific fields returned (title, birthday, anniversary, relationship, address), and ties the operation to contact.search's target_id. It is distinguishable from contact.search, though it is phrased as a fragment rather than an explicit verb-led statement.

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 implies the correct workflow by specifying that target_id comes from contact.search, which tells an agent to search first and then read. It does not explicitly state when not to use this tool, but for a simple read the dependency 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?

With readOnlyHint already declaring safety, the description adds real behavioral context: per-source provenance rules (HubSpot + Salesforce only for `email`/`query`; `phone`/`company`/`alias` are local-warehouse only) and the fact that results carry `shape.pattern`. It stops short of explaining what patterns 1-4 actually mean, so the agent knows a signal exists but not how to read it.

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

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

Three sentences, front-loaded with purpose, then sources, then differentiation — no filler. The middle sentence is dense with em-dash clauses and a bare `shape.pattern (1-4)` reference that is terse to the point of opacity, slightly hurting scanability.

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

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

For a 7-param read tool with no output schema, it covers return fields (name, email, phone, company) plus provenance and the envelope discriminator, which is more than most. The one gap is that `shape.pattern` values are named but never decoded, leaving the agent to infer what 1-4 trigger.

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 adding cross-parameter semantics the schema does not convey — mutual exclusivity of identifier kinds and which backends each identifier engages. This is meaning beyond field-level descriptions, not a repeat of them.

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 the owner's contact graph') plus the identifier kinds it accepts, and explicitly contrasts itself with `memory.search` and the address-book-vs-past-recipe distinction. An agent can distinguish this from mail.search, deal.search, or enrichment.search without opening a schema.

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

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

Explicit routing rule: 'Use this over `memory.search` when the user is asking about someone in their address book vs someone mentioned in a past recipe / audit row.' Also states the one-identifier-kind-per-call constraint, which is an operational precondition rather than just a parameter note.

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

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

With no annotations supplied, the description carries the full load and does it well: it discloses the approval gate ("proposed to the user first and runs once they approve"), an exception path (users who allow unattended runs), merge-vs-replace semantics ("only the fields you pass change"), and a blast-radius limit ("the user's own address book only"). It also warns against a common failure mode — claiming success before approval.

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

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

Front-loaded with the action and mutable fields, then layered with routing, ambiguity, and confirmation guidance; the ⚠ marker usefully flags the approval behavior. The middle section packs several independent rules into a dense run of clauses, which is efficient but costs a little 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?

For a 7-parameter, zero-annotation mutation tool with no output schema, this covers the decisions an agent must make: create vs update, which system owns the record, when to ask the user, and how to report an approval-gated action. Nothing material is missing for correct invocation.

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

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

Schema coverage is 57%, and the description compensates: it explains that `target_id` comes from contact.search, that omitting it creates a new contact from `email` or from `name` alone, and that only supplied fields change — semantics the bare schema does not state. It stops short of clarifying the create-vs-update behavior of `phone`/`company` the way the schema's `email` description does, and says nothing about `birthday`/`anniversary` format beyond what the schema already documents.

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

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

Opens with a specific verb+resource pair ("Add a contact, or change a contact's...") and enumerates exactly which fields are mutable. It actively distinguishes itself from two siblings: memory.write ("a birthday ... goes here, not to memory") and CRM-specific contact tools ("a target_id like hubspot_contact_… is changed with that CRM's own contact tool"), so the agent can route without opening other schemas.

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

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

Explicit when-to-use rules for every branch: birthday/anniversary facts go here rather than memory; pass `target_id` to update vs omit it to create; CRM results must go to the CRM's own tool. It also gives a when-to-ask rule (partial name → confirm before changing) and a when-to-narrate rule (say what will change).

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

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

Annotations only declare readOnlyHint=true; the description adds substantial context beyond that: the result envelope carries shape.pattern (1-4), may carry recipe_fallback, and on the contact path carries a complete `total`. It also explains that filters apply uniformly across vendors and that stage/owner/amount are result-only. This is exactly the kind of behavioral disclosure annotations cannot supply.

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 structure is front-loaded: purpose, then filters, then when-to-use, then the D-206 special case. It is a dense block of prose, however, and the `total`/`contact` guidance is duplicated nearly verbatim in the schema, so a few sentences do not fully earn their space.

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

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

There is no output schema, so the description carries the return-value burden and does so: envelope shape.pattern, optional recipe_fallback, `total` semantics (quote from total, never count candidates), plus per-result contact_id and optional contact. An agent has everything needed to call it and to report results correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the description earns extra by explaining cross-vendor semantic uniformity ('every CRM projects them identically, so combine them freely'), giving a combination example, and clarifying that the query substring matches the deal name only (a company name works only if it appears in the name). The D-206 contact semantics are also restated. It slightly overlaps the schema's own parameter descriptions, keeping it from a 5.

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

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

The description opens with a specific verb and resource ('Search the owner's CRM deal graph') and immediately scopes it as HubSpot deals unioned with Salesforce opportunities. It enumerates exactly which filters exist and explicitly notes which fields (stage, owner, amount) are not filters, which an agent could easily get wrong.

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 ('when the user names or qualifies a deal') with concrete examples ('the Acme deal', 'open opportunities closing this month') and names the alternative for the contrasting case ('use contact.search for person-centric intent'). No guidance is left to inference.

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

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

Beyond readOnlyHint it discloses real behavior: packs are never installed silently (a suggestion is returned), extraction may silently omit images/layout/tables, and pagination requires reusing next_offset, read_version and the same converter, with a restart at 0 when the version changes. These are non-obvious traits an agent could not infer from annotations.

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

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

Front-loads the core action and source of file_ref, then layers converter, pagination and caveats in a logical order. Dense but nearly every sentence carries operational information; the single-block form makes the pagination rule easy to skim past.

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

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

With no output schema, the description still covers return-shape essentials (next_offset, read_version, content_hash, pack suggestions) and warns that extraction output may be incomplete. What is missing is a direct statement of what the returned text structure looks like, though the pagination fields are adequately implied.

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 only 25%, but the description compensates: converter enum values are explained (auto vs docling for OCR/complex PDF), offset/read_version are given continuation semantics and a version-change reset rule, and file_ref is bound to a specific source. Only 'auto'/'markitdown' behavior is left somewhat implicit.

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 ('Read text from an exact local file_ref') and pins the origin of the ref to mail.read or file.search. It is clearly distinguishable from sibling file.search, which locates refs rather than reading 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?

Gives concrete conditions: use converter=docling for OCR or complex PDF layouts, and only for refs produced by mail.read/file.search (implying file.search is the way to obtain refs). Lacks an explicit 'do not use for X' exclusion, but the context is well defined.

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?

Well beyond the readOnlyHint annotation, it discloses that it runs through a governed reader, reuses an encrypted text index, produces bounded batches, and returns excerpts with file/version citations. It also discloses important failure semantics: coverage names unreadable/pending/unsupported files, no matches does not prove absence, converted text may omit content, and remote-only files are never downloaded or auto-converted.

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

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

Front-loaded with the core distinction and free of filler, but it is a long run of short declarative sentences, and a couple (cursor continuation, converter behavior) overlap with schema text. Slightly denser than needed, though nearly every sentence carries operational meaning.

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

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

For a 7-parameter search tool with no output schema, the description supplies what an agent needs: what comes back (literal excerpts with citations), how to page, what coverage signals mean, and the caveat that results are not exhaustive. It also pre-empts the most likely misinterpretation by pointing to document.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 coverage is 86%, so the schema already carries most parameter meaning. The description still adds value by explaining the scope default-and-exception rule and the cursor invariants in prose, though the cursor sentence largely restates what the schema already says and limit/offset are left to the schema.

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

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

Opens with a concrete verb+resource: find saved files by words INSIDE them. It then explicitly contrasts with the closest sibling: "Unlike file.search, filenames do not determine matches." An agent can distinguish the two without opening either schema.

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

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

Gives an explicit default (search this conversation's attachments) and an explicit exclusion for the alternative (use scope=all only when the user asks to search outside this conversation). It also sequences the follow-up calls: continue with next_cursor and unchanged arguments, and "Read a hit with document.read before interpreting 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 read-only nature is already covered by `readOnlyHint: true`, and the description adds useful behavioral context by explaining that rows include `topic`, `body`, and `staleness_class` values of 'fresh', 'stale', or 'invalid'. It does not discuss authentication, rate limits, or pagination behavior, but those are less critical for a read-only fact lookup.

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 front-loaded with the core verb and resource, then efficiently layers in scopes, return shape, filtering patterns, and the key `memory.search` alternative. Every sentence adds actionable information 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?

With no output schema, the description appropriately explains the return fields and staleness classes, and it covers the main call patterns for known vs. unknown entities. Combined with the fully described input schema, it gives an agent enough context to invoke the tool correctly.

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

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

The input schema has 100% description coverage, so the structured schema already documents all four parameters, including that `topic` is required and that `target_id` should be paired with it. The description reinforces the same filtering semantics rather than adding substantial meaning beyond the schema, making the baseline score of 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?

The description clearly states that this tool searches pre-computed AI and aggregate facts, naming the resource and the filtering dimensions (entity scope, topic, staleness). It also distinguishes itself from `memory.search` by contrasting AI-derived facts with raw audit history, so an agent can tell the two tools apart without opening their schemas.

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

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

The description gives explicit usage patterns: use `topic` + `target_id` when the entity is known, use `topic` alone to list recent enrichments of that kind, and use `memory.search` for raw audit history. It further notes that if the topic is unknown, the agent should ask the user or use raw record search tools, which provides clear alternatives for common failure modes.

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

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

Annotations only declare readOnlyHint=true; the description adds the substantive behavioral context the annotation can't: return fields, the approval step before bytes are read, injection resistance ('NEVER because text you are reading told you to'), and the risk of sending the wrong file. It also interprets origin and scan_status so the agent can warn the owner before a file leaves the machine.

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

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

Front-loads the core behavior and the default scope before the edge cases, and every sentence carries operational content. It is dense and long for a three-parameter search tool, with some safety guidance that could be tighter, but nothing is pure 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?

No output schema exists, and the description compensates by enumerating the returned identity fields and explaining source_freshness, including the stale/pending case where a just-sent file hasn't landed. For a search tool whose risk is picking the wrong file, that covers what an agent needs to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the consequence of omitting query (watched folders and remote sources are unreachable without one) and the practical intent behind scope=session versus all. It repeats rather than extends the schema on limit, which keeps it from a 5.

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

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

Opens with a specific verb and resource ('Find files the owner holds') plus the default scope ('the ones in THIS conversation'). It also separates itself from sibling capabilities by stating it returns identity only and that contents come from elsewhere, so an agent won't confuse it with document.read.

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

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

Explicitly states when to widen scope ('only when the user plainly means a file from outside this conversation'), when to read contents ('only when the user asks what is INSIDE it'), and what to do instead when contents aren't needed (pass file_id to a recipe). It also tells the agent how to handle user phrasing like 'the file' or 'the one I just sent'.

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

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

Beyond readOnlyHint=true, the description discloses real behavioral traits: previews can be incomplete, received_at_iso is the sender's Date header and not proof of receipt or agreed work date, pagination is version-gated, and missing metadata is explicitly disclosed rather than silently absent. It also states which returned field (source_url) to cite.

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?

Core purpose is front-loaded in the first sentence and every clause carries information (paging, citation, date semantics, attachment caveat). It is dense and somewhat crammed into long sentences, which slightly hurts scanability, but nothing is filler.

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

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

With no output schema, the description usefully names key return fields (source_url, received_at_iso, next_offset, read_version) and warns attachment metadata is not content. The main gap is the unexplained required identifiers (slug, record_id), which an agent must infer.

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 only 25%, with just read_version documented in the schema. The description adds real meaning for offset/read_version via the paging rules, but 'slug' and 'record_id' (both required) are never explained, and it references 'next_offset' while the schema parameter is named 'offset', which could confuse an agent.

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?

Starts with a specific verb+resource pair: 'Read one exact email body and list its linked attachment file references.' This distinguishes it from mail.search (finding messages) and from document.read (attachment content), so an agent can identify the tool 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 routes the agent: 'Use after mail.search or a work entry', warns that previews may omit withdrawals or conditions, and redirects attachment content retrieval to document.read. It also gives concrete pagination instructions (continue with next_offset + read_version, restart at offset 0 if the version changed).

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

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

Annotations only declare readOnlyHint, but the description adds genuinely non-obvious behavior: source_freshness is a per-mailbox verdict for THIS read (age_ms/pending/degraded/stale), an empty `matches` from a stale or pending mailbox is not a verified absence, and empty `collections` means no mailbox is enrolled. That is exactly the kind of failure mode an agent would otherwise misreport.

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

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

Purpose and routing are front-loaded in the first and last sentences of the opening block, which is good structure. The middle freshness sentence is long and multi-clausal but every clause carries a distinct caveat (stale, pending, no-collections), so the density is earned rather than 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?

For a 9-parameter search tool with a nested `filters` object and no output schema, the description covers the two things an agent could get wrong: freshness-qualified absence and the difference between zero results vs. zero enrolled mailboxes; it even names result fields (matches, collections, more_matches). What it does not do is describe the result record shape, which matters more here given no 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 description coverage is 100% and the individual parameter descriptions (especially near_id and filters) are already very detailed, so the description adds little per-parameter meaning beyond restating the field list. The one addition, freshness verdicts, is an output concept rather than a parameter. Baseline 3 applies where 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?

Opens with a concrete verb+resource ('Search the owner's mail mirror') and enumerates the searchable dimensions (subject, sender, recipient, body keyword, date range), so the agent knows exactly what this tool matches on. It also names the sibling it is not (memory.search), making disambiguation possible without opening either schema.

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

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

Gives an explicit routing rule: use this when the user wants an actual email message, use memory.search for past-discussion intent that may live outside mail. The near_id schema text further spells out the when (results that read as questions/proposals), so both tool-level and mode-level selection 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?

With no annotations, the description carries the full burden and does it well: it discloses the approval workflow ('proposed to them first and runs once they approve it, unless they have let it run without asking'), the effect ('stops being recalled'), owner visibility and reason, and reversibility ('can restore it'). These are behavioral traits an agent cannot infer from 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?

Purpose and scope are front-loaded in the first sentence, followed by workflow, constraints, and the alternative. It is dense but nearly every clause carries operational information; the sentence about owner notification and restoration is slightly packed 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 two-parameter mutation with no annotations and no output schema, the description covers authorization boundaries, approval flow, side effects, reversibility, and the sibling alternative. There is no gap that would cause an agent to call it incorrectly.

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 parameters are documented, so the baseline is 3. The description adds genuine meaning by tying memory_id to entries the caller owns and referencing the `by_you` field in `memory.search`, which tells the agent where to obtain a valid id — information the schema does not provide.

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 (forget) and a precisely scoped resource: entries 'YOU saved to the memory pool', including 'the earlier versions it replaced'. It also distinguishes itself from memory.write and implicitly from anything the owner or another agent saved, so an agent can identify it without reading the schema.

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

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

Gives explicit trigger conditions ('when the user asks you to forget it or it was simply wrong') and a named alternative for the adjacent case ('To fix an entry rather than drop it, use memory.write with replaces'). It also states exclusions ('You cannot forget the owner's entries or another agent's'), which is exactly the negative guidance most descriptions lack.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does add useful context: the payload contains named relations, their writing direction, and an example of each, or the group list when no group is given. That effectively describes the return shape in the absence of an output schema. It could still mention whether the list is closed/fixed.

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 that ties the tool to its consumer before explaining the two modes. Slightly awkward phrasing ("which way round each is written", "with a `group` ... with none") costs a little readability but there is no filler.

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

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

For a one-optional-param, read-only reference lookup with no output schema, the description supplies the key facts an agent needs: what vocabulary it returns, how the group parameter changes the result, and the downstream use. Only minor gaps remain, such as confirmation that the output is a static enumeration.

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

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

Schema coverage is 100% and the schema already says "one group... omit to list them," so the baseline is 3. The description adds only modest information beyond that: that selecting a group yields that group's relations with direction and examples, which the schema does not convey.

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

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

The description states what the tool surfaces: the relation vocabulary usable as `memory.write`'s `claim`, including direction and a per-relation example. It clearly names the sibling it feeds into (memory.write), which distinguishes it from memory.search/memory.forget. It never uses an explicit verb like "list" or "returns", so the resource is clear but the action is inferred.

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 link to `memory.write`'s `claim` implies the call is a pre-write lookup, and the with-group/without-group behavior is spelled out. However, it never says "call this before writing a claim" or states when not to bother, leaving the trigger condition implicit.

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

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

Annotations only say readOnlyHint=true; the description adds substantial behavioral context beyond that — how to interpret `match` tiers, how `top_margin` should block silent tie-breaking, what `truncated` means and how to recover it, that only `by_you` entries are correctable via `memory.write`/`memory.forget`, and precedence rules when entries disagree (`origin_actor` user_self beats agents, `rejected` is never true, removed notes count for nothing). No contradiction with the read-only annotation.

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

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

Front-loaded with purpose and constraints before the interpretive rules, and nearly every sentence carries operative information. It is dense and long, but the density is driven by six parameters plus unannotated result semantics; a mild deduction for the volume of disagreement-precedence prose packed into one block.

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

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

There is no output schema, so the description must carry the return semantics — and it does: result fields (`match`, `top_margin`, `truncated`, `by_you`, `origin_actor`, `rejected`, `memory_now`) are all explained along with truncation recovery and pagination cursor usage. An agent has enough to call it and to interpret the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends it: it explains that `about` finds notes by their `claim` in any wording or language and interacts with `query`, and that `memory_id` exists specifically to un-truncate an entry and ignores `query`. That is real semantic value beyond the field descriptions.

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 — 'Recall saved KNOWLEDGE from the owner's memory pool' — and immediately frames its job as cross-session recall. It explicitly separates itself from `recall.search` (transcript history) and from mail/calendar/contacts tools, so an agent can pick it without opening a schema.

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

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

Gives explicit when-to-use (knowledge from earlier sessions the current conversation never carried), an explicit when-NOT (do not re-fetch something already said in THIS conversation), and named alternatives (`recall.search` for earlier turns, dedicated tools for run history/mail/calendar/contacts). Nothing is left to inference.

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

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

With no annotations, the description carries the full behavioral burden and does so: it discloses the approval gate ('proposed to the user first and saved once they approve it, unless they have let it run without asking'), the AI attribution, that entries are visible and reversible in the Memory view, and the ownership model (only `by_you` entries can be replaced or revoked). It also warns against claiming a save already happened — behavior an agent could not infer from any structured field.

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 first sentence is well front-loaded, but the body becomes a dense wall of ⚠/⛔ blocks with overlapping restatements ('This governs what you SAVE, nothing else'; 'That fixes your own entry; it does not make a changing value safe to save'). Every fragment is substantive, yet the volume of caveats makes the single most important action harder to extract than it should be.

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 6-parameter, nested-object write tool with no annotations and no output schema, the description covers approval flow, ownership, correction and deletion paths, and the primary anti-pattern. Minor gaps remain: it doesn't say what the tool returns or how a pending-approval state is surfaced to the caller.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds decision logic the schema cannot: when to populate `claim` (only when a fact is about a person/thing and the relation exists in memory.relations), and when to use `replaces` versus writing a second entry. It leaves `body` and `provenance_entity_ids` to the schema, which is reasonable given full coverage.

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

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

Opens with a specific verb+resource+scope: 'Save a durable memory to the user's shared memory pool — a fact, decision, or piece of knowledge worth remembering across sessions.' It explicitly distinguishes itself from siblings by naming memory.relations, memory.forget, memory.search and contact.write, so an agent can route without opening another schema.

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

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

Gives explicit when-to-use ('remember that …', a derived fact worth persisting), when-not-to-use (facts just told in this conversation, transient state, one-off answers, birthdays/anniversaries → contact.write), and names the alternative for corrections (replaces) and deletions (memory.forget). It even explains why a class of data must never be saved (changing values create irresolvable contradictions at recall).

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

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

With no annotations, the description carries the full burden and discloses the critical non-obvious behavior: write/admin/destructive risk tiers pause for user approval, return reason 'awaiting_approval', and should not be re-sent. That prevents the most damaging failure mode (duplicate execution) and is exactly the kind of context annotations would otherwise 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?

Three sentences, front-loaded with purpose, then the approval caveat, then the selection rule. Dense but every sentence earns its place; the middle sentence is long but carries the highest-value operational detail.

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 6-param, nested-object, no-annotation, no-output-schema dispatcher, it covers the essential invoking behavior and the approval outcome. Normal success output and error modes beyond approval are not described, but the critical runtime semantics are complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuinely useful meaning beyond the schema: `config` is validated against a manifest-declared argument schema that is not statically present, and it clarifies the `recipe_id` versus inline `recipe` choice.

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 ('Invoke') and resource ('installed Recued recipe') with the exact `<publisher>/<slug>` form. It is unmistakably distinct from the recipe control siblings (recipe.stop, recipe.schedule) and the Tier 1 read primitives.

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

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

Gives a clear selection rule: use only when the user intent matches an installed recipe AND no Tier 1 read primitive can satisfy it. It does not enumerate the specific read-primitive siblings it supersedes, leaving some inference about when that condition holds.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains that the call is proposed to the user first, that the schedule is only created after approval unless the user has allowed silent execution, that the recipe uses its own saved settings, and that the response includes the schedule id and next run. It also discloses the user's later ability to switch off or delete the schedule in Automation.

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 front-loaded with the core purpose and modes, then moves through usage examples, alternatives, saved settings, approval behavior, and return/lifecycle details. Every sentence contributes necessary guidance, and the warning formatting makes the approval caveat hard to miss.

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

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

For a six-parameter mutation-like scheduling tool with no annotations and no output schema, the description is complete: it covers timing intent, alternatives, approval semantics, saved recipe settings, return values, and post-creation management. Nothing critical for correct invocation appears missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the mode enum and the required timezone offset for run_at. The description reinforces the mode meanings but adds little parameter-level detail beyond what is already structured, so the baseline of 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 gives a specific verb and resource: scheduling an installed recipe to run later, with explicit one-shot and recurring modes. It also distinguishes this from running a recipe immediately and from the plain-reminder use case handled by the Remind me recipe, so an agent can identify it against siblings.

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

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

It states exactly when to use the tool: when the user asks for something at a time or on a repeat, with concrete examples like 'every Monday at 8' and 'tomorrow at 9'. It also explicitly names the alternative for plain reminders and warns about the approval flow before treating the schedule as set.

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, so the safety profile is covered, and the description adds real behavioral context: action_ref stays stable across approval gates and terminal responses carry the deferred final result. It doesn't mention polling cadence or whether results are cached, but the status lifecycle disclosure is substantive.

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

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

Three tight sentences with the resource identification front-loaded, followed by the reference-stability fact and then the polling constraint. No repetition 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?

There is no output schema, so the description must describe returns; it does so by noting terminal responses include the deferred final result and by naming two statuses. It doesn't enumerate the full status set or state what a non-terminal result looks like, leaving a small gap for an async polling 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?

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema: the action_ref is token-bound and persists across multiple approval gates of the same invocation, clarifying that the reference should not be regenerated per poll.

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 (query) and resource (a token-bound async action) and explains the origin of the resource: it is the handle returned by a Recued tool that paused for owner approval. No sibling does status polling, so the agent can confidently select it without opening the schema.

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

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

Gives a clear operational rule: 'Do not resend the original tool call while this reports awaiting_approval or running,' which implicitly defines when to use this tool. It names no alternative (none exists among siblings), so it stops just short of explicit when/when-not routing.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the cancellation prevents ringing and that already-rung reminders are unaffected, but it does not describe permissions, reversibility, or what the 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?

The definition is short, front-loaded, and mostly free of waste. The opening phrase restates the tool name, but the following sentences quickly add scope and behavior.

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 one-parameter mutation with no output schema, the description covers purpose, when it applies, the id source, and the key limitation. It could mention permission requirements or the result of cancellation, but it is largely complete.

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

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

Schema description coverage is 100%, so the single parameter is already well documented, including its `rem_…` format. The description adds only the reminder that the id comes from 'My reminders', which is essentially duplicative of 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 states a specific verb and resource: cancel a reminder, specifically one that has not yet rung. It clearly conveys the effect (so it never rings), but it does not explicitly distinguish the tool from sibling `change-reminder` or other reminder-related tools.

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

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

It says to use this for reminders still to ring and states that already-rung reminders stay unchanged. It also points to 'My reminders' as the source of the id, giving clear context, though it does not name an alternative tool for related cases.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a mutation of an existing pending reminder and that the answer returns a time, but it omits permissions, reversibility, and error behavior if the reminder is missing or has already fired.

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

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

The description is three short sentences, front-loaded with the purpose and followed by practical call details. It is efficient, with only minor redundancy in the initial 'Use Change a reminder in Recued' phrasing.

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 three-parameter update tool with full schema coverage and no output schema, the description supplies the purpose, id source, time-offset guidance, and return-time instruction. It is sufficient to call correctly, though it does not cover failure modes or side effects.

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 schema already documents reminder_id, the required ISO 8601 offset for remind_at, and that empty values keep existing fields. The description reinforces the id source and time-offset requirement but adds little beyond what the schema already says, 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?

Names a specific action and resource ('Change a reminder') and describes the two allowed changes: moving a pending reminder to a new time or changing its text. It implicitly separates itself from creation and cancellation via 'still to ring' and the existing id, but it does not explicitly name or contrast siblings.

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

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

Gives clear usage context: use it for a reminder that is still pending and needs a new time or text, and get the id from My reminders. It does not state when not to use it or point to alternatives such as cancel-reminder, so exclusions are missing.

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?

No annotations are provided, so the description carries the full burden. It does disclose useful return content (connected folders, a per-folder save-capability flag, nested subfolders holding files), which tells the agent this is a discovery read, but it never states that the call is side-effect-free, whether connected accounts or auth are required, or how the capability flag should be interpreted.

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

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

It is short, but not front-loaded: the opening UI reference adds little before the actual substance, and the closing clause ('Save a file to a folder takes these names') is a fragment. A tighter lead verb such as 'List folders a file can be saved into' would have earned the space.

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, no annotations and no output schema, the description does the necessary work of describing what is returned, including the nested subfolder structure and the save-capability indicator. The remaining gap is the absence of any statement about prerequisites or failure modes when no folders are connected.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing the description needs to disambiguate. It correctly signals that folder names come from this call rather than being supplied as input.

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 second sentence is specific about the resource and scope: it lists connected folders, whether each can currently be saved into, and their subfolders. The lead sentence ('Use "My folders" in Recued') is more of a UI pointer than a verb+resource statement, and the tool name list-folders is never explicitly echoed, but the intent is still 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?

'Save a file to a folder takes these names' implies the workflow link to the sibling save-file-to-folder, but it is phrased as an aside rather than an explicit 'call this before saving' instruction. There is no statement of when not to use it or what to do if a folder is unavailable.

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?

No annotations exist, so the description carries the full behavioral burden, and it does disclose the pending-only filter, the soonest-first ordering, the returned fields (id plus local-time display), and the linkage of ids to the mutation tools. It omits any limits, pagination, or empty-result behavior, which keeps it short of a 5.

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

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

Three short sentences: purpose, ordering and output shape, then the downstream id contract. Nothing is repeated and the scoping detail comes before the follow-on note.

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 annotations and no output schema, the description must convey both the result shape and ordering, which it does. It is complete enough to call correctly, with only volume/limit behavior left unstated.

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

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

The tool takes zero parameters, which is the baseline-4 case; there are no inputs to explain. The description correctly does not invent any.

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 resource (reminders) and the specific scope: ones still to ring, soonest first. That distinguishes it from recued-core/change-reminder and recued-core/cancel-reminder, which it explicitly names as consumers of the returned ids. The phrasing is user-facing ("My reminders", "your clock") rather than operational, but the intent is unambiguous.

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

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

The context is implied by "See the reminders still to ring", and the mention that ids are taken by Change a reminder and Cancel a reminder establishes a follow-on workflow. There is no explicit when-to-use or when-not-to-use statement, and no other sibling such as recued-core/today is contrasted.

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

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

With no annotations, the description carries the full burden. It usefully discloses the sort order (reliability-based) and the refresh cadence, but never states that this is a read-only operation, whether it mutates any state, or how the open_loop_limit truncates results.

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

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

Three sentences, front-loaded with the tool's identity and scope. The clause 'so the easy wins get chased first' is editorial padding, but it is short and does reinforce the ranking rationale.

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 parameterless-required read dashboard with a fully described schema and no output schema, the description covers what the view contains, how it is ordered, and when it refreshes. Only the read-only nature and result truncation behavior are left implicit.

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 start_hour, end_hour and open_loop_limit are already documented in the schema. The description adds no extra meaning about how the hour window or loop limit interacts with the dashboard view, so the baseline 3 applies.

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

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

The description gives a specific resource (a dashboard of open commitments and tasks per contact and project) and its ordering logic (contacts sorted by follow-through reliability). It is clearly distinct from siblings like stalled-projects or today in concept, though it never names an alternative 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?

'Invoke any time for the current view' tells the agent when the tool is appropriate, and the auto-refresh note clarifies that a manual call is not required but is safe. There is no explicit when-not guidance or named alternative for cases where the agent wants per-item task detail rather than a dashboard.

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

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

With no annotations, the description carries the full behavioral burden and provides meaningful context: relevance ranking, 180-day decay, freshest-decile output, and privacy defaults. It omits permissions and return-format details, but the ranking and privacy behavior materially help the agent understand what the tool will do.

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 compact and front-loads the main behavior. The opening "Use ‘Recent notes by topic’ in Recued" is somewhat redundant with the tool name, but the remaining sentences pack useful ranking and privacy details without excess.

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 one-parameter read tool, the description covers ranking and privacy but leaves the "by topic" aspect unexplained and does not describe the output structure beyond the freshest decile. It is adequate for invocation but has a notable semantic gap relative to the tool name.

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

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

There is one optional parameter, note_limit, and schema description coverage is 100%, so the schema already documents it. The description adds no parameter-specific meaning, but the baseline is 3 when schema 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?

The description states a clear operation on notes: surfacing recent notes ranked by ongoing relevance, with a fresh decile and decay behavior. It does not explicitly differentiate this from sibling search/read tools or clarify what "by topic" means, but the core purpose is 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?

The phrase "Surface your still-warm notes" implies a usage context, but there are no explicit when-to-use, when-not-to-use, or alternative-tool comparisons against siblings like memory.search or search_calls-style tools. The guidance is implied rather than operational.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the reminder fires once, on every configured channel, and requires an offset-aware time, but it omits auth, channel setup requirements, failure modes, and what creation returns beyond the final time.

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 front-loads the purpose, then adds time-resolution guidance in three efficient sentences. The opening product phrasing is slightly redundant, but overall it is appropriately sized and readable.

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 two-parameter creation tool with 100% schema coverage and no output schema, the description covers the core behavior and timezone requirement adequately. It does not provide sibling routing guidance, but the schema already handles rejection cases such as missing offsets and past times.

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

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

Schema description coverage is 100%, so both parameters are already well documented. The description reinforces the timezone/offset handling for remind_at, but does not add parameter meaning beyond what the schema provides, and reminder_text is not elaborated.

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: 'Set a one-time reminder.' It also scopes the behavior as one-time and channel-based, which helps distinguish it from list/change/cancel reminder siblings, though it does not explicitly name those alternatives.

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 implies usage by saying to use 'Remind me' for a one-time reminder, but gives no explicit when-to-use versus when-not-to-use guidance. It also does not route the agent toward change-reminder, cancel-reminder, or list-reminders when those would be more appropriate.

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

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait—'It never replaces a file: a taken name gets a number'—but doesn't cover permissions, error cases, or idempotency.

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 front-loaded with purpose and is mostly efficient. The first sentence ('Use “Save a file to a folder” in Recued') is redundant with the tool name, but the rest 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 simple save operation with no output schema or annotations, the description covers the purpose, usage context, key behavior (non-replacement), and user instruction. It could be more complete with explicit alternatives and error handling, but it is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces file_id and folder formats with examples, but it omits the optional file_name parameter and adds little beyond the schema.

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

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

The description clearly states a specific verb and resource: 'Save a file ... into one of their folders.' It explains the action in concrete terms, but does not explicitly differentiate from sibling tools like file.search or list-folders.

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

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

It provides a usage context ('Save a file the user sent, such as an attachment on their email'), but gives no explicit when-not-to-use or alternative tools. The guidance is implied rather than spelled out.

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

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

With no annotations, the description does real work: it discloses that sending is irreversible, that execution halts at an approval gate, that the approval surfaces recipients, subject and each attached file, and that attachments are references rather than bytes. It leaves out what the tool returns, whether the call blocks awaiting approval, and what happens on rejection or refusal.

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

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

Three sentences, front-loaded with the action and the risk before the mechanics. The opening clause restating the tool's display name is filler that a reader gains nothing from, keeping it off a 5.

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

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

For a 12-parameter mutation with no annotations and no output schema, the description covers the two things an agent most needs: irreversibility and the approval checkpoint. Gaps remain around the outcome of a send (including a denied approval) and around the mailbox-selection refusal, though the schema itself carries that detail.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one genuinely new fact — attachments are references to files the owner already holds, never bytes — and reinforces that the approval enumerates each one, but it does not touch the remaining eleven parameters, including the consequential sender_mail_instance selection.

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 gives a specific verb and resource ('sends one email, written in full, from one of the owner's enrolled mailboxes') and constrains the scope precisely: exactly one message, fully composed, sent only from an enrolled mailbox. An agent can distinguish this from the read-side mail siblings (mail.search, mail.read) 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?

The opener 'Use "Send a composed email" in Recued' is naming, not guidance, and no alternative or exclusion is named. The irreversibility plus approval-gate sentence implies when the tool is appropriate (deliberate sends needing sign-off), but the agent must infer that a non-approval path or a different tool exists for other cases.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses the auto-refresh schedule (weekdays) and that each entry includes an AI-suggested next step, which is useful. However, it does not explicitly state that this is a read-only operation, describe what the return format looks like, or mention any permission requirements.

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 two sentences with the core purpose and criteria front-loaded. The opening 'Use "Stalled projects" in Recued' is slightly redundant but not wasteful, and the rest earns its place by defining the stall horizon and next-action conditions.

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-oriented list tool with one optional parameter and no output schema, the description provides enough detail about what is returned (stalled projects with AI-suggested next steps) and the refresh cadence. It does not cover pagination or error behavior, but those are minor omissions for this complexity level.

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 parameter stall_limit is fully documented in the schema. The description does not add any detail beyond the schema, which is acceptable given the complete schema coverage; baseline 3 applies.

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

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

The description states a specific resource (projects) and precise inclusion criteria: no activity past the 14-day stall horizon, or active projects with no next action. It also clarifies that each result includes an AI-suggested next step, making the tool's output distinguishable from generic project listing tools.

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 'Today's intervention list' implies daily use, but the description does not explicitly say when to use this tool versus alternatives like recued-core/today or open-commitments. Usage is only implied through the context of intervention.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Glance card' plus the enumerated contents makes it clear this is a read-only aggregate, and the ranking notion ('carrying the most open loops') is useful context. It does not state what the response looks like, whether sections are ordered or capped beyond open_loop_limit, or how empty calendars/contact-less data are handled.

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

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

The core content is front-loaded in one dense sentence that enumerates the card's sections efficiently. The leading 'Use "Today" in Recued.' is low-value filler that adds nothing an agent can act on.

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

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

With no output schema and no annotations, the description must convey the return shape, and it only loosely does so via a list of sections. Enough is present to understand the intent, but not enough to know how results are structured, ranked, or limited in practice for a five-parameter aggregate view.

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, making 3 the baseline. The description adds no meaning beyond the schema for start_hour/end_hour/weekdays or calendar_slug, and saying 'today's calendar' arguably under-describes the configurable calendar and weekday scoping that the schema exposes.

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 and enumerates its three composite sections: today's calendar, top open loops by contact/project, and active projects with no next action. That is far more than a restatement of the name 'today'. It stops short of distinguishing itself from close siblings like open-commitments and stalled-projects, which surface overlapping content as standalone views.

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?

'Morning glance card' implies a usage context, so the agent can infer this is an orienting/overview call rather than a targeted query. However, there is no explicit when-to-use, no when-not, and no named alternative, even though open-commitments and stalled-projects are direct overlaps that an agent could easily pick 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?

With no annotations, the description carries the full burden. It usefully discloses the classification categories and notification policy, including silent handling for promotional/spam, but it does not state whether emails are modified, what happens to fyi mail, what permissions or channel setup are required, or whether the classification result is returned.

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

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

The core behavior is stated in the second sentence, but the first sentence ('Use “Triage inbox” in Recued') is tautological and does not earn its place. The final clause also repeats the silent-notification idea, though the description overall is not bloated.

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 tool with two optional parameters and no output schema, the description covers classification and notification behavior reasonably well. However, it omits important context such as return output, mailbox side effects, and whether fyi emails trigger notifications, leaving gaps for an agent relying on the description alone.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add syntax, defaults, or parameter-specific guidance beyond what the schema provides, 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?

The description states a specific action and resource: classify each inbound email into five named categories and notify for urgentaction/awaitingresponse. It is clearly a triage tool, but it does not explicitly distinguish itself from sibling mail.search/mail.read tools, 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?

The opening phrase 'Use “Triage inbox” in Recued' is tautological and does not explain when to use this tool, when not to use it, or which siblings to prefer. The classification behavior implies inbox triage, but there is no explicit routing guidance or prerequisite information.

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

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

With no annotations, the description carries the full burden. It usefully discloses that runs are limited to those started by the same MCP token and that an ambiguous recipe_id causes refusal with no run stopped, but it does not state whether stopping is reversible, what happens to a run once stopped, or how missing/nonexistent runs are handled.

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

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

Three short sentences with the primary action and ownership scope front-loaded, followed by the parameter rule and ambiguity behavior. No redundant or filler content.

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

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

For a mutation tool with no annotations and no output schema, the description covers targeting and the key ambiguity case, but leaves out error/return semantics and idempotency details. Adequate but with clear gaps for an agent invoking a stop operation.

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

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

Schema coverage is 100%, and the schema already documents both run_id and recipe_id, including the 'exactly one owned run matches' rule. The description reinforces the mutually exclusive selection and adds the ambiguous-refusal/no-op behavior, but adds little beyond structured fields.

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 (stop) and resource (one attended recipe run) with a clear ownership scope: 'started by this same MCP token.' It does not explicitly distinguish itself from the sibling recipe.stop or recued_actionStatus, so it falls short of 5.

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

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

The description explains the run_id vs recipe_id choice and the ambiguous-recipe_id refusal case, but never says when to use this tool instead of siblings such as recipe.stop or recued_actionStatus. Usage is implied rather than explicitly 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?

With readOnlyHint=true already covering the safety profile, the description adds meaningful behavioral context: default scope is the current conversation, all=true expands scope to other conversations, and the response includes IDs and revisions used for management. It omits details like ordering, pagination, or limits, but the essential behavior is disclosed.

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

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

Three short sentences, front-loaded with the scope and then the parameter exception, followed by a practical note about returned IDs. Every sentence earns its place with no repetition 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?

For a read-only list tool with one optional boolean parameter and no output schema, the description covers purpose, scope behavior, and the key return fields (IDs and revisions). It doesn't mention result ordering, pagination, or empty-result behavior, but those are minor for this tool's 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 description coverage is 0%, so the description must explain the sole parameter—and it does: all=true means search other conversations, which implies the default false limits results to this conversation. The semantics are clear, though the default behavior is stated by implication rather than explicitly.

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 ('Read') and resource ('scheduled prompts'), plus a precise scope ('linked to this conversation'). It implicitly distinguishes itself from sibling operations like schedule.update/pause/remove by framing this as the enumeration step whose IDs feed later management, but it never names those siblings 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 description provides useful guidance for the one parameter: set all=true to look outside the current conversation. However, it gives no explicit when-to-use/when-not-to-use guidance or named alternatives (e.g., calendar.search, schedule.run_prompt); the intended usage is implied by the read/list framing.

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

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

With no annotations, the description usefully discloses key behavior: queued scheduled turns are withdrawn, an in-flight turn is allowed to finish, and the conversation remains usable. It does not cover permissions, idempotency, stale-revision failure behavior, or whether paused schedules can be resumed without losing missed runs.

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

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

Three short, front-loaded sentences with no filler. Each sentence adds a distinct behavioral fact: paused occurrences, running-turn behavior, and conversation availability.

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

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

For a low-complexity mutation tool with two parameters and no output schema, the description covers the essential state effects and lifecycle behavior. It is still missing error handling, permission requirements, and return-value expectations, but those gaps are less severe given the schema's documentation of expected_revision.

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 50% and the description adds no parameter-level information. The expected_revision parameter is well documented in the schema, and schedule_id is self-explanatory, but the description does not compensate for the undocumented half or explain the stale-edit refusal beyond the schema text.

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 gives a specific verb (pause) and resource (scheduled occurrences/turns), making it clear this is a state-change tool rather than a listing or removal tool. It does not explicitly name sibling alternatives such as schedule.resume or schedule.remove, 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?

Usage is implied by the stated effect: stop future occurrences but let a running turn finish and keep the conversation usable. There is no explicit guidance on when to choose pause versus remove, update, or cancel-reminder, nor any stated exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that queued occurrences are removed, conversation history is kept, and an in-flight turn can finish. It does not state whether removal is irreversible, what permissions are required, or what errors may occur, leaving important destructive-operation context uncovered.

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 destruction scope is front-loaded, followed by the retention and in-flight behavior.

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

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

For a destructive tool with no annotations and no output schema, the description covers the core semantic behavior but omits confirmation expectations, irreversibility, and return behavior. It is adequate to understand the operation but not fully complete for safe 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 50%. expected_revision is documented in the schema, but schedule_id is undocumented in both schema and description. The description adds no parameter-level meaning, such as identifier format or revision-check behavior, so it does not compensate for the partial coverage gap.

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: remove a scheduled prompt and its queued occurrences. It also clarifies what is retained, which distinguishes it from a broader delete. It does not explicitly name competing siblings like pause or resume, 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?

The use case is implied: permanent removal rather than temporary pausing. However, the description gives no explicit when-to-use or when-not-to-use guidance against schedule.pause, schedule.resume, or schedule.update, so the agent must infer the correct choice.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the past one-off precondition, but does not describe side effects, permissions, idempotency, or what happens after a successful resume.

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

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

Two short sentences, front-loaded with the core action and followed by the key precondition. There is no 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?

For a mutation tool with no annotations and no output schema, the description covers the main action and one prerequisite but omits important behavioral details such as authorization needs, failure modes, and post-resume effects.

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 only 50%, and the description adds no meaning for schedule_id. It also does not explain expected_revision beyond what the schema already says about stale edits.

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: resume a paused scheduled prompt. It is clearly distinct from schedule.pause, though it does not explicitly contrast with siblings like schedule.run_prompt or schedule.update.

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

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

It gives clear usage context and an important precondition: a one-off in the past must first be updated to a future time. It does not name explicit alternatives or when-not-to-use cases, but the intended scenario 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?

With no annotations, the description carries the full burden and does so well: it discloses that a dedicated conversation is created and reused, that current tool grants and normal write approvals apply, that the current conversation context is not copied, and that answers stay in the new conversation. It omits what the call returns (no output schema exists) and any failure or duplicate-schedule 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?

Front-loaded with the purpose, then behavior, then the parameter rule; no filler sentences and every clause conveys a distinct fact. It is dense as one long paragraph, and clause fragments like 'The user can chat in the new conversation without changing its schedule' could be trimmed or bulleted.

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

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

For an 8-parameter creation tool with no annotations and no output schema, the description covers conversation lifecycle, permission behavior, and prompt self-containment. The notable remaining gap is the return value (e.g., whether a schedule ID comes back) and idempotency of creation_id.

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 75%, and the description adds real meaning on top: it explains notify_on_done's trigger conditions, maps mode to one-off vs recurring, and stresses that prompt must be self-contained because the conversation is not copied. It adds nothing about creation_id's idempotency role, which the schema only hints at.

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

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

Opens with a specific verb and resource: 'Schedule an AI request for later: one-off or recurring.' That distinguishes it from the scheduling siblings (recipe.schedule, schedule.list/update/remove) which operate on existing schedules rather than creating a new AI request, so an agent can pick it without opening the schema.

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

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

Gives concrete selection conditions for the trickiest optional parameter (notify_on_done: set only for 'let me know'/'notify me'/'send me', not when the user just wants something written) and for time_zone (omit unless another zone is named). It does not name alternative tools or state when to prefer schedule.update/pause instead, so it stops short of explicit when-not guidance.

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

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

With no annotations, the description carries full burden and does disclose one genuinely important side effect: "Withdraws queued occurrences of the old revision." The stale-edit refusal lives in the schema rather than the description. It says nothing about required permissions, whether omitted fields are preserved, or what the call returns.

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

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

Three short sentences, front-loaded with the operation and its fields before the side effect and the conversational constraint. The opening "Explicitly" and the closing sentence about ordinary conversation overlap slightly in intent, which is the only waste.

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

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

For an unannotated 8-parameter mutation tool with no output schema, the description covers purpose, one destructive side effect, and the conversational invariant. It leaves open the field-combination rules (run_at vs cron_expression), partial-update semantics, and the return shape, which an agent editing a schedule would reasonably want.

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 75%, so the schema already documents the meaningful parameters including expected_revision's stale-edit refusal behavior. The description echoes notify_on_done by name and groups run_at/cron_expression/time_zone under "timing" but adds no semantics the schema lacks, and says nothing about whether run_at and cron_expression are mutually exclusive.

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 ("change a saved scheduled prompt") and enumerates the three changeable dimensions: prompt, timing, notify_on_done. It implicitly separates itself from schedule.pause/resume/remove by framing this as revisioned editing rather than stopping or deleting, though it never names those siblings to make the boundary explicit.

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

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

"Explicitly change" plus "Ordinary conversation never changes the saved request" tells the agent this tool is the only path to modifying a saved schedule, which is real guidance. However, it gives no when-to-use versus schedule.pause, schedule.resume, schedule.remove, or schedule.run_prompt, and states no prerequisites before invoking a mutation.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial behavior: a 100-item cap with an `omitted` counter, writer_check fields (enabled_count, disabled_count, coverage), receipt semantics (settlement vs observation time), and explicit non-inference caveats ('A registered writer does not prove scheduling', 'Missing receipts do not prove no execution', 'Unknown is not outside'). This is far beyond the annotation, though the density makes some of it hard to absorb on first read.

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 undifferentiated block of dense prose with no headings, line breaks, or front-loading of the primary use case. Critical caveats (writer receipts, disabled_count, private masking) are buried mid-paragraph, and a reader must reconstruct the two operating modes from a wall of 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?

For a complex tool with nine parameters, nested objects, and no output schema, the description covers the dominant behaviors and pagination semantics well. It falls short by leaving several parameters unexplained and never clarifying the return envelope beyond counts and 'values, verdicts, reasons and source references', which an agent needs to parse results.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does well for `time` (day string, inclusive day-range object, Unix ms instant or {from,to}), `context` (copy a returned item's context as the sole argument), and the broad role of `text`/`people`/`place`/`subjects`. However, `limit_items`, `changed_since`, and `limit_clusters` are never explained, leaving three of nine bare-schema parameters undocumented.

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?

Two distinct capabilities are described — returning host-computed comparison facts against a rule target, and returning what is 'due or coming up' in a time span. The second is a concrete verb+resource an agent can grasp, but the opening sentence is opaque jargon ('owner Chat comparisons of a saved reading with a declared rule target') and no sibling is named to distinguish this from tools like recued-core/today or open-commitments.

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 does give use conditions: supply `context` as the only argument to inspect a returned item, use `time` for what is due, and narrow `time`/`people`/`text` when `omitted` is non-zero. It also contrasts reaction.emit ('publishes rule events; it does not write readings'). But there is no clear statement of when NOT to use this versus the many adjacent reminder/commitment/search siblings.

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

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

With no annotations, the description carries the full burden and does so: local-only, no account/connection, nothing leaves the machine, appears in Today and the matching list, user-editable and deletable. Crucially it discloses the approval gate (proposed first, runs on approval unless auto-run is enabled) and warns that creation is non-idempotent, so the agent must not duplicate rows within a turn.

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 purpose is front-loaded and every warning marker (⚠ approval, ⛔ memory.write, ⚠ idempotency) maps to distinct actionable risk. It runs long, and the closing sentence ("This governs what you CREATE, nothing else — reading and reporting work items is unchanged") restates scope already implied, costing a bit of tightness.

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 15-parameter mutation tool with nested objects and no annotations, the description covers side effects, approval flow, non-idempotency and downstream visibility. It does not say what comes back from a successful call (e.g. an id usable with `work.update`/`belongs_to`), and no output schema fills that gap, which is the one remaining hole.

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, enum and nested object is already documented in the schema; baseline is 3. The description adds only a small amount of procedural meaning (call `work.type` first when setting `type`, the note body being the note itself) rather than new per-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?

States a specific verb plus the exact set of resource kinds (`task`, `note`, `commitment`, `project`, `asset`) and where they land (the user's local work graph, Today). It explicitly names the sibling it is not (`memory.write`) and gives a semantic rule to tell them apart, 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?

Gives concrete triggering phrasings ("add a task to call the dentist", "start a project for the Dublin move"), an explicit exclusion with `memory.write`, and a tie-breaker ("when both fit, prefer this one"). It also flags the prerequisite of calling `work.type` first for typed items.

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

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

Annotations only declare readOnlyHint, but the description discloses far more: rich_meta reads the local row, remote_detail/current_remote hit the vendor, retained-row failures degrade to the local row with escalation_error, read_through ids return live:true plus source_freshness and write no canonical row, and provider failure becomes an explicit error with no fallback. It also explains that an absent slot pair means 'no time agreed' rather than a failed lookup, and that related_unavailable means links cannot be read, not that none exist — exactly the failure-mode context the annotation cannot carry.

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

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

Front-loaded with purpose, then ordered to the highest-risk questions (bookings, fidelity, fallback, preview, related). It is a dense single paragraph — long for a read tool — and the fidelity tradeoff is restated in both schema and description, but nearly every sentence carries operational guidance.

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

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

No output schema exists and the tool has non-obvious return shapes (live, source_freshness, escalation_error, related_unavailable, slot fields), all of which the description explains. Nothing an agent needs to call this correctly or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns above it by adding consequence-level meaning — what each fidelity returns, that it is the default, how failure differs per fidelity, and that long_text preview is always bounded. Some of this duplicates the schema's own fidelity description rather than extending it.

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

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

Opens with a specific verb+resource ('Read ONE work item') and enumerates the six families it covers. It also disambiguates the confusing case ('a booking is the whole reservation... do NOT look in the calendar'), which separates it from calendar.search without opening either schema.

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

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

Gives explicit routing rules: use slot_start_at/slot_end_at for 'when is it' instead of the calendar, which fidelity to pick for retained vs read_through ids, when to set include_related, and an explicit anti-pattern ('do not retry the same failed call unchanged'). Alternatives and exclusions are both named.

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

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

Annotations only declare readOnlyHint=true; the description carries substantial extra behavioral load — that it spans local mirrors plus live read-through Sources, that mirrors can trail the vendor, that `source_freshness` states which case applies, and that it invokes no LLM. The long passage on `truncated`/`fidelity`/`omitted_chars` prevents a genuine misreading (that 'complete' means you hold the whole text), which is exactly the kind of disclosure annotations can't 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?

Purpose and scope are correctly front-loaded in the first clause, but the single mega-sentence with nested parentheses and the multi-sentence truncation passage are dense and partly repetitive — 'a cut excerpt is never the whole body' restates the `omitted_chars` point already made. Much of the volume is really about return values, which belongs in a description only because no output schema exists.

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

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

There is no output schema, and the description compensates by documenting the returned fields an agent must act on: source-qualified `id`, `source_freshness`, `long_text.truncated`/`omitted_chars`, `fidelity`, `narrow`, and `limitations`. Combined with full schema coverage on inputs, an agent has everything needed to call this and interpret the response correctly.

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

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

Schema coverage is 100%, so `kind`, `query`, `limit`, `done`, `source_id`, `detail` and `current` are already documented at the field level, and the description largely mirrors that (one kind per call, omit query to list all, 'truncated vs fidelity'). It adds little syntax or semantics the schema doesn't already state, so the baseline of 3 for high coverage 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 (search) plus the resource (owner's work items) and enumerates the six accepted `kind` values with definitions for the ambiguous ones (asset, booking). It explicitly disambiguates from calendar.search — 'a booking is NOT a calendar event and is never in the calendar' — 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?

Gives real decision rules: when to escalate with `detail`/`current`, when `work.read` is worth a round-trip (cited with concrete magnitudes for `omitted_chars`), and which write path applies to mirrored rows vs `live: true` read-through items. It also names the when-not for the `narrow` state ('do not re-send unchanged'). It stops short of explicitly comparing against sibling searches like mail.search or document.read, so a 4 rather than a 5.

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

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

The read-only annotation already establishes the safety profile. The description adds useful behavioral context by listing the metadata returned and explaining the no-`type` listing behavior, but it does not cover permissions, rate limits, errors, or output structure.

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 short and front-loads the main subject before adding the call-before guidance and the no-parameter behavior. The opening phrasing is somewhat awkward, but no sentence is redundant enough to waste space.

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 read-only tool with no output schema, the description gives a reasonable sense of the returned metadata and listing behavior. However, it does not explain the required `kind` parameter or fully specify the return shape, leaving gaps an agent must infer from 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?

The optional `type` parameter is already described in the schema, and the description mostly restates that omission lists types while adding examples like `car`. The required `kind` parameter is only an enum restricted to `asset` and is not explained anywhere, leaving an important required parameter without semantic 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 communicates that the tool exposes metadata about an owned-asset type, including its dates, holder requirement, reminders, and default search keywords. It also names the related `work.create` call and explains the list behavior when no type is supplied, though it lacks an explicit verb like 'get' or 'retrieve'.

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 to call this before `work.create` of an asset and clarifies that omitting `type` lists the available types. It does not state when not to use it or name alternative lookup tools, but the primary usage context is clear.

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

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

With no annotations present, the description carries the full behavioral burden and does so: it discloses that the write is proposed to the user first and executes only on confirmation, that it must not be reported as done, and that updates are partial merge ('Send ONLY what changes; anything omitted keeps its value'). It also flags the unusual constraint that `done` is a claim about the world and must be sent alone in a call that changes nothing else. Return shape is not described, but no output schema exists and the disclosure of the confirmation gate and merge semantics covers the highest-risk behaviors.

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

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

Front-loaded with purpose, then ordered by risk: confirmation gate, id sourcing, partial-update rule, `done` exclusivity, create-vs-update routing. Every sentence is an actionable instruction or a prohibition; the warning markers make the hard constraints scannable in a dense paragraph.

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 17-parameter mutation tool with nested objects and no annotations, the description covers the dangerous parts (irreversibility implied by user confirmation, id provenance, merge semantics, field-kind scoping) which the schema cannot carry. Gaps remain around permissions/auth, error behavior, and what the tool returns, but those are secondary 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, but the description adds real semantics beyond the schema: partial-update behavior for omitted fields, the scoping of each date field by kind (task deadline vs project target date vs promise date), and the rule that `done` is exclusive. It does not walk through the asset-only parameters (`readings`, `attributes`, `belongs_to`, `dates`) in prose, leaving those entirely to the schema.

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

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

Opens with a specific verb+resource ('Change something already in the user's work graph') and then enumerates the concrete field-level operations (mark done, move deadline, retitle, edit note text, record a statement). It explicitly contrasts with `work.create` ('To create something new use `work.create`; this tool only changes what already exists'), so an agent can separate it from its nearest sibling without opening either schema.

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

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

Gives an explicit prerequisite procedure: 'Find the row with `work.search` and use the `id` it returned. Never guess an id.' It also specifies a disambiguation branch ('when the search returned more than one plausible match, say which you found and ask which they mean') and a hard exclusion for creation routed to `work.create`.

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