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

Annotations only declare readOnly/openWorld, but the description adds substantial behavior: the two-call sequence to the public /minimal then /active endpoints with the ?ctxc= parameter, the default-to-latest-flow behavior, and the size-ceiling fallback that returns size and top-level keys until view="raw" is requested. This is real operational context beyond the annotations.

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

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

Front-loads purpose and credential requirements, then layers the two-call mechanics and fallback behavior. Every sentence is informative, though the low-level endpoint paths are more implementation detail than an agent strictly needs to select and invoke the tool.

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

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

With no output schema, the description still explains the response shape (compact projection vs raw payload), the truncation fallback, and the credential environment. An agent has everything needed to call it and interpret a size-only response.

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

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

Schema description coverage is 100%, so both params are already documented, and the description largely restates the compact/raw distinction. It does add workflow meaning by framing view="raw" as the recovery step after a ceiling-truncated response, which links the parameter to observable behavior rather than repeating it.

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

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

States a specific verb and resource ('Read a HoneyBook questionnaire (flow)') and enumerates what is returned — pages, questions and submitted answers. This distinguishes it cleanly from generic siblings like get_project or get_workspace, and it ties the tool to the flow credential realm.

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

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

Explicitly states the prerequisite (a credential captured by `use_flow_link`), the exclusion ('a client-portal session will NOT work here, and vice versa'), the default behavior ('most recently captured flow'), and points to `list_active_sessions` for ids. When-to-use and when-not are both 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description earns credit beyond that by enumerating what the read yields, including per-recipient delivery status and optional original HTML, which is real behavioral context. Permissions and pagination/limits remain unstated, keeping it below a 5.

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

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

A single front-loaded sentence with zero filler; the return contents are enumerated compactly after the verb and scope.

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

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

With no output schema, the description usefully carries the return-value burden by listing the fields returned. It is nearly complete for an agent to call it correctly, missing only caveats about session/origin handling and any size or access limits.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the format enum and its "text" default. The description only echoes the text-vs-HTML format choice and adds nothing about origin, workspace_id, or message_id. Baseline 3 is appropriate.

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

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

Specific verb ("Read") plus resource ("one message") and an explicit scope of what is returned: body, sender, recipients, attachments, delivery status. This cleanly distinguishes it from list_messages and send_message among the 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?

"Read one message in full" implies the single-message vs list case, but no alternative is named and there are no stated conditions or prerequisites (e.g., when to prefer list_messages first, or auth/session needs). Usage is inferable but not 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 already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuine behavioral value by warning that view="raw" is large and embeds the vendor's whole account — useful for cost/context budgeting, though it says nothing about pagination or errors.

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

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

Purpose and return contents are front-loaded, followed by the one non-obvious caveat about raw. Two sentences, no filler, no repetition of the name.

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

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

No output schema exists, so the description carries the burden of describing the return shape — and it does, enumerating fields and the compact/raw difference. It omits error/empty-project behavior and session/origin prerequisites, which the schema only hints at.

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

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

Schema description coverage is 100%, so the schema already documents project_id, origin, and both view values including the 'embeds the vendor's account' caveat. The description's view="raw" note mostly restates the schema, 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 resource (project details) and enumerates exactly what is returned — Overview card fields plus participants. An agent can distinguish it from list_projects, which is referenced in the schema's project_id description.

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

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

Usage is implied: fetch a single project by id, presumably after list_projects. There is no explicit when-to-use/when-not statement and no alternative tool is named, so the agent must infer the 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=true and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that status flags like has_sent_files, has_signed_files, and has_paid_payments are included, but it does not describe permissions, rate limits, or other behavioral traits.

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

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

Two tight sentences with no wasted words. The core purpose is front-loaded, followed immediately by useful return-value examples.

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

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

For a simple read-only getter with full schema coverage and annotations, the description is largely complete. It hints at return contents via status flags, though without an output schema it could say more about what 'full detail' includes.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds no additional syntax, format, or semantic detail beyond what the schema provides.

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

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

The description states a specific verb ('Get') and resource ('full detail for a workspace'), and clarifies the domain alias '(vendor project)'. It does not differentiate from siblings like get_project or get_workspace_file, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as get_project or get_workspace_file. The implied context ('full detail') is minimal, leaving the agent to infer usage from the name alone.

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

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

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds real behavior: the default is a compact summary (~5-15 kB) and 'raw' may exceed MCP size limits on proposal-class files. This size/side-effect context goes beyond the annotations usefully.

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

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

