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

Annotations only give the generic safety profile (readOnly=false, idempotent=true, destructive=false); the description goes far beyond that with concrete effects: unblocking memory tools immediately, access only until next_billing_date, no data loss, clearing deletion_scheduled_at, and the prior cancellation of the PayPal subscription. It even discloses the 'not_scheduled' error code and confirms no rate limiting, which annotations cannot express.

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 outcome and immediate effect are front-loaded, followed by a clearly labeled 'Side effects' block and an error-case sentence. Every sentence carries actionable information, including the subscription-reactivation pointer and the error code, with no filler.

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

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

For a zero-argument state-changing tool with an output schema already covering return values, the description supplies the missing pieces an agent needs: what state is cleared, what access resumes, what the billing consequence is, and the failure mode. Nothing material is left to inference.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is a 4. The description correctly avoids inventing parameter talk and instead spends its words on behavior.

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

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

The first sentence names a specific verb and resource ('Cancel a previously scheduled account deletion'), which cleanly distinguishes it from siblings like amber_delete_account (irreversible) and amber_cancel_subscription (billing only). An agent can route between these 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?

The description establishes the precondition (a deletion must be pending) and the alternative path when the paid period has expired ('call amber_reactivate_subscription to start a new one'). It does not explicitly say when not to use it versus amber_delete_account, but the conditional guidance is clear enough for confident 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?

Goes well beyond the annotations: access continues until next_billing_date, data is preserved rather than deleted, the request is dispatched to PayPal immediately with a webhook-driven status update in ~1 minute, and each failure mode is enumerated with its consequence ('NOTHING was attempted', 'the subscription is unchanged, so it is safe to retry'). The explicit error.code-vs-status disambiguation for the colliding 'cancelled' name is a genuine behavioral disclosure that no annotation carries. The 'data is preserved' line is a useful clarification of destructiveHint=true rather than a contradiction.

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

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

Front-loaded with purpose and the exclusion, then delivery timing, then errors — a sensible ordering with no filler sentences. The error enumeration is dense and the 'cancelled' collision explanation is a long parenthetical that takes effort to parse, but every clause in it 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?

Covers purpose, exclusion, prerequisite, timing, data-retention consequence, and the full set of documented failure modes with recovery advice, which is everything an agent needs for a destructive, open-world mutation. Return-value detail is rightly omitted since an output schema exists.

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

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

Schema coverage is 100% and the single parameter's description already explains the true/false split, so the baseline is 3; the description still adds value by restating the confirm: true requirement and, more importantly, by mapping the confirm: false outcome to a specific error field so the agent does not mistake it for a completed cancellation. It does not repeat the stringified-boolean acceptance, but that is already fully documented in 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 and resource ('Cancel the user's PayPal subscription') and immediately bounds the scope by naming the sibling it is not ('Do NOT use if the user wants to delete their account entirely -- use amber_delete_account instead'). An agent can separate this from amber_manage_subscription, amber_reactivate_subscription and amber_delete_account without reading 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 explicit when-to-use, when-not-to-use, and the named alternative for the excluded case. It also states the confirm: true prerequisite and warns that confirm: false is a harmless intent check, which is exactly the routing information an agent needs before calling a cancel tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds materially more: the key is shown once and only a hash is stored, calling again silently replaces the previous key and kills any running job, the response reports when the replaced key was last used, and the key's true blast radius is exactly two capabilities (download export, start restore — the latter being a write). It also discloses that trashed memories are included in the backup and that a restore re-creates them as trash.

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 and well-structured with IMPORTANT and Usage markers, but it carries a meta-paragraph about a documentation correction ('Corrected 2026-09-19: this said ... which understated it') that helps no agent select or invoke the tool and reads as changelog noise. The operational content is dense but the correction digression and the duplicated 'relay it to the user' instruction cost it.

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

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

For a single-optional-parameter tool with an output schema, the description covers everything an agent needs: what it creates, the one-shot secret handling, rotation semantics, revocation path, rate limit, credential scope, and the warning behavior. Return-value details are correctly delegated to the output schema while the agent is still told to relay the secret and any replaced-key warning.

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

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

Schema coverage is 100% and the schema description for warn_after_days is already exhaustive, so the baseline is 3. The description still earns credit by adding an actionable directive the schema buries: 'ASK THE USER how long a gap without a successful backup should be treated as a problem,' plus the consequence of omission (30-day default, invisible failure). It does not restate the schema's interval-selection heuristics, which is appropriate.

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

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

States a specific verb and resource ('Create a key that lets an automated job download a full export of this account without an AI session') and immediately distinguishes it from amber_export_memories by scoping it to unattended/cron use. An agent can tell this apart from the sibling export and revoke tools without opening any schema.

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

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

Gives explicit when-to-use context (a weekly cron saving to S3/NAS), an end-to-end usage recipe (POST /backup with X-Amber-Backup-Key, poll GET /backup/<task_id>, then fetch download_url), names the revocation sibling (amber_revoke_backup_key), and states the one-per-hour limit. It also tells the agent to ask the user about the warning threshold before calling, which is guidance rather than mere description.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond: 30-day deferral, immediate memory-tool blocking versus continued access to account-management tools, automatic PayPal subscription cancellation, and the specific `already_scheduled` state on repeat calls. That is exactly the behavioral context annotations cannot express (timing, side effects on adjacent subsystems, reversibility window). Nothing here contradicts the destructive/idempotent hints.

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 timeframe, then consequences, then requirements, then return codes — a sensible ordering. Slightly redundant: memory tools being 'blocked immediately' is stated in the first line and restated in the grace-period paragraph, which could be merged.

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, single-parameter, open-world tool this covers everything an agent needs: irreversible-after-30-days warning, what breaks immediately, what still works, the reversal tool, and expected response codes. An output schema exists, so not enumerating return fields further is fine.

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

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

