Dayze — Life Context

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

Annotations only declare readOnly=false, destructive=false, openWorld=false. The description adds real behavioral context the annotations lack: cost ($0.10), API key requirement, a privacy constraint ('never ask for or store device or account identifiers'), and the return shape (inventory_id, item with capability_summary). It does not cover failure modes or rate limits, so not a 5.

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

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

Purpose and the key constraining rules are front-loaded in the opening sentences, and every clause is load-bearing for a 28-parameter tool. The embedded JSON example is long and slightly unwieldy, but it demonstrates the specs/state split in a way prose cannot.

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 high-complexity 28-param nested tool, the description plus a rich schema and output schema cover what an agent needs: when a template is required, what goes in specs vs state, the privacy prohibition, and the return values. Nothing essential 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 86%, so the baseline is 3; the description nonetheless makes the hardest distinction explicit — stable facts belong in specs, changing facts go in state as one observation with observed_at — and the worked example shows exactly which fields that implies. This adds meaning beyond the field-level 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 ('Add an owned item to the user's private Inventory') and immediately differentiates the typed spec path from free-form adds. An agent can distinguish this from update_inventory_item, get_inventory_item, and archive_inventory_item 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 routing rules: pass spec_template plus matching specs for computer/phone/camera/synth, put changing facts in state as one observation with observed_at, and never infer specs from a model name. It stops short of explicitly contrasting add vs update_inventory_item, which the schema partly handles ('null (update) clears it').

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: it's an append operation, the item's current value is overwritten by this value, and it costs $0.10 with an API key required. This is above the annotation baseline.

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 covering the operation, its target and its side effect, plus a short parenthetical for cost/auth. No filler and every clause earns its place.

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

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

With an output schema present, return values need not be described, and the description plus rich schema cover the parameters, the mutation semantics and the pricing/auth constraints. The only real gap is the absence of alternative-tool routing, which keeps it from a 5.

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 89%, so the schema already documents the parameters in detail. The description lists value, currency, valued_at and source but adds no format, default, or validation meaning beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Append a valuation ... to one owned Inventory item') and names the contributing fields. It also discloses the consequential side effect that the item's current value becomes this value, which helps separate it from update_inventory_item. It stops short of naming the sibling it is not, so a 5 isn't warranted.

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 'append a valuation to one owned Inventory item' (i.e., the item must already exist), but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as get_inventory_valuations or update_inventory_item. It's the minimum viable level.

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

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

Annotations already declare the write/non-destructive/non-open-world profile, so the bar is lower. The description usefully adds the per-call cost and API-key requirement, which annotations do not convey, but says nothing about uniqueness conflicts, dedup behavior, or how the alias affects downstream matching.

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 with the core action front-loaded and the cost/auth constraint in a short parenthetical. Nothing wasted, though the parenthetical could be slightly more integrated.

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

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

With an output schema present, return values need no explanation, and the cost/auth detail is covered. Still, for a 6-parameter mutation tool the description omits alias_kind/source semantics and conflict behavior an agent needs before invoking.

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

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

Schema description coverage is only 33%, so the description should compensate. It hints at alias_kind via 'nickname/payment handle/misspelling' but never names the parameter, and leaves source, alias, and person_id semantics to the schema. This is only baseline-level compensation for the 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?

States a specific verb (Add) and resource (alias) scoped to 'one CRM person', and illustrates the alias kinds (nickname/payment handle/misspelling). It doesn't explicitly distinguish itself from the close siblings update_person_alias and remove_person_alias, but the verb makes the intent 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 only guidance is cost and auth ($0.05; API key required). There is no statement of when to add an alias versus updating or removing one, nor any prerequisite about the person existing or alias uniqueness.

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

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

Annotations already establish the safety profile (write but not destructive, closed-world), and the description adds genuinely new operational context not present in the annotations: a $0.10 cost, an API key requirement, and the idempotency purpose of request_id. It does not mention reversibility (undo_event_fact_correction exists) or side effects on the saved answer, which keeps it out of 5 territory.

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 telegraphic sentences, front-loaded with the action and followed by the prerequisite, retry hint, and cost/auth note. Every sentence carries information, though the phrasing is clipped enough that minor clarifications are traded away for brevity.

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?

Because an output schema exists, the description need not explain return values, and it covers the mutation's prerequisite, idempotency, cost, and auth. For a 6-parameter mutation it could still say more about which parameters identify the target fact and about reversibility, so it is complete but not exhaustive.

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 33%, so the description must carry more weight, and it partly does by explaining request_id as the retry-safety/idempotency handle and implying value is the correction payload. However, message_id, source_ref, and action semantics (when to pick 'correct' vs 'not_true_anymore') are left entirely to the schema, leaving a real 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?

States a specific verb pair ('Correct or dispute') on a specific resource ('an event fact from a saved answer'), which distinguishes it from sibling writers like correct_memory_atom and the read-only get_event_fact_source. It does not explicitly name those siblings, so the differentiation is implicit rather than spelled out.

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?

'Inspect its source first' gives a concrete prerequisite step (pointing the agent at the source-inspection flow), and 'Supply request_id for safe retries' gives a conditional instruction for the retry case. There is no explicit when-not guidance or named alternative (e.g., undo_event_fact_correction for reversal), so it stops short of a 5.

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

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

Annotations only carry destructiveHint=true; the description adds substantial context beyond that: soft-delete via archived_at, original rows preserved for versioning, a changed record is refused, 30-day undo window via restore_id, and cost/auth requirements ($0.05, API key). This is rich behavioral disclosure.

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

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

Dense but front-loaded: the 'Preview first, 30-day undo' summary leads, followed by mechanism, workflow, and return semantics in order. No sentence is filler given the complexity of the two-step reviewed flow.

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 mutation tool with an output schema, it covers safety (reversible, preserved rows), the prerequisite preview workflow, the return value (restore_id) and undo path, plus auth and cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 80%, so most parameters are already documented, but the description adds meaning by tying preview_id, restore_window_acknowledged and request_id into a workflow and explaining the required flag values. It stops short of fully disambiguating idempotency_key vs request_id, which the schema handles.

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 (soft-delete an asset, sets archived_at) and immediately differentiates the mechanism from hard deletes. An agent can distinguish it from siblings like archive_event or archive_expense without opening a schema.

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

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

Explicitly prescribes the required sequence: call preview_destructive_change first, then re-invoke with preview_id, restore_window_acknowledged and request_id after user confirmation. It names the alternatives (preview_destructive_change, restore_change) and the exact conditions that select them.

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

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

Goes well beyond the annotations: reversibility, linked data preservation, a returned restore_id, the guarantee that archived rows are never purged, the 30-day restore window, idempotency behavior, zero cost, and API-key auth. Annotations only give the destructive/read-only flags; the description supplies the retention and restore semantics that matter for a destructive-flagged tool.

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

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

Front-loads the operation and key guarantees in the first clause, and each sentence adds distinct facts (reversibility, restore window, idempotency, cost). The parenthetical about the Dayze restore window is slightly verbose but still informative, not filler.

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

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

An output schema exists, so return values need not be described, yet the description still notes restore_id. Combined with auth, cost, retention, and idempotency details, it is nearly complete; the main gap is the ownership/permission constraint and the undocumented reason and alias parameters.

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

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

Schema description coverage is only 25%, so the description should carry more. It clarifies request_id semantics (fresh value per action) and implies event_id must be an owned event, but leaves reason and the idempotency_key alias unexplained, so it only partially compensates.

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 (archive) and resource (event), with scope (one owned event) that distinguishes it from the sibling delete_event and pairs it with restore_event. An agent can identify the operation 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?

Explains the reversal path (restore_event works for at least 30 days) and gives idempotency guidance ('Use a new request_id for each intended action'), which is clear context. It does not explicitly compare against delete_event or state when archiving is preferable to deletion, so no full 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?

Adds substantial context beyond the annotations: linked data is preserved, archived rows are never purged, restore is guaranteed for at least 30 days (the Dayze destructive-change restore window), and the call is $0 but requires an API key. These are exactly the traits an agent needs to reason about safety and cost for a mutating tool.

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

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

Three dense, front-loaded sentences with no filler; the core action leads and the retention/restore facts follow. The parentheticals ('the Dayze destructive-change restore window', '$0; API key required') are compact but slightly cluttered.

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

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

An output schema exists and the description still flags the restore_id return, plus it covers reversibility, retention, auth, and cost. Given annotations and output schema are both present, this is close to complete; only the exact effect on the expense's visibility/state is 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 coverage is only 25%, so the description carries extra burden. It adds real semantics for request_id (must be unique per intended action, implying idempotency), but says nothing about expense_id, reason, or the idempotency_key alias. Partial compensation, not full.

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, and scope: 'Reversibly archive one owned expense.' The word 'reversibly' immediately distinguishes it from hard-delete siblings (delete_event, delete_food, delete_memory), and 'expense' distinguishes it from the other archive_* tools. An agent can identify the operation without opening the schema.

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

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

It hints at when reversibility matters by naming the 30-day restore window and pointing to restore_expense, and it gives operational guidance ('use a new request_id for each intended action'). However, it never explicitly says when to choose archive over update_expense or the delete_* family, so the choice 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?

Annotations declare destructiveHint=true, and the description goes well beyond that: it discloses what is preserved (valuations, people links, photos), the 30-day restore window, that a changed record is refused, idempotency behavior on retries, and that a preview_id is mandatory. It also notes auth (API key) and cost ($0.10), which annotations cannot convey.

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

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

Front-loaded with the two most important facts ('Preview first, 30-day undo'), then the mechanism and parameters. Dense but every clause carries operational meaning; the parenthetical cost/auth note is compact rather than wasteful.

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

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

For a destructive, multi-parameter, preview-gated mutation with an output schema present, the description covers the prerequisites, the reversibility contract, the failure case (edited record refused), and the undo path. Nothing an agent needs 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 cross-parameter meaning the schema cannot: preview_id must originate from preview_destructive_change invoked for this exact tool, restore_window_acknowledged must be true after reviewing, and request_id is the idempotency key. The return of restore_id is also tied back to restore_change.

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 (archive an inventory item) and immediately distinguishes it from deletion by naming the resulting state (status archived, archived_at set). The resource qualifier separates it cleanly from the sibling archive_asset, archive_event, archive_expense, and archive_trip 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?

Gives the full ordered workflow: call preview_destructive_change first, wait for user confirmation, then call this tool with preview_id, restore_window_acknowledged and request_id. It also names the alternative (restore_change) and the exact condition under which undo applies, leaving nothing 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?

Annotations only flag destructiveHint=true; the description resolves the ambiguity that flag creates by stating the archive is reversible, that rows are never purged, that linked data is preserved, and that the restore window is 30 days. It also discloses auth requirements (API key) and cost ($0), which annotations cannot convey.

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

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

Two dense sentences with no filler, front-loading the reversibility guarantee and then the restore window and idempotency rule. The parenthetical cost/auth note is compact and 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?

An output schema exists and the description still names the key return value (restore_id), and it covers reversibility, retention window, auth, and cost. The only gap is that the non-required 'reason' parameter and trip_id identifier semantics are left unexplained for a mutation tool.

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

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

Schema description coverage is only 25% and only idempotency_key carries an inline description (alias for request_id). The description adds real semantics for request_id (must be new per intended action) but says nothing about trip_id or the 'reason' parameter, leaving half the required/optional surface undocumented in both places.

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 (archive), resource (one owned trip), and the key behavioral property (reversible, linked data preserved). The scope qualifier 'one owned trip' and the naming of restore_id/restore_trip let an agent distinguish it from sibling archive_* tools and from delete_* tools 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 actionable usage context: reversibility, the 30-day restore window tied to restore_trip, and the instruction to use a new request_id per intended action. It stops short of explicitly naming when to prefer this over alternatives like delete_event or archive_event, so it is clear context without exclusions.

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

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

Annotations declare it non-readonly and non-destructive, and the description adds real value beyond them: the linked-copy side effect ('the original row stays'), legacy url support, cost ($0.10), and an API key requirement. It stops short of rate limits or failure modes, so not a full 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?

Purpose is front-loaded in the first sentence, followed by behavior, roles, legacy handling, and cost/auth. Dense single-paragraph packing, but nearly every clause earns its place; minor density cost keeps it from 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 mutation tool with an output schema (so return values need not be described) and annotations covering safety, the description supplies the essential remaining context: side effects, legacy path, and cost/auth. It is nearly complete, missing only idempotency/parameter nuances.

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 60% and the description mainly restates fields the schema already documents (roles list duplicates the enum, url legacy is also in the schema). It adds only the marginal note that 'photo is stored as original' and leaves metadata/request_id/idempotency_key unexplained in the description.

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 (attach an asset_id to an entity) and implicitly distinguishes itself from siblings like upload_asset (which creates an asset) by contrasting 'uploaded without an entity' vs 'already on an entity'. An agent can tell this links existing assets rather than creating 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?

Provides legacy usage context ('pass url instead of asset_id') and behavioral conditions (unattached vs already-attached), but never explicitly states when to use this over siblings such as upload_asset or update_asset. Usage is implied rather than 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false). It discloses one-photo-per-entry replacement semantics, that replaced URLs are reported, that EXIF capture time shifts consumed_at unless keep_consumed_at=true, that unknown/other-user food_id returns not_found and stores nothing, that the calendar event is synced and life_state rebuilt, auth requirements, and cost. This is rich, decision-relevant disclosure.

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

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