Purpose is front-loaded, followed by enumerated section semantics. Slightly long but every clause earns its place; minor redundancy between naming the section and describing its content.

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

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

No output schema exists, so the description must carry return-value context, and it does by describing what each section returns. Adequate for a single-file detail tool, though the origin parameter and its session dependency are not elaborated here.

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

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

Schema coverage is 100% (baseline 3), and the description still adds meaning by spelling out what each section returns (line items + tax/svc, contract HTML + signatures, full payment schedule), which the enum description does not fully capture.

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 ('Get detail for one workspace file') and clarifies its scope versus the list sibling (single file, not a list). The default response shape is described, so an agent immediately knows what this returns relative to list_workspace_files.

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

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

Gives clear guidance on when to use each `section` value (pricing for line items, agreement for contract HTML, raw for unpruned). It does not explicitly name alternative tools, but the drill-down guidance is actionable and context is clear.

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

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

Annotations already mark it read-only and idempotent, and the description adds substantial behavior beyond that: it makes exactly one authenticated request, reports the credential source and acceptance, never returns the credential, and distinguishes failure categories. This goes well beyond the annotation hints and avoids any 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?

Four sentences, each carrying distinct information: what action is performed, what is reported, read-only/credential safety, and when to call it. There is no filler, repetition, or schema duplication.

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

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

With no parameters, no output schema, and no nested objects, the description carries the full burden of explaining the tool. It covers purpose, behavior, output contents, safety properties, and invocation timing. Nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

The tool has zero parameters, with schema coverage at 100%, so the baseline is 4. The description adds no parameter-level detail because none is needed, but it does explain what the tool does with its implicit credential input, which is contextually relevant.

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

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

The description names a specific verb ('resolves', 'makes', 'reports') and a concrete resource (api.honeybook.com), and clearly frames the tool as a credential/upstream healthcheck. This distinguishes it from all sibling tools, which are operational actions like list_messages or pay_invoice.

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

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

The description gives explicit guidance: 'Call this when a real tool fails and you want to know which hop broke.' This clearly tells an agent when to use it, though it does not enumerate exclusions or name alternative diagnostic tools if any exist.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds two useful facts beyond them: 'No API call' (no rate limit, no network side effects) and that flowCredentials is 'weak auth scoped to ONE questionnaire'. It does not discuss caching or freshness of the listed credentials, so not a 5.

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

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

Three dense sentences, front-loaded with the core action and then the two-way split. Every clause carries information, though the parenthetical capability lists make it slightly heavy for a no-argument discovery tool.

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

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

No output schema exists, yet the description names the two return keys (portalSessions, flowCredentials) and what each represents, so an agent knows the response shape and how to interpret it. Combined with the safety annotations, nothing needed 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?

Zero parameters, so the baseline is 4. There is nothing for the description to clarify about inputs, and it does not attempt to.

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

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

Specific verb ('List') plus precise resource ('HoneyBook credentials currently active in this MCP'), further decomposed into the two returned keys. An agent can distinguish this from get_workspace, use_magic_link, and the other siblings 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 explains what each credential kind grants access to and warns 'The two are not interchangeable', which is real guidance for choosing a credential. It falls short of explicitly stating when to call this tool versus a sibling (e.g., as a precondition check before use_magic_link), so it is context-rich but not full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the description only needs to add context. It contributes scope semantics (what the set excludes, the 'portal Files tab' mental model) but says nothing about pagination, ordering, or volume limits of the result set.

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

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

A single sentence with an em-dash gloss; the scoping exclusion is front-loaded and every clause earns its place. No boilerplate or repetition of the tool name.

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

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