Schema coverage is 100% and the `confirm` description already covers the boolean and the stringified-boolean edge case, so the description is not required to explain the parameter. It still adds value the schema does not: the concrete return codes `cancelled` (confirm=false) and `already_scheduled`, which tell the agent how to interpret the response rather than the input.

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

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

States a specific verb and resource — 'Schedule permanent account deletion in 30 days' — and immediately distinguishes it from subscription cancellation ('unlike cancellation, which keeps access until period end') and from its own inverse tool `amber_cancel_account_deletion`. An agent can route correctly 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?

Explicitly separates this from the two nearest alternatives: subscription cancellation (which preserves access to period end) and `amber_cancel_account_deletion` (the reversal path). It also states the exact precondition (`confirm: true`) and what happens when it is false, so the when/when-not decision is fully determined.

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 destructive=true and idempotentHint=true, and the description adds real value beyond that: reversibility, skip-already-deleted semantics, the no-op vs not_found distinction, the async-write race that causes batch shortfalls, subscription requirement, and no rate limit. Minor deduction because the error/verification material is stated twice in slightly different words, diluting rather than contradicting the 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?

Core purpose and the sibling exclusion are front-loaded, but the text is dense and repetitive: the deleted_count-vs-sent check appears in the main body and again in the errors section, and the no-op vs not_found explanation is restated. Several clauses could be tightened without losing information.

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

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

For a destructive batch mutation this covers everything an agent needs: required argument cardinality, idempotency, partial-success accounting, error codes, the async-write caveat, and post-delete verification against the returned content. Output schema exists but the description still adds interpretive guidance on how to use those fields rather than merely repeating them.

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

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

Schema coverage is 100% and the schema already documents each parameter, so the baseline is 3. The description earns above baseline by stating constraints the schema does not encode: at least one id is required (required array is empty) and supplying both singular and plural yields invalid_params. It does not restate the max-100 limit, but that is already in 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 and resource ("Soft-delete one or more memories to the trash") and immediately names the two siblings it must be distinguished from: amber_restore_memory for reversal and amber_delete_account as the wrong tool for account-level cleanup. An agent can route to it 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-not guidance ("Do NOT use this for account-level cleanup -- use amber_delete_account instead") plus the alternative for undoing the action. It also prescribes the correct downstream flow after a shortfall (check amber_get_store_task_status and retry), covering the ambiguity an agent would otherwise guess at.

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 a safe read; the description adds the async contract (task_id returned before the file exists, poll amber_get_export_status), the no-truncation guarantee, subscription requirement, absence of rate limiting, record contents, and the queue_failed semantics with safe-retry guidance. That is substantial context the annotations cannot convey.

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

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

Paragraphs are grouped by concern (mechanics, the include_deleted decision, alternatives, async rationale, constraints) with the most important mechanics front-loaded. It runs long and the backup/include_deleted point is restated two or three times, plus "read-only" repeats the annotation, but nothing is genuinely off-topic.

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

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

Despite an output schema existing, the description still supplies the orchestration loop (task_id → poll → download_url) and the one documented failure mode, which is what an agent actually needs to complete the workflow. Nothing material is missing for a single-optional-parameter async export.

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 already 100%, yet the description adds real decision meaning for include_deleted: why backups must set it true, the reversibility rationale, and a concrete 121-vs-6,334 record example. It tells the agent how to choose the value, not just what it does.

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

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

"Start exporting your memories to a downloadable JSON file" gives a specific verb and resource, and the description explicitly separates it from amber_list_memories (paginated) and amber_search_memories (targeted lookup). An agent can pick it out of a 29-tool sibling set 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 names the triggering intents (backup, migration, "can I download my data?"), names the alternatives and the condition that rules them out, and adds the unattended-cron route via /backups. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-inferable behavior: no rate limiting, memory counts read as null after access lapses while data is preserved, access persists past `subscription_active` until `next_billing_date`, and the meaning of `deletion_scheduled_at`. This is exactly the operational context annotations cannot carry.

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

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

Front-loaded with purpose and trigger before the edge-case detail, and the closing 'Read-only... Not rate-limited' tags are efficient. The middle sentence is convoluted and partly restates itself ('note that is later than `subscription_active` turning false, because a cancelled subscription keeps access until its paid period ends and reports real counts until then').

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 zero-param read with an output schema and full annotation coverage, the description covers everything an agent needs: what triggers it, what the returned states mean over the subscription lifecycle, and where to go to reverse a pending deletion. No meaningful gap remains.

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

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