The verb and scope are front-loaded in the first clause, and the dense remainder is largely load-bearing detail. It is a long single block, and the auth/cost/side-effect sentences could be tightened, 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 annotations, a 100%-covered schema, and an output schema present, the description covers the remaining gaps an agent needs: auth modes, share-token restriction, idempotency, replacement behavior, and side effects. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description meaningfully extends it: 'exactly one of' image_base64 or url, accepted formats (JPEG/PNG/WebP/GIF/HEIC/AVIF), and the 8 MB size cap -- none of which appear in the schema. It also explains the keep_consumed_at effect in narrative form.

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: 'MUTATES one Food Diary row the authenticated user owns by storing a meal photo on it'. The parenthetical about the web diary upload pipeline and the food_id sourcing make it clearly distinct from generic upload_photo/attach_asset siblings. An agent can tell exactly what this does without opening the schema.

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

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

States the required food_id and names where to obtain it (log_food / search), which gives real routing context. It also clarifies the either/or between image_base64 and url. However, it never explicitly contrasts against the closest siblings (upload_photo, attach_asset, update_food), so there is no stated when-not.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly aligns with a safe, read-only operation. It adds context on cost and authentication requirements, and states that it returns only compact candidate clusters, which is a useful behavioral detail. No contradictions with 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?