For a read-only list tool with full schema coverage and annotations, the description supplies the key missing piece — what is and is not in the result. With no output schema present it could also sketch the returned shape, but the content-type framing largely compensates.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents workspace_id and origin fully. The description adds no parameter-level meaning (no format, enumeration, or default 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?

The description names the exact resource returned (loose images, files and bookmarks in a workspace) and explicitly contrasts it with list_workspace_files, which covers contracts/invoices/proposals. The listing action itself is only implied by the tool name rather than stated verb-first, but the scope is unambiguous.

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

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

It states the exclusion boundary against a named alternative — the contracts/invoices/proposals belong to list_workspace_files — which effectively routes the agent to the right sibling. It stops short of an explicit when-to-use/when-not statement or any prerequisite (e.g. session/origin requirement).

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the description correctly focuses on traits beyond that: it discloses the feed-derived source of truth, that rescheduled meetings surface their latest time, and that results are sorted by start. Pagination and volume limits are not disclosed, keeping it short of a 5.

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

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

Two sentences, densely packed with resource scope, return fields, freshness semantics and sort order, with the core purpose front-loaded. No filler or restatement of the name.

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

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

For a read-only list tool with full schema coverage and no output schema, the description supplies return fields, ordering and freshness semantics, which is most of what an agent needs. Missing pagination/result-count behavior keeps it from perfect.

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

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

Schema description coverage is 100%, so both parameters (origin, workspace_id) are already fully documented in the schema. The description adds only an implicit workspace scoping notion and no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names the concrete resource ('meetings the vendor has scheduled in a workspace'), enumerates the sub-types it covers (consultations, Zoom calls, walkthroughs), and lists the returned fields. No sibling tool covers meetings, so the boundary is unambiguous.

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

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

Usage is implied by the workspace scoping and the note that data comes from the workspace feed, but the description never states when to reach for this tool versus alternatives or what happens if workspace_id is unknown. With no competing meeting tool the gap is minor, but no explicit routing guidance is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: results are compact cards rather than full bodies, they are ordered newest first, and critically that reading does NOT mark anything seen — a non-obvious side-effect guarantee relevant to a mailbox tool.

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

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

Two tightly packed sentences with zero filler; the core scope and return shape are front-loaded and the alternative tool plus the seen-state caveat follow immediately after.

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?

Although no output schema exists, the description compensates by enumerating the returned card fields (sender, subject, preview, seen state, attachments) and the ordering. Combined with full parameter coverage and clear annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the enum for kind is fully documented in the schema, so the baseline is 3. The description restates the messages/activity split but adds no format, default, or interaction detail beyond what the schema already provides.

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

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

States a specific verb (List) and resource (messages/activity log in a workspace) and grounds it in the UI surface ('the portal's Activity tab'). It also names the sibling that returns full content (get_message), so an agent can separate it from adjacent tools without opening a schema.

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

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

Explicitly routes the agent to get_message 'for a full body' and clarifies that reading does not mark items seen, implicitly contrasting with mark_messages_seen. It does not, however, say when to prefer this over other listing siblings (list_attachments, list_payments, list_tasks) or address the activity vs messages choice in prose beyond the schema.

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 and openWorldHint, so the safety profile is covered. The description adds that notes are vendor-shared and scoped to a workspace, but says nothing about pagination, ordering, or the multi-session origin behavior that the schema hints at.

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

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

A single front-loaded clause with a scoping anchor and concrete examples; no filler, no repetition of schema/annotations.

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

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

For a filtered-list read tool with full schema coverage and annotations, the description is adequate but thin: no return-shape hint (and none available, since no output schema), no pagination or empty-result behavior, and no sibling contrast. Enough to call it, not enough to call it confidently.

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

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

Schema description coverage is 100%, so both workspace_id and origin are already documented in the schema (including the 'from list_projects' hint and the single-session condition). The description adds no parameter-level 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?

Clear verb+resource: it lists notes shared by the vendor in a workspace, and concretely anchors them (meeting notes, AI recaps, the portal's Notes tab). It does not name or contrast any sibling (e.g. list_workspace_files, list_attachments), so it stops short of the 5.

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

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

No explicit when-to-use, when-not-to-use, or alternative routing is given. The parenthetical domains imply what content is returned but never say when to prefer list_notes over list_workspace_files or list_messages.

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 and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: the empty-array outcome when nothing is saved, and that view="raw" exposes untrimmed records including billing name/address and Stripe references, which is sensitive-data disclosure the annotations do not 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?

Three tight sentences, front-loaded with purpose, then edge case, then the view flag. The raw-view clause largely duplicates the schema's own view description, which is the only minor waste.

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

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

With no output schema, the description usefully enumerates the returned fields and the empty-result case, and annotations cover the read-only profile. It leaves the origin parameter's session behavior to the schema, which is acceptable given the schema documents it fully.

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 view enum is fully documented in the schema, including the compact/raw distinction. The description restates the raw-view behavior but adds no syntax, defaults, or constraints the schema lacks, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List saved payment methods') scoped to a client account with a vendor, and enumerates the returned fields. This clearly separates it from the sibling list_payments, which deals with payments rather than stored instruments.

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

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

Usage is implied rather than stated: an agent can infer it retrieves saved cards, but there is no explicit when-to-use, no exclusion, and no pointer to list_payments or other siblings for related data. The empty-array note is the only boundary condition given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: it discloses the return shape (per-file payments with state, method, invoice number) and the aggregation behavior (paid/unpaid totals per currency), which an agent needs to interpret 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?

Front-loaded with the resource and scope, then the return contents, then the routing note. The field enumeration is long-ish but each item is genuinely informative about output, so little is wasted.

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

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

With no output schema, the description carries the burden of explaining returns and does so well, including the per-currency totals. It leaves pagination/sorting behavior unstated, a minor gap for a list tool.

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

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

Schema description coverage is 100%, so both workspace_id and origin are already documented in the schema; the description adds no syntax or format detail beyond the implied workspace scope. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Payment schedule for a workspace') and goes further by enumerating the returned fields (amount, due date, paid/pending, method, invoice number, per-currency totals). It is immediately distinguishable from the write-side sibling pay_invoice, which it names.

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 write action away from this tool ('To pay one, use pay_invoice'), giving the agent a clear read-vs-pay decision. It does not, however, distinguish this from other list-style siblings such as list_payment_methods or explain when a caller would reach for this versus the Payments tab in general.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds value beyond that by enumerating the returned fields (name, date, booked flag, workspace_id). It omits pagination/sorting behavior, which matters given the 'page' parameter, keeping it below a 5.

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

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

Two tightly packed sentences with no filler; the identity of the tool ('List your projects') is front-loaded, followed by terminology, return shape, and role. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned fields and the cross-tool purpose of workspace_id, making it largely self-sufficient for a simple, unauthenticated-safe list tool. The only gap is pagination behavior implied by the 'page' parameter.

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

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

Schema description coverage is 100%, so both parameters ('page' and 'origin') are already fully documented in the schema, making 3 the baseline. The description's mention of workspace_id pertains to the response, not to an input parameter, so it adds no parameter-level meaning.

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 your projects') and immediately clarifies the vendor's own terminology ('HoneyBook calls them events'), removing ambiguity for an agent trained on the generic term. It also names the returned fields and frames itself as the 'portal's project switcher', which separates it from the singular get_project sibling.

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

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

The description gives clear context for when to reach for it: to obtain the workspace_id that 'every other workspace tool takes', and to act as a project switcher. It does not, however, name any alternative (e.g. get_project for a single item) or state exclusions, so it falls short of a 5.

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

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

Annotations already cover the read-only and open-world safety profile, so the bar is lower. The description adds real behavioral context: it discloses what is returned (today/this week/overdue/completed counts plus task groups) and the ordering (sorted by due date), which the agent cannot infer from annotations or schema.

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

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

A single front-loaded sentence with no filler: it identifies the resource first, then scope, then return content and ordering. 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?

No output schema exists, so the description carries the burden of explaining the return shape, and it does (counts and task groups, sorted by due date). Pagination and session/origin handling are left to the schema, which is acceptable given full schema coverage.

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 schema already documents all five parameters including the curr_date bucketing and workspace_id source. The description's reference to 'today / this week / overdue' counts loosely reinforces curr_date semantics but adds no 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?

States a specific resource (tasks), scope (vendor-assigned to you in a workspace), and even maps it to a concrete UI location (the portal's Tasks tab). No sibling tool overlaps with tasks, so the agent can identify it unambiguously.

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

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

Usage is implied by the description (list tasks for a workspace) but there is no explicit when-to-use, when-not-to-use, or named alternative. No sibling competes for this resource, so the gap is mild rather than harmful.

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 and openWorldHint, so the description carries the rest and does so well: it discloses pagination behavior ("Follows every page"), the exact return shape { files, complete }, and the meaning of complete:false. It also warns that view="all" produces large payloads (hundreds of kB per proposal) and enumerates the default summary row 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 core action, then streamed as tight clauses covering filtering, pagination, return shape, and the drill-down path. Every sentence carries information; nothing is redundant with the schema or annotations.

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

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

No output schema exists, yet the description fully specifies the return envelope, the failure signal (complete:false), default vs. full row shape, and the follow-up tool. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by describing the default summary row contents and the size tradeoff of view="all". It does not restate origin's session-defaulting behavior, which stays 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+resource (list all files a vendor has shared) and enumerates the domain objects (contracts, invoices, brochures, proposals). It is immediately distinguishable from the sibling get_workspace_file, which it explicitly names as the drill-down alternative.

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: use this list tool by default, call get_workspace_file with a row's _id when pricing/contract/payment details are needed, and only pass view="all" when every pruned file object is required. Optional file_type filtering is also covered with an omit-to-return-all default.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and repeatability profile is covered. The description adds useful context that this mirrors an implicit portal side effect, but it never explains what 'seen' means to recipients or whether the change is reversible, leaving the destructive hint unelaborated.

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

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

Two sentences with no waste; the core action is front-loaded and the clarifying sibling comparison follows. Every clause earns its place.

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

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

No output schema exists and this is a destructive mutation, yet the description omits what happens to the items afterward and whether other users are affected. The portal-behavior analogy partially compensates, but gaps remain for an operation flagged destructive.

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

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

Schema description coverage is 100%, so all three parameters (origin, message_ids, workspace_id) are already fully documented with sourcing hints. The description adds no parameter-level meaning 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+resource ('Mark feed items as seen') and anchors it to a familiar behavior ('what the portal does when you open the Activity tab'). It also explicitly distinguishes itself from list_messages and get_message, so an agent can tell it apart from read siblings 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 note that list_messages and get_message 'never do this on their own' strongly signals when this tool is needed (to advance the seen state after reading). However, there is no explicit when-not guidance and no mention of batching or prerequisites such as an active session.

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 rich behavior beyond the annotations: it explicitly states no money moves, returns a portal deep link, and details the confirmation flow including the two-step preview/confirmToken fallback. This is consistent with readOnlyHint=true (no server-side mutation) and openWorldHint=true (external portal), so there is no contradiction and substantial added context.

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

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

Front-loads the core action and the critical v1 caveat in the first sentence. The remainder is dense and readable, though the em-dash clauses and parenthetical about MCP_CONFIRM_MODE make it slightly sprawling for a single paragraph.

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

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

With no output schema, the description does the work of describing the return (deep link, or preview + confirmToken) and the confirmation handshake. It is nearly complete, though it does not describe the shape/format of the returned link or the preview payload.

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

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

Schema description coverage is 100%, so the schema already documents file_id, origin, and confirmToken in detail, establishing a baseline of 3. The description reinforces the confirmToken lifecycle but adds little parameter detail the schema does not already carry.

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 ('Pay an invoice from a vendor') and immediately disambiguates the behavior an agent would otherwise assume by naming a sibling-adjacent concept (list_payments vs this action). The v1 caveat makes clear this is the payment action, distinct from the read-only listing tools.

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

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

Explains the operational context (v1 returns a deep link; user pays in browser) and the confirmation modes, referencing MCP_CONFIRM_MODE. However, it never explicitly names an alternative tool or states a when-not-to-use condition, so routing against siblings like list_payments is left to inference.

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

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

Annotations already mark it as destructive, non-idempotent and open-world, and the description goes well beyond that: it discloses the two-step confirmation fallback, the pending/task_id and unknown outcomes, and the fact that a message may still be delivered even when send status is uncertain. This is exactly the extra 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?

Dense and front-loaded — the purpose and audience come first, then confirmation mechanics, then failure modes. It is longer than average but nearly every clause carries operational information an agent needs; only the parenthetical about MCP_CONFIRM_MODE could be trimmed.

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

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

No output schema exists, and the description compensates by describing the response categories (confirmation-required preview with confirmToken, pending with task_id, unknown) and the retry guidance. Nothing essential to invoking it correctly is missing.

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

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

With 100% schema description coverage the baseline is 3, but the description adds real meaning: reply_to_message_id inherits the subject, confirmToken is phase-2-only and must never be invented or reused, and the call must repeat with identical arguments.

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

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

The description names a specific verb (Send), resource (a message), audience (the vendor and other workspace members), and channel (HoneyBook portal / Activity composer). It is trivially distinguishable from siblings like list_messages or get_message.

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 covers when this tool applies, how the confirmation requirement must be satisfied in each client mode, that a repeat call with confirmToken is required, and how to recover from uncertain delivery ('check list_messages before resending'). Explicit behavioral routing rather than implied usage.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds substantial context beyond that: it discloses that signing happens in the browser, that the tool hands over a deep link, and that a confirmation gate (elicitation or two-step confirmToken) is always enforced. This is exactly the behavioral detail an agent needs and it is consistent with the read-only annotation.

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

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

It is front-loaded with the purpose and the important correction that it does not sign, but the middle sentences are dense with nested parentheticals about confirmation modes. Slightly longer than necessary, though every clause carries real information.

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

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

With no output schema, the description does the work of explaining what comes back (a deep link) and the two-phase confirmation contract. For a deceptively named tool with no output schema, this is complete enough to call correctly.

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

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

Schema description coverage is 100%, so origin, file_id and confirmToken are already fully documented in the schema. The description restates the confirmToken fallback and references MCP_CONFIRM_MODE, which adds a little framing but is largely redundant with 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?

The description opens with a specific verb+resource ('Sign a contract you received from a vendor') and then immediately corrects a natural misreading by stating it returns a deep link and signs nothing itself. This makes the tool's true function unambiguous and distinguishes it from the other session/link tools.

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

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

It implies the use case (a contract from a vendor) and explains the confirmation flow, but never names an alternative or states when to pick this over siblings like use_magic_link or use_flow_link. The when-to-use context is implied rather than explicit.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds substantial context beyond them: it writes to ~/.honeybook-mcp/flows.json, the credential is HoneyBook 'weak auth' limited to one questionnaire, it cannot read portal workspaces/files/invoices/payment methods, and scope must be re-approved once per new questionnaire.

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 purpose, then routing to the sibling, then prerequisites, then behavioral scope — a logical order with little waste. Slightly long and dense, but nearly every sentence (routing, prerequisites, scoping) carries load-bearing 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?

No output schema exists, yet the description covers prerequisites, the exact side effect and destination file, credential scope limits, and the re-approval behavior. An agent has everything needed to invoke it correctly and predict the outcome.

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

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

Schema description coverage is 100% and the single parameter already documents the URL shape, the /flow/<flowId> segment requirement, and the ?hash= fallback. The description largely restates the same URL constraints, so it adds little parameter-specific meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (capture) plus resource (HoneyBook QUESTIONNAIRE flow credential) and immediately names the sibling it is not: for client-portal /app/link/resolve/… links use `use_magic_link` instead. An agent can distinguish it from use_magic_link 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?

Explicit when-to-use based on URL shape (https://<vendor>.hbportal.co/flow/<flowId>?hash=…), an explicit when-not with the named alternative (use_magic_link for portal links), and concrete prerequisites (install extension, open link, let page render before running).

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 annotations: explains exactly what is extracted and where it is written, clarifies that nothing is sniffed from a live request so an idle page is fine, and notes that other tools default to the most-recently-activated session. The description does not explicitly discuss permissions or failure modes if the extension is missing, which keeps it from a 5.

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

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

Front-loaded with the core action and prerequisite chain, then edge cases. It is fairly long but dense with non-redundant operational detail, so it earns most of its length.

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 session-capture tool with no output schema, it covers installation, the exact storage field, the write target, session-selection behavior for sibling tools, and the hard rejection of flow links. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds critical semantics: magic_link_url is used only to derive portalOrigin as a cache key and is not opened or navigated to. That resolves a likely misconception for the agent.

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

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

States a precise verb and resource: capture a client-portal session and snapshot auth fields from localStorage into a sessions file. It explicitly distinguishes itself from use_flow_link, naming that sibling and the condition under which this tool refuses the input.

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?

Prerequisites are laid out step by step (install extension, open magic-link URL, leave tab signed in and open). It also gives an explicit exclusion: questionnaire links must use use_flow_link instead, and this tool will reject them.

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