Zero parameters, so the baseline is 4. The description instead spends its words on return-field semantics (what `next_billing_date` and null memory counts mean), which is useful even though an output schema exists.

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 ('Return the authenticated user's account summary') and enumerates exactly what comes back: subscription state, next billing date, memory counts, creation date. An agent can immediately distinguish this read-only status snapshot from the sibling mutation tools like amber_manage_subscription or amber_cancel_account_deletion.

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

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

Gives an explicit trigger ('Use this when the user asks about their account, subscription status, or how many memories they have') and routes one adjacent case away with 'use amber_cancel_account_deletion to stop it'. It does not, however, disambiguate against amber_manage_subscription or amber_cancel_subscription for subscription-related questions, so the routing is partial rather than 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?

Goes well beyond the annotations: states it is not rate-limited, requires an active subscription, and documents the status semantics, progress signal (`memory_count` climbing), 7-day retention and post-expiry `code: not_found`. The resumable-Range detail is genuinely useful. Minor gap: no note on whether polling itself incurs costs or how long a `pending` task may sit before it counts as stalled.

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

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

Front-loaded with purpose and usage, then statuses, then link lifetime — a sensible order. Slightly redundant: the 7-day export retention is stated twice ('valid for 7 days, matching how long the export itself is kept' and later 'The export itself is kept for 7 days').

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 spelled out, yet the description still covers statuses, error signalling and link expiry. For a one-parameter polling tool this is complete; nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already explains that `task_id` is the id returned by `amber_export_memories` and that unknown/expired ids yield `not_found`. The description repeats that provenance rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Check an export started by `amber_export_memories`') and adds the second function (collect the download link). It names the sibling that creates the export, so the agent can tell it apart from the import-status and store-task-status 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?

Explicit operating instructions: poll every few seconds, only report ready once status is `complete`, and call again for a fresh link if the URL expired. The lifecycle (pending/running/complete/failed) gives the agent the decision rules it needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral context: not rate-limited, requires an active subscription, full status lifecycle, 7-day task expiry, and the `not_found`/`invalid_input` error surface. It also explains that `imported_count` counts processed memories with no total available, which prevents an agent from misreading a stall.

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?

Long but front-loaded and organized into purpose, status vocabulary, progress semantics, and failure handling, with no filler sentences. The closing note on `amber_upload_backup` is slightly tangential for a status tool but earns its place as a next-step pointer.

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 re-specified, yet the description still defines every status value and the meaning of `imported_count`, plus the trash-restore edge case. For a single-parameter polling tool this leaves nothing an agent needs unresolved.

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 `task_id` is already documented, but the description adds meaning the schema does not: it enumerates every call that can produce the id and explains that a mismatched or aged-out id surfaces as `not_found`. That is useful routing context rather than a restatement.

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 ('Check a restore in progress') and immediately scopes it to every way a restore can be started, which separates it from the starter tools (`amber_upload_backup`, `amber_import_memories`) and from the export-status sibling. An agent can tell this is the polling endpoint for imports without opening the schema.

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

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

Explicitly covers when to use it (polling a restore regardless of origin), what to do on failure (relay `error`, restart safely, use a fresh backup if the file is damaged), and routes the agent to `amber_upload_backup` when the user still needs to get a file in. It even pre-empts a wrong inference by saying `awaiting_upload` is not a failure.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint:false, but the description goes further: it resolves IDs across active AND trashed memories, explains that a non-empty `deleted_at` marks a trashed record, documents the `code: not_found` failure case, and states it is not rate-limited but requires an active subscription. That is meaningful behavioral context beyond structured fields.

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

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

Front-loaded with the purpose and the truncation trigger, then the return shape, then edge cases (trash, not_found, rate limit, subscription). No sentence is filler; each adds a distinct operational fact.

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

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

For a single-parameter read tool with an output schema and full annotations, this covers everything an agent needs: when to call it, what it returns (content, metadata, topics, created_at), how trashed records behave, and the failure mode. Nothing material is missing.

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

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

Schema description coverage is 100% and the schema already tells the agent where memory_id comes from (store task results, search items, list pages). The description adds the truncation rationale for fetching by ID but no additional constraint on the ID format itself, so baseline 3 applies.

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

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

States a specific verb+resource ('Retrieve a single memory by its ID') and immediately scopes it as 'full, untruncated content', which distinguishes it from the search/list siblings that truncate. An agent can tell exactly which tool fetches a complete record.

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

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

Explicitly names the trigger condition: use after `amber_search_memories` when a result shows `truncated: true`, or when a memory_id is already known. It also names `amber_restore_memory` as the follow-up for trashed records, routing the agent correctly instead of guessing.

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

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

Well beyond the annotations: it discloses durability semantics (an accepted store is already durable), the exact four status values with meanings, background completion timing, no rate limiting, subscription requirement, queue-redelivery idempotency vs client-retry duplicate risk, partial searchability during writing, and 7-day pruning with `code: not_found`. Annotations already cover read-only and idempotent, and the description is consistent with them; minor deduction because return-value detail partly duplicates the existing output schema.

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

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

Front-loaded with purpose and the key instruction (don't block on completion), and the status vocabulary is laid out cleanly. Some phrasing is editorial rather than informative ('note the `ed`', 'waited for ever', 'That is Amber retrying internally'), which costs a little density but not comprehension.

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 polling tool with an output schema, everything an agent needs is present: when to call, how to interpret each status, how long to wait, what partial results mean, and how expiry/not_found is surfaced. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and both parameters already document their roles, including the task_id/idempotency_key alternative, so the schema carries the burden. The description reinforces the idempotency_key case indirectly via the client-retry duplicate warning but adds no new syntax or format detail beyond the schema.

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

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

Opens with a specific verb and resource: 'Check the processing status of a memory store task.' It explicitly separates itself from the similarly-named import/export status siblings by calling out that the import tool's vocabulary ('awaiting_upload', 'running', 'complete', 'failed') was mistakenly published here, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use ('before you list, search for or delete the facts you just stored', 'when the user asks whether something was saved') and explicit when-not/wait guidance ('Do NOT hold your reply to the user waiting for completed'). It also states the polling rule and the prerequisite of an active subscription, leaving little 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 cover idempotency and non-destructiveness, but the description adds far more: no copy is stored, the link must remain valid for the whole multi-hour restore and is re-read as work proceeds, a partial restore resumes, and the operation is additive only. It also discloses the subscription requirement and the full set of invalid_params causes, plus the fact that validation happens before any task is created.

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 scope, then organized into short scannable blocks for usage, link lifetime, re-run safety, return value, and errors. It is long, and the capitalized emphasis plus slight repetition about link validity cost a little, but nearly every sentence carries decision-relevant information for an agent.

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

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

Despite an output schema existing, the description still names the returned task_id and the required follow-up (poll amber_get_import_status until complete, then report the count), which closes the loop for a long-running async operation. Nothing an agent needs to call this correctly — prerequisites, link requirements, resume semantics, error handling — 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% and already documents HTTPS, credential-free access, and range-request support, so the schema does the heavy lifting. The description still adds operational meaning the schema lacks — that the link must survive at least 30 days for a large account, and that URLs pointing back at Amber or carrying credentials are rejected.

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 — restore an Amber backup from a URL — and immediately distinguishes it from the sibling paths (amber_upload_backup for local files, amber_export_memories for the reverse direction) by explaining that Amber reads the archive directly from the URL. An agent can route correctly 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 explicit when-to-use conditions (file reachable over HTTPS: S3, R2, Backblaze, GCS, MinIO, presigned link) and an explicit when-not with a named alternative destination (https://ambermem.com/backups for files only on the user's computer). It also pre-empts a wrong workaround ("Do not ask them to paste the file contents").

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context beyond them: subscription requirement, no rate limiting, full untruncated content in results, exhaustive database-level filtering semantics, and the specific `invalid_input` error condition. The only gap is it doesn't contrast behavior with hard-delete (amber_delete_memory) beyond asserting it never permanently deletes.

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

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

Well front-loaded — purpose and pagination first, alternatives second, semantics third. Slightly padded by restating return fields (`memories`, `next_cursor`, `has_more`) that an output schema already documents, and by re-explaining metadata_filter caveats already present in 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?

For a 3-parameter read tool with an output schema, the description covers scope, ordering, pagination, filtering semantics, auth requirement, and error modes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description adds cross-tool meaning: the metadata_filter behaves the same exhaustively as in amber_list_memories, and after_id/has_more pagination contract is spelled out. Marginal added value over the already-detailed schema, hence 4 rather than 5.

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

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

Opens with a specific verb+resource+scope: 'Browse the trash in reverse chronological order of deletion (most recently deleted first).' It is immediately distinguishable from amber_list_memories (live memories) and amber_search_deleted_memories (meaning-based search within trash), both of which are named.

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

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

Explicitly routes the agent: use amber_restore_memory to bring an item back, use amber_search_deleted_memories for meaning-based search. It also states the prerequisite (active subscription) and that it is not rate-limited, leaving little to infer about when to pick this tool.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description still adds non-obvious operational facts: not rate-limited, requires an active subscription, cursor rejection semantics for cross-account or old-schema cursors, and that full content is returned untruncated. The only minor gap is that it does not discuss page-size effects on latency or any ordering guarantees under concurrent writes, so it falls just short of the top.

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

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

Front-loaded with purpose and routing before details, and nearly every sentence carries new information. It is somewhat long and repeats cursor/pagination mechanics already spelled out in the schema's after_id description, which is the main deduction.

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 scope, ordering, pagination contract, filter semantics, safety, prerequisites, error cases, and return shape for a 3-parameter tool with nested objects. Even though an output schema exists (making the return-value sentence partly redundant), nothing an agent needs in order to call 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% and the parameter descriptions are already very detailed, so the baseline is 3. The description still adds genuine meaning by contrasting this tool's metadata_filter (database-level, exhaustive) against search's post-ranking filter, which is a semantic distinction not stated in the schema itself.

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 ('Browse all active memories') plus ordering ('reverse chronological, newest first'), and explicitly names the sibling it is not: amber_search_memories. An agent can distinguish browsing from searching without opening either schema.

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

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

Gives explicit routing rules: 'Prefer amber_search_memories when looking for specific content; use this when the user wants a browsing overview or asks "show me my recent memories"'. It also adds a second decision rule for metadata_filter (exhaustive vs relevance-bounded search), which is a real when-to-use distinction rather than an implication.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context they do not carry: 'not rate-limited' and 'Requires an active subscription.' It also discloses the critical behavioral trait that subjects match by EXACT text and that forks produce silently incomplete search results.

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

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

The core action and the reuse-existing-spelling rule are front-loaded, and every paragraph is on-topic. The fork-detection section is long relative to a one-parameter list tool, but it carries genuinely non-obvious guidance 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 not be spelled out, and the description still covers ordering, the count/topics payload, the subscription prerequisite, and the exact-match pitfall. Nothing an agent needs to call 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% and the single `limit` parameter is fully documented in the schema, including default and ordering. The description only echoes the 'most-mentioned first' ordering, adding no new syntax or constraint 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 ('List the subjects (people) already in memory') plus ordering ('most-mentioned first') and return shape ('a count and the `topics`'). It is clearly distinguishable from siblings like amber_search_subjects and amber_list_topics.

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

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

Explicitly says to call it before amber_store_memory or amber_search_memories when unsure how a person was recorded, and names amber_rename_subject as the repair path. It also gives a concrete when-to-use signal for the `topics` field (detecting split subjects) and an explicit prohibition (never merge on your own 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the default filter (only live topics), the existence of orphaned 0-count topics and why they persist, that the operation is not rate-limited, and that it requires an active subscription. The subscription prerequisite and default-hiding behavior are exactly the kind of context annotations cannot express.

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

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

Front-loads the core behavior, then usage guidance, then defaults and constraints — good ordering with no filler. The single dense run-on covering defaults plus orphan explanation is slightly heavy but 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?

For a two-optional-parameter read tool with an output schema, the description covers purpose, prerequisites, defaults, and downstream usage. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining the *reason* include_empty exists (topics aren't deleted when their memories are) and reinforcing most-used-ordering for limit. It adds rationale rather than new mechanical detail, so not quite a 5.

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

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

States a specific verb and resource ('List the topics (tags) already in use, most-used first') and immediately differentiates itself from the sibling tools it interacts with (amber_store_memory, amber_search_memories). An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly prescribes when to call it ('before amber_store_memory when you're unsure whether a topic already exists') and what to do with the result ('REUSE an existing name instead of minting a near-duplicate'), including a concrete example. It also names the downstream consumer of consistency (the `topics` filter in amber_search_memories), which is genuine 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description nonetheless adds real context beyond them: Amber never touches payment details, PayPal owns the self-service page, and a `code: no_subscription` result is possible. It loses a point for restating the read-only/no-side-effect property twice (once as 'no changes are made by calling it' and again as 'Read-only -- does not modify the subscription'), which duplicates what the annotations already say.

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?

Structure is good: purpose first, then when-to-use, then sibling differentiation, then failure/behavior notes. The only weakness is mild redundancy between 'no changes are made by calling it' and 'Read-only -- does not modify the subscription,' plus the standalone 'Not rate-limited' fragment, which could have been folded in.

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 does not need to document return values, yet it usefully names the two things returned (URL and next billing date) and documents the `no_subscription` error branch. For a zero-parameter read tool with rich annotations, nothing an agent needs in order to call it correctly is missing.

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

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

There are zero input parameters, so there is no parameter meaning to add and the baseline is 4. The description correctly focuses on outcome (URL plus next billing date) rather than inventing parameter guidance that does not apply.

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

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

The description opens with a specific verb and resource ('Return a PayPal URL... to manage their subscription') and enumerates the concrete actions enabled (update payment method, view billing history, change payment source). It then explicitly contrasts itself with `amber_cancel_subscription` and `amber_reactivate_subscription`, so an agent can disambiguate without opening any schema.

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

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

It gives an explicit trigger ('Use this when the user asks about billing, wants to change their payment method, or wants to view their subscription details') plus explicit when-not guidance via the two named sibling alternatives. It even routes the `no_subscription` failure case to `amber_reactivate_subscription`, which is exactly the kind of fallback routing an agent needs.

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: it names the database effect (row deletion), the specific error shape on repeat calls (`code: not_found`), and that the tool is not rate-limited. It even reconciles the idempotentHint annotation with the not_found behavior ('idempotent in intent but...'), which is precisely the nuance 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?

Front-loads the action and consequence, then side effects and preconditions. The developer_notifications explanation is long-ish but earns its place because absence of the block is easily misread by agents. No filler sentences.

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

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

For a single-parameter destructive mutation, the description covers precondition, persistence effect, error behavior, rate limits, and the confusing absence-of-block case. With annotations and an output schema also present, nothing material is missing.

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

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

Schema coverage is 100% and the schema already explains that the value is a positive integer from the `id` field, with a worked example. The description adds only the surrounding context of where that ID lives, not new parameter semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Dismiss a developer notification') and immediately specifies what that means ('Permanently removes it from the `developer_notifications` block'), so an agent knows exactly what the call 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 prerequisite ('Only call after the user has seen the notification content') and clarifies when the notification block is present vs absent. No sibling tool offers a comparable action, so no alternative routing is needed, but there is no guidance on what to do instead when the block is absent.

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 by disclosing pricing/trial terms, that no charge occurs before approval, that each invocation mints a new pending subscription and invalidates older links, that approving one cancels other active subscriptions on the account, and specific status/error codes (`already_active`, `deletion_scheduled`, `creation_failed`) with retry safety. The non-idempotent behavior is explicitly justified by 'each call creates a NEW pending subscription', which aligns with `idempotentHint: false`.

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

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

Front-loads the action and the hard requirement, then layers first-time/returning behavior, status codes, and errors in a scannable order. It is dense with genuinely useful facts, though a few lines (the double-billing explanation) are longer than needed for an agent to act correctly.

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

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

Despite an output schema existing, the description usefully pre-declares the branches an agent must handle (`already_active`, `deletion_scheduled`, `creation_failed`), plus the human-in-the-loop browser step that annotations alone would never convey. For a zero-param, open-world, non-idempotent mutation, nothing material is missing.

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

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

The tool takes zero parameters, so the 4 baseline applies; there is no input surface for the description to clarify further. The description correctly spends its words on flow branching and outcomes rather than inventing parameter details.

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

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

Opens with a specific verb and resource plus the concrete return artifact: 'Create a PayPal subscription and return an approval URL.' It immediately distinguishes itself from `amber_manage_subscription`, so an agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use ('first-time' vs 'returning' flows), explicit when-not ('Do NOT use if the user just wants to manage an existing subscription'), and names the sibling alternative to use instead. It also states the required post-call user action (must open the URL in a browser) and the account-matching warning.

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, disclosing merge behavior, the irreversibility of a merge, that deleted memories are also relabelled (so renamed_count can exceed the active count), that a no-op returns 0 rather than an error, the subscription requirement, and the invalid_input conditions. The destructiveHint=false annotation is consistent with the stated "NEVER deletes a memory"; the description productively refines that by explaining that irreversibility arises from merging, not deletion.

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 the exact-match retrieval rationale are front-loaded, and the risk disclosure follows in a logical order. It is a dense block of prose with some repetition around the merge warning, so it is efficient rather than optimal.

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

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

For a two-parameter mutation with an output schema already present, the description covers everything an agent needs: when to call it, what it returns, what it touches (including trashed memories), what is reversible, and what error to expect. Nothing material is left to inference.

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 schema coverage at 100% the schema already documents both parameters, so the baseline is 3. The description still adds real meaning: shared case-insensitive matching and normalization of both names, plus the invalid_input failure modes (empty, oversized, control characters) that the schema does not state.

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

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

States a specific verb and resource ("Relabel a subject (person) across EVERY memory tagged with them") and makes the scope explicit, which separates it cleanly from amber_list_subjects, amber_search_subjects, and amber_update_memory. The parenthetical example of a first name becoming a full name removes any ambiguity about what 'rename a subject' means in practice.

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 both trigger cases (a name changed, or you learned more of it) and names the prerequisite alternative, amber_list_subjects, for confirming exact spellings. It also supplies an exclusion-style warning: when merged_into_existing would be > 0, be sure and confirm with the user first, which is actionable decision guidance rather than generic advice.

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: discloses the side effect (moves memories from trash to active), subscription requirement, absence of rate limiting, no-op vs not_found distinction, and non-atomic batch behavior. The idempotentHint is expanded into concrete mechanics (already-active entries return in already_active_ids) rather than merely restated.

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

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

Front-loaded with purpose and when-to-use, then parameter mode, then return-value verification, then errors — a logical order with no filler sentences. It is long and heavy on emphatic capitalization, which is slightly excessive for the amount of distinct information conveyed.

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

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

Even with an output schema present, the description explains how to reconcile the counts (restored + already_active_ids + not_found_ids) and warns that batches are not all-or-nothing — exactly the reasoning an agent needs before trusting a restore result. Error taxonomy and the no-op-not-an-error case are both covered.

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 would be 3, but the description adds a real constraint the schema does not express: the schema declares zero required properties, while the description states 'At least one is required' and that supplying both singular and plural triggers invalid_params.

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 ('Un-delete memories from the trash') plus the resulting state change ('making them searchable and visible in amber_list_memories again'), which immediately distinguishes it from amber_search_deleted_memories and amber_list_deleted_memories.

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

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

Explicitly names the triggering workflow ('Use after amber_search_deleted_memories or amber_list_deleted_memories to recover accidentally deleted content') and gives an explicit exclusion with the correct alternative ('Do NOT use for new content -- use amber_store_memory instead').

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds the real blast radius: dependent automated jobs stop working immediately. It also discloses the not-found outcome ('Returns `code: not_found` if no key exists') and the operational trait 'Not rate-limited', none of which appear in structured fields.

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

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

Four tight sentences, front-loaded with the action and its consequence, then the use case, the error case, and the alternative. No sentence is filler; the rate-limit note is short and load-bearing.

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 fills the remaining gaps: consequence of revocation, when to prefer rotation, error behavior, and rate-limit status. For a zero-param mutation tool, nothing an agent needs before invoking is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema shows. The baseline for a parameterless tool applies, and the description correctly avoids inventing argument details.

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 ('Revoke this account's backup key') and immediately scopes it to a single key, which separates it from sibling tools like amber_delete_account. It also names the related rotation tool, so an agent can tell revoke apart from rotate without reading either schema.

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

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

Gives an explicit trigger ('Use this if a key may have leaked -- for example it was committed to a repository or pasted into a log') and names the alternative with the condition that selects it ('To rotate instead of simply revoking, call amber_create_backup_key'). When-to-use, when-to-rotate, and the sibling route 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 readOnlyHint/idempotentHint, and the description adds substantial behavior beyond them: relevance ordering with scores only comparable within one query, 1000-char content truncation, and a concrete rate-limit budget (5000 capacity, ~1 refill per 17s). It also documents the invalid_input error class, which the annotations cannot express.

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

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

Front-loaded with purpose, then usage trigger, then ranking/filter semantics, then operational limits and errors — a sensible order. It is dense and slightly long, but nearly every clause carries information an agent needs; only the repeated 'exactly like amber_search_memories' framing is mildly redundant.

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

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

For a 10-parameter search tool with a nested metadata_filter object, the description covers the gaps the schema leaves open: ranking interpretation, truncation, rate limits, error surface, and the restore path. Since an output schema exists, return-value structure need not be restated, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning the schema cannot: subjects/query_variants/keywords are the SAME steering contract as amber_search_memories, and topics is semantic rather than exact. It also flags max_age_days as a recency restriction, clarifying the interplay of filters versus ranking boosts.

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

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

Opens with a specific verb and resource: 'Search within the trash for soft-deleted memories.' This cleanly separates it from amber_search_memories (active memories) and amber_list_deleted_memories (enumeration without query). An agent can pick the right tool from the first sentence 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?

Gives an explicit trigger ('when the user asks about something they've since deleted') and names the follow-up alternatives with conditions: amber_get_memory for full content past the 1000-char truncation, amber_restore_memory to bring a result back. It also explains that steering params mirror amber_search_memories, so the agent knows behavior transfers across tools.

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

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

Goes far beyond the readOnly/idempotent/non-destructive annotations: discloses that results are ranked rather than filtered (with the anti-inference warning), 1000-char truncation, score non-comparability across queries, the drip-bucket rate limit, `filter_truncated` semantics, and topic lift bounds. The near_date paragraph, however, is self-referentially muddled ("the score claim did not, and this sentence used to make the stronger one"), leaving the agent unsure which claim currently holds — that undercuts otherwise excellent 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 reasonably at the top, but the body is bloated and repeats schema parameter prose nearly verbatim, then drifts into corrective meta-commentary about its own earlier wording. Sentences like "the ordering claim holds, the score claim did not, and this sentence used to make the stronger one" cost the reader without adding callable information.

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

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

For a 9-parameter hybrid-search tool with nested `metadata_filter`, this covers the full decision surface: relevance judgement, absence inference, temporal ordering/timeline reading, error semantics, and how to get complete result sets. Nothing an agent needs in order to call it correctly is missing, and the output schema means return shape needn't be spelled out.

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 already 100%, so the baseline is 3, but the description adds real decision-level meaning: query must be natural language not keywords, `query_variants` replaces server-side expansion and should carry 3-6 phrasings, `keywords` must omit the subject name, and `subjects` uses exact case-insensitive matching with the `self`/`anyone` conventions. It also explains the topics-resolved/lift interaction that the schema alone does not make actionable.

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?

Opening sentence gives a specific verb+resource+scope: "Find active memories by semantic meaning." It then explicitly separates itself from siblings, naming `amber_list_memories` for chronological browsing and `amber_get_memory` for full content, so an agent can route correctly without opening another schema.

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

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

Gives explicit when-to-use guidance (search-before-store check, relative-time queries need `near_date`), explicit when-not (don't pass `near_date` for time-agnostic questions, omit `topics` if unsure), and names the alternatives `amber_list_memories` (exhaustive filtered listing), `amber_list_topics`, and `amber_list_subjects`. It even specifies the diagnostic escape hatch per parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuinely new operational facts — "not rate-limited" and "Requires an active subscription" — which is real value beyond the annotations, but it says nothing about result ordering or truncation behavior beyond what the schema states.

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 sentence, then clearly delimited MATCHING and limitation sections with bulleted examples — easy to scan. It runs long and repeats the "same as amber_list_subjects" equivalence twice, but the length is buying disambiguation 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?

For a two-parameter search tool with an output schema, the description covers everything an agent needs to call it correctly: matching semantics, fallback path, rate-limit and subscription prerequisites, and an explicit statement of what the tool cannot do. No material gap remains.

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 substantial meaning the schema does not: normalization rules (case- and accent-insensitive, spaces/hyphens/apostrophes/periods ignored on both sides, word order still significant) and worked examples. The only gap is the `limit` parameter, whose semantics are left entirely to the schema.

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

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

Opens with a specific verb and resource plus scope: "Find subjects (people) already in memory WITHOUT listing them all," and immediately states the returned fields (name, memory count, topics). It names the sibling amber_list_subjects and explains precisely how the two differ (filtered vs. full listing).

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

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

Explicitly routes the agent: "Prefer this over amber_list_subjects once a store has grown," with a token-cost rationale, and gives a reverse condition too — when text matching cannot resolve a person, fall back to listing subjects and comparing `topics`. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive, but the description adds what they cannot: a concrete rate limit (12 capacity, 1 refill per 5 minutes), a prohibition on sensitive data, and the post-send user communication protocol. This is exactly the behavioral context that structured fields 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?

Purpose comes first, then triggering conditions, then constraints, then operational limits — a sensible front-loaded order. Every sentence carries distinct information (what, when, privacy rule, rate limit) with no repetition of the schema or title.

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

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

The tool is simple, an output schema exists so return values need no explanation, and the description covers the non-obvious risks (rate limiting, leaking secrets, asking permission). Nothing an agent needs to call this safely and 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% and the field-level descriptions already explain 'category', 'summary', 'details', and 'tool_context' with examples. The description only adds a cross-cutting constraint ('never include passwords, API keys... in any field'), which is useful but not per-parameter guidance, 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 ('Send a structured bug report, feature request, or general feedback to Amber's developer') and enumerates the categories of content it accepts. No sibling tool in the list does anything similar, so the agent can identify it immediately.

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

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

Explicitly names the triggering conditions ('errors, unexpected behaviour, or the user expresses frustration') and tells the agent how to behave toward the user ('briefly mention it... but do not ask for permission first'). This is a rare case of both when-to-use and interaction protocol being spelled out.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description supplies the real behavioral profile: writes are asynchronous and rows are unqueryable until a task reports completed, dedup is byte-identical and same-call only, retries without an idempotency_key duplicate data, and each named error (invalid_input, queue_unavailable, idempotency_key_reused) is documented with whether anything was written. That is materially more than the annotations convey.

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

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

The purpose is front-loaded correctly, but the text runs to well over a thousand words and restates the same warnings repeatedly — non-deduplication is asserted in the opening paragraph, again under SEARCH FIRST, and again in the fresh-context warning; the atomicity rule is stated, then restated as a split test, then as a worked example. Much of this is genuinely necessary for a tool with strict validation, but the redundancy and the bullet-dense formatting make it hard to scan, and a tighter version would lose no instruction.

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 strict server-side validation and a rejection-not-truncation failure mode, the description covers batching limits, field-level limits, control-character rejection, per-index error reporting, async task polling, and an inline call example. Nothing an agent needs in order to call it successfully 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 a baseline 3 would be defensible, but the description adds operational meaning the schema cannot: the split test for what counts as one atomic fact, worked examples of valid variant sets, and why subjects are matched by exact text so full stored spellings must be reused. It also explains the exact retry contract for idempotency_key (same key, same facts, same order), which changes how the parameter is used.

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

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

Opens with a specific verb and resource ("Store long-term memories") and immediately names the retrieval sibling ("you can search later with amber_search_memories"), so an agent knows exactly what this does and which tool consumes its output. It also distinguishes itself from sibling writers by stating that Amber "only validates and stores what you send" rather than extracting facts itself.

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

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

Gives explicit routing rules: call amber_search_memories before storing, skip unchanged facts, delete-then-store when a fact supersedes an old one, and use amber_get_store_task_status before acting on accepted rows. It also bounds the search-first rule with a when-not ("do NOT hold your reply to the user waiting for it"), which is rare precision.

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

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

Beyond the annotations, the description discloses that the tool deliberately works on trashed memories, that subject replacement clobbers the whole subject set, that an empty subject removes all subjects, and that rederive_subject is ignored when subject is supplied. It also documents subscription requirements, store limits (3 topics, 4000 bytes of metadata), and not_found/invalid_input error behavior. This goes well beyond what readOnlyHint=false and destructiveHint=false convey.

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

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

The description is front-loaded with the core purpose and then structured into a clear field-by-field bullet list, followed by matching guidance, an example, and errors. Despite being long, the length is justified by nine parameters and multiple non-obvious semantic distinctions; no sentence is filler.

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

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

Everything an agent needs to call this correctly is present: required memory_id, optional fields and their interactions, trashed-memory behavior, matching rules, subscription requirement, limits, and error cases. The output schema covers the return value, so the description does not need to explain the full response shape beyond noting that it returns the updated memory.

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?

Although the schema has full description coverage, the description adds important semantics that are not merely restated: subject REPLACES every subject, add_subjects/remove_subjects modify co-subjects without clobbering, subjects match by exact case-insensitive text while topics match semantically, and set_metadata/clear_metadata operate at field level. It also explains the interaction between subject and rederive_subject and gives a concrete correcting example.

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: 'Correct a stored memory after the fact' for subject, tag, and metadata fixes. It explicitly excludes rewording facts and names the correct alternative workflow (delete and store the corrected version). It is easy to distinguish from siblings such as amber_rename_subject, amber_store_memory, and amber_delete_memory.

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

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

It says exactly when to use the tool: noticing a wrong or missing subject, tag, or stale metadata, including while reviewing search results. It also gives explicit when-not guidance for rewording a fact and for replacing versus adding subjects. Alternative tools are named for listing subjects and topics before reuse.

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

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

The annotations already declare idempotentHint=true and destructiveHint=false, and the description usefully corroborates the idempotency claim by explaining that re-uploading duplicates nothing because memories keep their ids. It also adds the subscription prerequisite and panel-driven action semantics that annotations cannot express. However, the dry-run-ish description of what the panel does versus what the tool does is somewhat repetitive, and the error catalogue, while helpful, partly duplicates what the schema-adjacent contract already implies. Strong added context net of annotations, but not fully leveraged.

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

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

The description is front-loaded with the primary action and alternative, then the panel-driving caveat, then fallback and errors, which is a sensible ordering. It is dense but nearly every sentence carries actionable information; the parenthetical error glossary is the only section that runs long relative to its value.

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

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

An output schema exists so return values need not be described, and the description still covers the gaps that matter: subscription requirement, key prerequisite for the web fallback, panel-vs-agent division of labor, and a full error taxonomy including which errors originate from a different tool. An agent has everything needed to act or to hand off.

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

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

Schema coverage is 100% and both parameter descriptions already say the panel sets them, so the baseline is 3. The description adds the rationale an agent needs to resist orchestrating the call itself ('the `prepare` and `finish` actions are driven BY THE PANEL, not by you'), which is meaningfully more than the schema conveys.

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

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

The description opens with a concrete verb and resource: it shows a drag-and-drop panel that restores a backup located on the user's own computer. It explicitly separates this from the sibling `amber_import_memories`, which handles already-online archives, so an agent can pick the right tool without inspecting either schema.

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

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

It states the condition for use (file is local), the exclusion with a named alternative (online backup → `amber_import_memories` with URL), the no-argument invocation pattern, and a third path for clients that cannot render panels (open the web uploader). It also routes follow-up progress checks to `amber_get_import_status`, 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.