The description is two sentences: the first states the purpose and output, the second provides a warning and cost/auth info. It is front-loaded and efficient, with no redundant fluff. However, it omits parameter guidance, but that's not a conciseness issue.

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

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

The tool has 3 undocumented parameters and a specific purpose in a crowded domain of cleanup tools. The description differentiates from get_people but not from other cleanup tools like cleanup_preview or score_people_duplicates. It also doesn't explain what 'checks' values are valid or how 'min_confidence' relates to the output. With an output schema present, return values are covered, but parameter usage and selection criteria remain unclear, making it incomplete for reliable 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?

The input schema has 3 parameters with 0% description coverage. The description does not explain what 'limit', 'checks', or 'min_confidence' mean, nor their expected formats or constraints. Since the schema provides no descriptions, the description must compensate but does not. This leaves an agent guessing about how to set these parameters.

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

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

The description clearly states the tool performs server-side contact hygiene and returns compact candidate clusters for specific issues (duplicates, entity-type hints, normalization, payment-handle collisions, junk names). It explicitly contrasts with get_people bulk dumps, making its purpose distinct from a major sibling. The verb 'audit' and resource 'people' are 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 description explicitly warns against using get_people bulk dumps for cleanup, directing the agent to this tool instead. It also mentions cost and API key requirements. However, it does not clarify when to choose this over other cleanup-specific siblings such as cleanup_preview or score_people_duplicates, leaving some ambiguity in tool selection.

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 description contradicts the openWorldHint=false annotation by explicitly calling external Google APIs (nearby search + reverse geocode). Per the rules, a contradiction scores 1. The otherwise rich detail (idempotency, non-destructive guarantees, quota, cost) cannot compensate.

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 dense sentences, front-loaded with purpose and followed by behavioral guarantees and operational constraints. No filler; every clause carries 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?

Given the output schema exists and annotations (aside from the contradiction) cover safety, the description supplies cost, quota, idempotency, and resumability context. It lacks guidance on how to supply the API key or what happens on quota exhaustion, but overall it is fairly 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 80%, so the schema already documents limit, cursor, request_id, and idempotency_key. The description only reiterates cursor resumability and adds cost/API key info, not parameter semantics. dry_run remains undocumented in both.

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

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

States a specific verb (add), resource (human names to coord-only places/visits), and method (Google nearby search + reverse geocode). It does not differentiate from the similar sibling enrich_place_from_google, which also enriches places from Google.

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?

Implied usage for coord-only places, but no explicit when-to-use or when-not criteria, and no mention of alternatives like enrich_place_from_google or update_place. The quota and cost notes are operational, not routing guidance.

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

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

Annotations already flag destructiveHint=true, and the description adds substantial context beyond them: a 30-day undo via restore_change, refusal if the record changed since preview, restore_id return, idempotency behavior, and even cost/API-key requirements. This is exactly the behavioral disclosure a mutation tool needs.

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 two key facts ('Preview first, 30-day undo') and organized as a workflow. It is somewhat dense and repeats the review/reversibility idea, but nearly every sentence carries 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 destructive bulk mutation with a preview gate, the description covers the full lifecycle: preview, confirmation, application, undo window, and failure on changed records. An output schema exists, so return-value detail is not required, and cost/auth are noted.

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 67% schema coverage, the description still explains how the three required parameters are used together (preview_id from the preview call, restore_window_acknowledged after review, request_id for idempotent retries) and documents the preview-side entity_type/reason arguments. It adds real meaning over the schema.

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

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

States a specific verb+resource with a scoping qualifier: 'Dismiss non-person / typed junk from the clarification queue.' The 'bulk' framing plus the junk-type filter distinguishes it from the single-item dismiss_clarification and the resolve_clarification siblings 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?

It gives an explicit two-step protocol (preview first, then call this after the user confirms) and names the exact preview call and required arguments. It stops short of naming dismiss_clarification as the single-item alternative, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=false, and the description reinforces this with 'without losing transactions or links', which is exactly the concern for a reclassification operation. It also discloses two facts absent from structured fields: a $0.10 cost and an API key requirement.

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

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

Two compact sentences, the operation and its safety guarantee front-loaded, with cost/auth as a trailing parenthetical. Nothing is 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?

An output schema exists so return values need no explanation, and annotations plus the cost/auth note cover much of the behavioral picture. The gap is identification: for a mutation on a CRM row, the description never explains how source/entity_id/person_id select the target, leaving a real ambiguity at call time.

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 25% schema coverage, the description carries some burden and does add value by enumerating entity_type values that the schema leaves as a bare string. But it says nothing about the five other undocumented parameters (source, entity_id, person_id, confidence, identity_status) — notably which combination identifies the row to classify.

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 (Set entity_type) and resource (a CRM row), and enumerates the target values person/company/merchant. It does not, however, distinguish itself from the adjacent sibling convert_contact_entity, which an agent could plausibly pick instead.

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?

There is no when-to-use guidance: nothing says when classification is appropriate versus convert_contact_entity, update_person_identity, or update_person. The implied context (a CRM row needing an entity type) is the only signal offered.

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

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

Adds substantial behavioral detail beyond annotations: atomicity, refusal on changed sources, per-row statuses, a restore_id valid for at least 30 days, replay behavior that performs no additional actions, and cost/auth requirements. All of this is consistent with destructiveHint=true and enriches the agent's understanding of a destructive write operation.

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?

Very compact and front-loaded: the core action is stated first, followed by requirements, safety behavior, return/undo information, and cost/auth constraints. Every clause carries useful 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?

Given that an output schema exists, the description need not explain return values, but it still usefully mentions per-row statuses and restore_id. Annotations cover the safety profile, and the description fills in atomicity, refusal behavior, undo window, replay semantics, and cost/auth requirements, leaving no major operational gap.

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

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

Schema description coverage is only 25%, so the description should compensate by explaining the parameters. It merely lists preview_id, candidate_hash, and request_id as required, which repeats schema metadata without defining what they mean or how they relate to preview integrity and idempotency. The optional idempotency_key alias is not mentioned at all.

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: 'Atomically archive the exact reviewed preview.' This clearly distinguishes cleanup_apply from cleanup_preview by tying it to applying an already-reviewed preview, and from restore_cleanup by naming it as the undo path.

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

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

Gives clear usage context: it requires a reviewed preview, refuses changed sources, and names restore_cleanup as the alternative for undoing the operation. It does not explicitly say to call cleanup_preview first, but the reviewed-preview requirement strongly implies the workflow.

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

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

The description explicitly claims "Read-only account audit," but the annotations declare readOnlyHint=false. An agent that trusts the prose would treat this as a safe read while the structured safety signal says otherwise, which is a direct conflict. The otherwise-useful additions (30-minute expiry, $0 cost, API-key requirement, returned artifacts) do not cure the contradiction of 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 purpose in the first clause, followed by returns, the sibling routing rule, and operational constraints — no wasted sentences. It is slightly telegraphic ("($0; API key required)") but dense 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?

With an output schema present, the description need not enumerate return fields, and annotations cover the safety profile — though that coverage conflicts with the prose. Expiry, cost, and auth needs are stated, so an agent has enough to call it; the unresolved read-only conflict is the main completeness defect.

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 67%, with request_id and idempotency_key already documented in the schema as idempotency mechanisms. The description's "events, expenses or trips" restates the family enum values without adding syntax, defaults, or selection guidance, so the baseline of 3 applies.

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

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

States a specific action on specific resources ("account audit and durable archive plan for events, expenses or trips"), and the family list maps directly onto the enum an agent will see. It also distinguishes itself from its closest sibling by naming cleanup_apply as the step it precedes.

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?

"Review the exact candidate set before cleanup_apply" gives a clear workflow condition and names the alternative tool, so the agent knows this is the pre-flight step. It stops short of stating when not to use it or what to do once the 30-minute preview expires, so it is clear context rather than full 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?

Adds substantial context beyond the destructiveHint=true annotation: append-only bitemporal revisions that preserve prior versions, the absence of any post-commit undo tool, the workaround, the cost ($0.10), and the API-key requirement. This is exactly the irreversible-mutation disclosure an agent needs.

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

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

The core action and its precondition are front-loaded, and the parenthetical cost/auth notes are compact. Semicolon-heavy and dense, but every clause carries information rather than filler.

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

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

An output schema exists so return values need no explanation, and the description covers the prerequisites, irreversibility, cost, and auth. It is close to complete for a destructive mutation, with the only real gap being parameter meaning.

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% across five parameters, so the description must compensate. It name-drops payload_hash and owner_session_id but gives no meaning for either, and never explains the required proposal_id or the optional idempotency_key and request_id, leaving most parameters semantically opaque.

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 (commit) and resource (life update) and ties it directly to the sibling propose_life_update, which it requires first. An agent can distinguish this from propose_life_update and the restore_* tools without opening the schema, though the phrasing 'Owner approve+commit' is slightly telegraphic.

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 the precondition ('Requires the propose_life_update review first') and the correct alternative for fixing a bad commit ('correct a committed fact with a new propose_life_update'), plus the 'off by default' flag status. It stops short of spelling out when the flag is toggled on, but the routing guidance is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so no contradiction exists. The description adds useful behavioral context beyond the annotations: it packages what would be two notable_pack calls into one, notes the timeline format, and discloses the $0.08 cost.

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 concise semantic units in one sentence: what it returns, why it is preferable to calling notable_pack twice, and a concrete example. No filler words or redundant restatements.

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 tool with only two required parameters, the description plus the input schema and annotations gives an agent everything needed to call it correctly. It also includes enough comparison-specific context to choose this over notable_pack, and the cost and timeline details remove the main remaining unknowns.

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?

slug_a and slug_b have schema descriptions, and the example reinforces what a slug looks like. However, the description adds nothing about date, peers, or similar, and peers/similar are not described in the schema either, so the 40% schema-description gap is left uncompensated.

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: produce side-by-side notable packs for two slugs. It names the resource (notable packs with life_in_days + day_number timelines) and explicitly differentiates itself from notable_pack by noting it replaces two calls. The elon-musk vs steve-jobs example grounds the abstraction.

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 names notable_pack as the alternative and frames compare_lives as the one-call version for comparing two people. It doesn't give formal when-not conditions, but the intended context is clear enough for an agent to decide when to pick this over a single notable_pack call.

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

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

Goes well past the annotations (destructiveHint=true): discloses preview-first requirement, 30-day undo window, that a changed/changed record is refused, that FKs are preserved, and precisely what restore reverts (entity_type, identity_status, identity_confidence). This is unusually rich behavioral context for a mutation tool.

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

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

Front-loads the preview/undo model and cost, with each sentence carrying workflow or reversal information. It is dense and slightly repetitive in restating the preview/restore loop, but nothing is wasted.

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

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

Given an output schema exists, the description needn't explain return values, and it still covers the full lifecycle (preview, apply, refuse-on-change, restore) plus pricing and auth. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 57%, so the description meaningfully supplements: it explains preview_id's provenance, request_id's idempotent-retry behavior, and the review semantics of restore_window_acknowledged. It could still clarify entity_id vs person_id and target_type's allowed values.

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 ('Convert a contact's entity_type') and immediately identifies its relationship to a sibling ('same as classify_contact'), letting an agent distinguish it from the ~150 other tools. No ambiguity about what the tool does.

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 two-step protocol: first call preview_destructive_change with exact arguments, then after user confirmation call this tool with preview_id, restore_window_acknowledged: true and request_id. It also names classify_contact as the equivalent operation, so the when/how is fully prescribed.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: the preview-first guard, the 30-day restore window, the refusal of a changed record (staleness safety), the restore_id undo path, the $0.10 cost, and the API-key requirement. This is exactly the added behavioral detail expected when annotations only flag destructiveness.

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 workflow and reversibility facts are front-loaded, and the sentences are dense but purposeful. The trailing cost/API-key parenthetical and some workflow repetition make it slightly longer than strictly necessary, but every element carries useful signal.

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 mutation with a required multi-step preview flow, the description covers the full lifecycle: preview, apply, and undo. With an output schema present, it need not detail return values, and it still names restore_id, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies that memory_id and false_atom are supplied to the preview call rather than this one, and that preview_id comes from preview_destructive_change while restore_window_acknowledged must be true after review. It explains the reasoning behind request_id idempotency, though the alias field is 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?

States a specific verb (remove one exact false atom) against a specific resource (a bundled memory) and explicitly scopes it as surgical: it retains the other text and clears the stale embedding. This distinguishes it from siblings like delete_memory and merge_memory without needing to open any schema.

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

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

Gives an explicit two-step workflow: call preview_destructive_change first with the exact arguments, then call correct_memory_atom after user confirmation with preview_id and restore_window_acknowledged. It names the ordering, the prerequisite, and the confirm step, leaving nothing 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?

Annotations only declare the safety profile (non-read, non-destructive), while the description adds real behavioral context: privacy of the record, cost ($0.10), API-key requirement, defaults for status/source/confirmation_status, and the no-write-if-unresolved rule. This is substantial value beyond the annotations and does not contradict them.

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 the subject_type rule are front-loaded, then defaults, then cost/auth. Every clause carries a rule or fact, though the density is high and the trailing cost/API-key note reads as appended rather than integrated.

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 14 parameters, high schema coverage, and an output schema present, the description need not explain return values. It supplies exactly the missing pieces—usage rules, defaults, privacy, and cost/auth—so an agent has everything required to call it correctly.

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

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

Schema coverage is 93%, so the baseline is 3; the description goes beyond it by reinforcing defaults (suspected, user_reported, reported) and adding a semantic guardrail—never infer active/confirmed from a mention and keep the user's words. These add meaning for the enum/default parameters the schema alone does not fully constrain.

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 ("Add a private condition") plus the scoping rule (subject_type self or person). The create semantics implicitly distinguish it from the sibling update_condition, and the "private" qualifier adds scope an agent would not otherwise know.

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 rules and exclusions: use self or a person with an owned person_id from get_people/resolve_person, never turn a family member into self, and if the person is unresolved ask and write nothing. It even routes to the sibling tools needed to resolve the person first.

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

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

Annotations declare a non-destructive write; the description adds rich context beyond them: never sends anything, dedup returns created:false/deduplicated:true, linking fallback with person_link explaining why, auth requirements (context.write, share tokens cannot write), and cost ($0.10).

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: purpose first, then routing, then optional fields, dedup, auth and cost. Every sentence carries operational information, though the parenthetical field list makes it somewhat packed.

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-param mutation tool with an output schema and annotations, the description covers the write semantics, dedup, linking, auth, and cost. An agent has everything needed to call it correctly without guessing.

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 by tying parameters to behavior: person_id bypasses resolve_person linking, update_existing mutates an existing unsent reply, and summary must never contain the email body/subject/sender.

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 ('save a reply the user owes someone') with concrete examples ('what to reply to X', 'I owe X a reply'). Explicitly distinguishes itself from log_event and task, so an agent can route correctly 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 'Use this, not log_event or a task' names the alternatives and the condition that selects this tool. It further routes on dedup ('update_existing: true replaces its draft and summary') and linking ('only when resolve_person finds exactly one').

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): discloses duplicate detection, the exact shape of the existing-contact response (person_id, not_applied, hint), idempotency semantics (request_id / 15-minute dedupe window), the create_contact alias, cost ($0.10) and the API-key requirement. Rich, non-obvious 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?

Front-loads the core action and birthday formats, then layers idempotency, naming and cost. Dense but mostly earn-place; the parenthetical cost/auth note and alias clause make it slightly crowded for a single 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 13-param write tool with an output schema, it covers the important gaps: auth, cost, idempotency, duplicate handling and the existing-record return case. The main omission is meaning for the secondary filter-like params, though the output schema and self-explanatory names cover most of that.

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

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

Schema description coverage is only 23%, so the description must compensate. It adds real value on the two non-obvious params (birthday formats, request_id idempotency), but leaves tier, aliases, is_favorite, context_tags, relationship(s) and idempotency_key unexplained. Most remaining params are self-evident, so this is adequate rather than thorough.

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

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

States a specific verb ('Add') and resource ('Dayze Contacts record') and is clearly distinguishable from sibling creators like create_place and create_condition. It also resolves the create_person/create_contact naming ambiguity 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?

Implies usage through the duplicate-check behavior ('checks duplicates first'), which hints at a create-vs-update decision, but never states when to use this instead of update_person or merge_people. No explicit when-not guidance or named alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context—idempotency semantics, API key requirement, and cost ($0.10)—which is genuinely beyond what annotations provide. It does not, however, describe what happens on duplicate name matches beyond 'does not create calendar notes,' nor error behavior for partial matches.

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

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

A single dense sentence with no wasted words. It front-loads the core purpose, lists fields compactly, and tacks on idempotency and cost—appropriate framing for a tool definition.

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

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

An output schema exists so return values needn't be described. But for a 21-parameter mutation tool with only 29% schema description coverage and no annotation coverage of side effects, the description leaves too many gaps—particularly the ambiguity around name-based idempotency (what if the name matches an existing place but other fields differ?) and the meaning of aliased parameters.

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

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

Schema description coverage is only 29% with 21 parameters, so the schema leaves most parameters undocumented. The description lists some field categories (address, opening_hours, affordability, notes, tags) and mentions idempotency by name or idempotency_key, but omits many parameters like latitude/longitude, category aliasing, phone_numbers, hours_source, and request_id. It does not compensate for the low 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?

The description states a specific verb and resource: saving a 'venue card (business_contacts)' with named fields. However, it doesn't explicitly distinguish this from siblings like `update_place` or `enrich_place_from_google`, though the create-vs-update distinction is implied by the name.

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?

No explicit when-to-use guidance or alternatives. The description implies idempotency but doesn't explain when an agent should use `create_place` versus `update_place`, `resolve_place`, or `log_place_visit`, nor does it state what happens when a place already exists.

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

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

Goes well beyond the annotations: reversibility, preserved food/people/asset links, replay being a no-op, restore path, and cost/auth requirements ($0.10; API key required). The only tension is that destructiveHint=true is framed as harmless archival, which could soften an agent's caution before confirming with the user, though the two are not strictly contradictory.

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

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

Front-loaded with the core action and reversibility, and most sentences carry distinct information. The enumeration of return fields (deleted, changed, restore_id, life_state_rebuilt) duplicates the output schema and is the one expendable clause.

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

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

For a mutating tool with annotations, an output schema, and full param coverage, the description supplies the missing pieces: reversibility, link preservation, idempotency behavior, restore path, cost, and auth. The remaining gap is sibling differentiation from archive_event.

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, and the description adds real meaning by stating that both event_id and request_id are required and that a replay returns the first result. The idempotency_key alias is left to the schema, but that is a minor omission.

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

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

States a specific verb and resource with scope: 'Reversibly archives one owned event.' The word 'one' and 'owned' pin the cardinality and authorization boundary. However, it does not distinguish itself from the sibling archive_event, which reads as the same operation, so an agent cannot route between them from the description alone.

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 names the undo path ('Restore with restore_event'), which is useful recovery guidance, and implies use when the user wants an event removed. But it never states when to prefer this over archive_event, update_event, or delete_food/delete_place-style siblings, and gives no prerequisites beyond ownership.

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

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

Annotations already flag destructiveHint=true/readOnlyHint=false, but the description goes far beyond: 30-day undo window via restore_id, restore refusal if the record was edited since, rebuilds life_state, refusal of changed previews, idempotent request_id retries, auth requirements (API key or OAuth with context.delete, share tokens cannot write) and cost. This is rich behavioral disclosure.

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

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

Front-loaded with the two headline facts ('Preview first, 30-day undo') and every sentence carries operational weight. It is dense and slightly repetitive in restating the preview/confirm step, but no sentence is filler for a tool with this much mandatory ceremony.

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?

Output schema exists so return values need no explanation, yet the description still names the returned restore_id. Auth, cost, error conditions, idempotency, and the preview workflow are all covered, leaving nothing an agent needs in order to call this destructive tool safely.

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 already 100%, so baseline is 3. The description adds workflow meaning the schema cannot: why preview_id must come from preview_destructive_change, why restore_window_acknowledged must be true, and that request_id is an idempotency key. It explains the parameters' roles in the flow rather than their formats.

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 ('Removes one Food Diary row the authenticated user owns') plus the side effect on the mirrored calendar event, and explicitly distinguishes itself from sibling delete_event and implies the log_food/update_food context. An agent can identify this 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?

Explicit when-to-use ('Prefer this over delete_event for meals logged via log_food'), when-not (unknown or other-user food_id returns an error), and the full mandatory preview-then-confirm sequence including which arguments to pass to preview_destructive_change and delete_food. 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?

Annotations only declare destructiveHint=true; the description goes far beyond by disclosing the 30-day restore window, that a changed record is refused, downstream effects (chat and get_memories stop using them at once, life_state rebuilds), the auth requirement (API key or OAuth with context.delete, share tokens cannot write), and idempotent retry behavior. These are exactly the operational traits an agent needs for a destructive tool.

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

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

Front-loaded with the key constraint ('Preview first, 30-day undo'), and every sentence carries substantive information. It is dense and occasionally run-on, but there is no filler and no repetition of the schema.

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

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

An output schema exists, so return-value detail is unnecessary, and the description still covers the receipt/restore_id concept. Combined with the preview workflow, auth constraints, side effects, and reversibility, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds workflow meaning: memory_id is optional and checked against the preview, preview_id must come from preview_destructive_change, and restore_window_acknowledged must be true after reviewing the preview. It explains why these parameters exist rather than only restating their types.

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 ('Removes Dayze Agent memories the authenticated user owns') and scopes ownership explicitly. It distinguishes itself from siblings by routing calendar-event rows to delete_event and by naming get_memories as the source of memory_id. An agent can identify the target object class 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 an explicit two-step workflow: call preview_destructive_change first, then call delete_memory with preview_id, restore_window_acknowledged: true and request_id after user confirmation. It names the alternative (delete_event) and the condition that selects it, and states that unknown or other-user ids simply resolve to not-found.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description layers substantial extra behavior on top: a mandatory preview gate, exact-application semantics, a 30-day restore window via restore_id, refusal when the record changed since preview, and the cost ($0.10) and API key requirement. This is rich context well beyond the 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?

The key point ('Preview first, 30-day undo') is front-loaded, and the paragraph is information-dense with the cost/auth notice trailing. It is on the dense side for one paragraph, but nearly every clause 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?

Given a mutation tool with an output schema present, the description covers the workflow, reversibility, refusal semantics, idempotency, cost and auth requirements. Nothing an agent needs to invoke it correctly is missing, and return values are appropriately not over-explained.

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 80%, so the schema already documents preview_id, request_id, idempotency_key and restore_window_acknowledged. The description reinforces usage (pass preview_id, acknowledged: true, request_id) but adds no new format or constraint detail beyond what the schema states. Baseline 3 is appropriate.

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

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

The name/title pair (delete_moment) plus the workflow text make it clear this applies a reviewed deletion of a moment, and the description names the prerequisite (preview_destructive_change) and the undo path (restore_change). However, it never plainly states 'deletes a moment' as a verb+resource and does not differentiate itself from the sibling delete_moment_preview. Clear purpose, but differentiation is left implicit.

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

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

It gives an explicit two-step protocol: call preview_destructive_change first to store the change, then delete_moment after user confirmation with preview_id, restore_window_acknowledged: true and request_id. It also states the refusal condition (a changed record is refused) and the undo path, so when-to-use and the guardrails are fully specified.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, which sounds alarming for a 'preview', but the description clarifies that 'nothing is removed' and that only a preview is stored. This is meaningful added context beyond the annotations, resolving a potential misinterpretation. It also discloses the $0.05 cost and API key requirement, which annotations do not.

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

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

One dense sentence front-loads the operation, the effect, and the key safety point ('nothing is removed'), then appends cost and auth requirements in parentheses. No wasted words.

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

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

Covers the operation, the non-destructive nature, the cost, and the auth requirement, which addresses the main behavioral unknowns given a moderate schema and an output schema that presumably explains the return. It does not explain the relationship to delete_moment or the preview's lifespan, but it is nearly 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 67%; the description adds no parameter guidance beyond the schema. request_id and idempotency_key are documented in the schema itself, and moment_id is simply required. Baseline 3 is appropriate since the schema does the heavy lifting for most parameters.

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

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

States a specific verb and resource ('Read a Moment and linked impact and store a reviewed deletion preview') and immediately distinguishes itself from the real deletion tool by clarifying 'nothing is removed'. An agent can tell it apart from delete_moment and preview_destructive_change 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 implicit workflow is clear: this is the preview step before delete_moment, and the description says nothing is removed, which routes agents here rather than to the destructive sibling. It does not explicitly name delete_moment or state when the preview is mandatory, leaving some inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds context beyond them: a 30-day restore snapshot is preserved, undo is possible via restore_id, request_id gives retry-safe idempotency, and it costs $0.10 with an API key required. This is rich behavioral disclosure that materially affects how an agent should call 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?

Four tight sentences, each carrying distinct information (precondition, recovery window, idempotency, cost/auth). The critical precondition is front-loaded before the softer details.

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

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

An output schema exists, so return values need not be explained. Given the destructive nature and 5-param surface, the description covers everything an agent needs: prerequisite, reversibility window, undo path, and idempotency contract.

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, including request_id as an idempotency key and restore_window_acknowledged. The description restates the request_id idempotency purpose but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete one owned contact') with a clear scope restriction ('one owned'). It explicitly distinguishes itself from the sibling delete_person_preview (which must precede it) and undo_contact_change (which reverses it), so an agent can place it precisely among the destructive-contact 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 an explicit precondition ('only after delete_person_preview'), names the alternative recovery path ('undo with undo_contact_change using restore_id'), and notes the retry contract. When and how to use it are fully specified with no inference required.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description explains the apparent tension by specifying the operation is non-mutating to the contact but produces a durable snapshot, and adds behavioral context annotations cannot carry: a $0.05 cost, an API key requirement, and a 30-day restore window. That is exactly the kind of side-effect, auth, and lifecycle information an agent needs before calling.

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 no filler: the operation and its non-mutating nature come first, the workflow second, and the cost/auth constraint last. Every clause carries information an agent must 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?

An output schema exists, so return values (including preview_id) need not be explained, and the description covers the remaining gaps: safety profile, cost, auth, and the restore window. Nothing needed to invoke this correctly or chain it into delete_person is missing.

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

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

Schema description coverage is 100%, so person_id, request_id, and idempotency_key are already fully documented in the schema and the baseline is 3. The description adds only an indirect hint that a preview_id is produced for later use; it offers no extra meaning about the inputs themselves.

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

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

States a specific verb and resource ('Create a durable, non-mutating snapshot of one owned contact and every linked record') and immediately disambiguates from the name's implication of deletion by calling it non-mutating. It also names the sibling tool it feeds into (delete_person), so an agent can distinguish it from delete_person 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 ordering ('before deletion'), the review step ('Review the 30-day restore window'), and the exact handoff ('then pass preview_id to delete_person'). The when-to-use condition and the alternative it pairs with are both stated rather than inferred.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context: 30-day undo via restore_change, re-linking of visits/events/expenses/people, refusal if the record was edited, restore_id return, cost, and API key requirement. No contradiction with 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 key information (Preview first, 30-day undo), then gives the exact safe invocation sequence, restore behavior, and cost/API requirement last. Every sentence supports correct or safe invocation.

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

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

With an output schema present, return values need not be described. Annotations cover the destructive safety profile, and the description supplies the preview/restore contract, idempotency and acknowledgment requirements, re-linking behavior, cost, and auth requirement. Complete for this destructive tool.

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

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

Schema coverage is 57%, and the description explains the critical required parameters: preview_id from preview_destructive_change, restore_window_acknowledged must be true, request_id as idempotency key, plus place_id/business_contact_id as lookup keys. It does not explain the optional id parameter or the idempotency_key alias in depth, so it falls short of fully compensating.

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: delete a saved place card (business_contacts) by place_id / business_contact_id, returning the deleted card. It clearly targets the place card rather than a sibling entity such as a place visit.

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 mandates the preview-first workflow: call preview_destructive_change first, then after user confirmation call delete_place with preview_id, restore_window_acknowledged: true, and request_id. The sequence, conditions, and refusal of changed records are all stated.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: a 30-day reversible undo window, the preview-then-apply contract, refusal if the record changed since preview, restore_id return, idempotency, and the $0.10 cost plus API-key requirement.

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 'Preview first, 30-day undo,' and every sentence carries operational weight. It is dense and packs cost/parenthetical detail, but no sentence is filler; slightly more compression could help.

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, multi-step tool this is complete: it covers the preview gate, confirmation flow, reversibility window, and even names the return value, despite an output schema existing. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so each parameter is already documented. The description goes beyond that by explaining how the parameters interlock in the workflow (preview_id comes from preview_destructive_change, restore_window_acknowledged must be true, request_id ties to retries), adding real meaning over the schema alone.

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 (delete) and resource (one place_visits row) and immediately disambiguates from the sibling delete_place with 'without deleting its canonical place'. An agent can distinguish it from delete_place and delete_person 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?

Lays out an explicit when/when-not workflow: first call preview_destructive_change, then after user confirmation call this tool with preview_id. It names the exact alternative tools (preview_destructive_change, restore_change) and the conditions that select them, leaving nothing 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?

Annotations already declare this is a mutation (readOnlyHint=false) that is non-destructive and not open-world. The description adds genuinely useful operational context — the $0.05 cost and API key requirement — but says nothing about whether a dismissal is reversible, what happens to the underlying entity record, or whether the pending item can be restored.

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

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

One sentence with the action front-loaded and cost/auth constraints tucked into a trailing parenthetical. Nothing wasted, nothing buried.

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

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

An output schema exists, so return values need not be described, and the cost/auth note covers operations. Still missing is the consequence of dismissal (irreversibility, effect on the entity) and any routing guidance among the three clarification-related siblings, which leaves the definition thin for a paid mutation tool.

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

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

Schema coverage is only 50%: request_id and idempotency_key are documented in the schema, but clarification_id (the sole required param) and reason are bare. The description mentions clarification types but does not explain what clarification_id references or what reason is used for, so it fails to compensate for the 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?

States a specific verb and resource ('Dismiss a pending entity clarification') and gives a concrete example of the clarification type ('not_person, etc.'). It is distinguishable from resolve_clarification and bulk_dismiss_clarifications by implication, but never names those siblings or draws the boundary 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?

Only the word 'pending' hints at when this applies. There is no guidance on when to dismiss rather than resolve a clarification, no mention of bulk_dismiss_clarifications for multiple items, and no stated preconditions beyond an API key.

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

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

Annotations declare openWorldHint=true and destructiveHint=false, which the description reinforces with the concrete default (fill_empty_only, does not overwrite agent-supplied fields) — a real behavioral guarantee beyond the annotation. It also discloses the not_configured failure mode when GOOGLE_PLACES_API_KEY/GOOGLE_MAPS_API_KEY is absent and a $0.15 cost, though it never says what happens when fill_empty_only is set false (i.e., whether existing values are overwritten).

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 tightly packed sentences, front-loaded with the core action and default behavior before the failure mode and cost. The parenthetical field list and API-key aliases add density but each element carries information an agent needs.

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

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

With an output schema present, return values need no explanation, and the description still covers the default write policy, the external-dependency failure mode, and cost. The main gap is the behavior under fill_empty_only=false and role of business_contact_id, but overall it is sufficient 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?

Schema description coverage is only 40% across 5 parameters, so the description must compensate. It does explain the important fill_empty_only flag (default and non-overwrite semantics) that the schema leaves undocumented, but place_id, business_contact_id, and the idempotency alias pair receive no additional meaning from the description.

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 verb (enrich/fill) and resource (saved place card) and enumerates the fields it populates (hours/address/phone/website), so the agent knows exactly what the tool produces. It does not explicitly name a sibling like update_place or create_place to route against, so the differentiation from those tools is inferred rather than stated.

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

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

"Optional Google Places fill" signals when the tool is appropriate (supplementing an existing place card with external data), and the default fill_empty_only implies the safe path. However, no alternative tool is named and there is no explicit when-not guidance, leaving the agent to infer when a manual update_place is preferable.

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

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

Annotations already establish this is a safe read (readOnlyHint=true, destructiveHint=false), so the description adds value beyond them: an explicit source precedence order, a cost figure ($0.10), an auth requirement (API key), and the anti-fabrication constraint. That is meaningful disclosure for a tool whose annotations only cover safety.

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 and source order are front-loaded, followed by the usage clause and cost/auth note in parentheses. It is dense but every clause carries information; the only minor cost is that the source listing is tightly packed.

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

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

An output schema exists, so return shape need not be described. Combined with the usage condition, auth requirement, cost, and source precedence, the description covers what an agent needs to invoke it correctly; the main residual gap is no explicit guidance on when to prefer a sibling retrieval tool instead.

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 query, fact (alias), and limit (1–20, default 8) are fully documented in the schema itself. The description adds nothing about parameter behavior or the query/fact aliasing, 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 states a specific verb and resource ('Return evidence/provenance for a claim') and even enumerates the source hierarchy it walks (polaris_learned_facts, life_events/life_event_relationships, memories), which makes it easy to distinguish from plain retrieval tools like get_memories. It stops short of naming a sibling tool to contrast against, so it is strong but not maximally differentiated.

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

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

'Use when the agent must cite why it believes something — do not invent sources' gives an explicit when-to-use condition and a behavioral prohibition. It does not name an alternative tool or state when not to use it, so it lacks the exclusion clause that would push it to a 5.

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