Approveit

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds a concrete consequence of that idempotency: re-activating is a silent no-op rather than an error. It says nothing about who may activate, whether activation can be reverted (no deactivation sibling exists), or what is returned, leaving the operation's risk profile partly undisclosed.

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

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

Two short sentences with zero waste: the effect is front-loaded and the edge-case behavior follows. Nothing is repeated from the title or annotations verbatim.

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, idempotent state-change tool this covers purpose and no-op behavior adequately. Gaps remain around permission requirements, reversibility, and what a successful call returns, which matter because there is no output schema to fall back on.

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 workflow_id parameter is documented well, including how to obtain the id from list_workflows or a creation tool. The description adds no parameter-level meaning beyond that, 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 a specific verb and resource ('Publish a workflow') and states the concrete effect ('team members can submit requests against it'), which distinguishes it from describe_workflow or list_workflows. It stops short of naming a sibling tool explicitly, so an agent must infer the boundary rather than being routed.

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

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

Usage is implied by the stated effect: use it when a workflow must accept team requests. The no-op note implicitly tells the agent it need not pre-check activation state. However, no alternative or prerequisite (e.g., ownership/permission requirements) is named.

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

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

Beyond the read-only annotations, the description discloses important behavior: aggregation happens in the database, line-item columns are analyzed with same-line cell pairing, currency values are stored in minor units, and returned note and warnings fields must be read and repeated. These are exactly the behavioral details an agent needs before trusting or quoting 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 description is front-loaded with the core purpose and then gives concrete usage examples, warnings, and field-label guidance. It is dense and slightly repetitive with the schema on group_by_label and dimension, but nearly every sentence adds operational value for a complex 8-parameter 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?

For a complex aggregation tool with no output schema, the description covers the essential context: aggregation method, supported operations, grouping modes, line-item handling, field labeling, currency units, and warning behavior. An agent can call this tool correctly without needing additional return-value documentation.

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 useful semantic examples beyond the schema, such as field_label='Amount', operation='sum', group_by_label='Vendor' meaning spend per vendor, and dimension 'month' meaning volume over time. It also clarifies when to use field_label versus dimension in prose, though much of this is already present 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?

The description states a specific verb and resource: it aggregates workflow fields across visible requests as a database aggregate rather than by listing and summing requests. It clearly distinguishes itself from listing requests and from free-text search, and it names get_workflow_details as the fallback for uncertain field labels.

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

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

It gives explicit operating rules: numeric fields support sum/average/max/min, any field supports rank, group_by_label cross-tabulates two fields, and dimension groups by built-in properties such as status or month. It also routes the agent to get_workflow_details when field wording is unclear, which is a concrete alternative behavior.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds what they cannot: that the call has financial/operational consequences, that the first call with confirmed=false records NOTHING, that it fails for non-current approvers, and that the two-step pattern is required. That is meaningful behavior beyond the structured 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?

Three tight sentences ordered by importance: what it does, the safety obligation, then the failure mode and call sequence. Every clause carries operational weight; nothing is padding.

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, non-idempotent mutation with no output schema, the definition covers purpose, preconditions, confirmation protocol, and the preview/commit mechanics. It stops short of saying what the preview payload contains or what state the request enters after approval, which would close the last gap.

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

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

Schema coverage is 100%, and the schema's own property descriptions already explain confirmed=false as a no-op preview and the ar_identifier formats. The description restates the two-step semantics without adding syntax or edge-case detail the schema lacks, 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?

Specific verb ('record this user's approval') plus resource ('a request that is waiting on their decision') with a scope constraint that tells the agent when the action is even valid. It never names reject_request or describe_approval_request, so the sibling differentiation is left to the agent's inference rather than stated.

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

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

Explicit preconditions ('fails if the user is not the current approver'), an explicit confirmation protocol ('show the user what they are approving and get explicit confirmation in the same turn'), and an explicit two-call sequence with the default state spelled out for each call.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantive detail beyond them: the approval process is stopped, approvers are notified, and the default call cancels NOTHING. The explicit "NOTHING cancelled yet" wording is exactly the safety context an agent needs before a destructive call.

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

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

Three short sentences, front-loaded with the purpose before the safety procedure. The two-step explanation is repeated almost verbatim in the confirmed parameter's schema description, which is a minor redundancy but not harmful.

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 destructive tool with full schema coverage and no output schema, the description covers purpose, side effects, recipient notification, and the mandatory confirmation sequence. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100% and the confirmed parameter is already fully documented in the schema, including the preview-then-confirm sequence. The description reinforces the two-step flow but adds no syntax or format detail beyond what the structured fields already provide, 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 (cancel an approval request the user submitted) and immediately scopes it to the submitter's own request, which separates it from approve_request and reject_request in the sibling list.

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

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

Gives explicit procedural guidance: confirm with the user first, then preview with confirmed=false before cancelling with confirmed=true. The one gap is that it never contrasts this with reject_request, which an agent could reasonably confuse with cancellation.

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 supply the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds the crucial non-obvious state fact that the workflow is created inactive and needs activate_workflow to publish. It does not warn that repeat calls create duplicate workflows despite idempotentHint=false, which is the one meaningful gap.

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

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

Three short sentences, front-loaded with the core action, then the state consequence, then the preference. Every sentence carries distinct decision-relevant information with no repetition.

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

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

Given the self-documenting schema and annotations, the description covers what an agent needs: creating a clone, the inactive state, and the activation follow-up. Only the duplicate-creation risk on retry is left unaddressed.

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 per-parameter text is unusually rich (template_name precedence, approver_ids resolution via search_team_users, step conditions and fallback semantics), so the schema carries the load. The description itself adds no parameter-level meaning beyond what the schema already states, making baseline 3 correct.

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 new workflow") plus the mechanism ("by copying a prebuilt template"), which cleanly separates it from list_workflow_templates and describe_workflow_template in the sibling set. The final sentence contrasts it with an alternate construction path an agent might otherwise attempt.

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

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

Gives a clear preference rule ("Prefer this over building a workflow field by field") and names the required follow-up, activate_workflow, since the result is inactive. It stops short of explicit when-not conditions, but the alternative and the sequencing 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the response contents and the deep link, but it says nothing about what happens when the identifier is not found, and it leaves idempotentHint=false unexplained for an operation that reads a single record.

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, zero filler. The return payload is front-loaded and the input form follows, so an agent gets the important information first.

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

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

With no output schema, the description correctly carries the burden of enumerating return fields, and it does so thoroughly for a one-parameter read tool. The only shortfall is the absence of any statement about not-found or cross-workspace behavior, which is minor 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% and the single parameter already documents both accepted forms with the 'AR-15' / '15' example. The description's sentence 'Accepts the friendly number or the internal id' restates the schema rather than adding new meaning such as case sensitivity or prefix handling, 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 ('Return one approval request') and enumerates exactly what comes back: status, submitted field values, requestor, approver decisions, and a link. The word 'one' plus the enumerated payload makes it distinguishable from list_approval_requests and get_request_activity 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?

Usage is only implied by the singular 'one approval request', which suggests fetching a single known record rather than browsing. There is no explicit statement of when to prefer this over list_approval_requests or get_request_activity, and no mention of prerequisites or failure behavior for an unknown identifier.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes useful behavioral detail by enumerating what the response contains (steps, approvers, routing conditions), but it says nothing about behavior when the workflow_id does not exist, or whether inactive or draft steps are included, which matters because idempotentHint is 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?

One sentence, front-loaded with the verb and the resource, and every clause (steps, approvers, routing conditions) tells the agent something concrete about the payload. No filler and no redundancy.

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

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

For a simple one-parameter read tool with annotations and no output schema, the description covers what an agent needs: that it retrieves a structure rather than mutating anything, and roughly what that structure contains. The only real gap is error/not-found behavior and differentiation from get_workflow_details.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already explains 'ID of the workflow to describe'. The description adds no format, sourcing, or lookup hints beyond that, which is the expected baseline 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?

The description uses a specific verb ('Return') and names the exact resource returned: a workflow's approval structure, including steps, approvers, and routing conditions. It is clear what the tool does, though it does not contrast itself with the nearby sibling get_workflow_details, which an agent could easily confuse it with.

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 phrase 'a workflow's approval structure', which suggests inspection rather than mutation, and the read-only nature is consistent with that. However, there is no explicit when-to-use guidance, no statement of prerequisites, and no routing to the alternatives get_workflow_details or describe_workflow_template.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the response contains fields plus approval steps, which is useful context, but it says nothing about failure behavior for an unknown template, the id/name precedence resolution, or the shape of the returned steps.

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

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

A single sentence with the outcome front-loaded and the motivating context trailing it. Nothing is redundant and nothing is buried.

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

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

This is a low-complexity, read-only lookup with no output schema, and the description tells the agent what the return contains (fields and approval steps) at the right level of abstraction. The only real gap is the absence of any statement about what happens when the template cannot be resolved.

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 both parameters carry detailed guidance including the precedence rule that name wins over id. The description adds no parameter meaning of its own, so the schema-driven 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?

The description gives a specific verb and resource ("Return one template's fields and approval steps") and even names the payload contents. It implicitly separates itself from create_workflow_from_template by framing the call as pre-creation inspection, but it never names list_workflow_templates or the create sibling outright, so sibling differentiation is only partial.

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 clause "before creating a workflow from it" gives a clear situational trigger for the tool. There are no explicit when-not conditions or named alternatives, and the important "always call list first" rule lives in the parameter schema rather than the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses the ordering guarantee ('chronological'), the taxonomy of returned events, and the presence of actor attribution ('who did what and when') — meaningful since no output schema exists. It omits pagination, result caps, and behavior for a request with no activity.

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

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

One sentence, front-loaded with the verb and resource, with the event enumeration as a compact clause rather than a bulleted list. No filler, hedging, or restatement of the title.

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

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

For a single-parameter read tool with full schema coverage and annotations, the description supplies what the schema cannot: what the response contains and in what order. Only the absence of any note on volume, pagination, or an empty-history result keeps it from being fully complete.

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

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

Schema description coverage is 100% and the single parameter already documents both accepted forms ('AR-15' vs internal integer id) plus the ambiguity caveat. The description adds no additional meaning about ar_identifier, 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?

Specific verb ('Return') plus a precise resource ('chronological audit trail for one approval request') and an enumeration of the event types covered (submissions, approvals, rejections, comments, edits, forwards). It clearly reads as a history/audit tool, implicitly distinct from describe_approval_request, but it never names a sibling or states the contrast explicitly.

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

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

The phrase 'audit trail for one approval request' implies the use case (investigating what happened on a single request) and the 'one' constraint, but there is no explicit when-to-use vs when-not, and no pointer to describe_approval_request for current state or summarize_approvals for aggregate views.

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 safety profile (readOnly, non-destructive, closed-world), so the description's added value is the key behavioral fact that this resolves the connection's own authenticated actor rather than an arbitrary user, and that it is a cheap prerequisite call. It stops short of saying what happens when the connection is unauthenticated or what an empty/error result looks like.

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

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

Two sentences, zero filler, and the payoff (what you get back) is front-loaded ahead of the usage instruction. 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?

For a parameterless read of one object, the description is sufficient: it names the returned fields, which substitutes for the absent output schema, and the annotations carry the safety and idempotency profile. 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?

The tool takes zero parameters, which is the baseline-4 case. The description adds the useful implicit signal that no identifiers need to be supplied because the actor is derived from the connection 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 (return) and a precisely bounded resource: the Approveit identity 'this connection acts as', enumerating the fields returned (name, email, role, department, team). The phrase 'this connection acts as' separates it from search_team_users, which looks up other people, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit trigger — 'when you need to know who "I" or "me" refers to in a request' — plus ordering guidance ('call this first'). It does not name the sibling to use for looking up another user's identity, so the when-not side is only implied.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds useful behavioral context by describing the returned payload, but says nothing about failure modes such as an unknown or inactive workflow_id. Against an already-annotated read tool, this is adequate rather than rich.

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

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

Two sentences, both earning their place: the first defines the output, the second defines the calling context. The payload description is front-loaded ahead of the sequencing advice, with no filler.

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

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

With no output schema, the description carries the burden of explaining return values and does so reasonably (field list, types, required flags, option sets). For a single-param read tool this is nearly complete; only error behavior for invalid IDs is unaddressed.

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

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

There is a single required parameter at 100% schema description coverage, so the schema fully documents workflow_id. The description adds no additional meaning such as accepted ID ranges or where to obtain a valid ID. Baseline 3 is appropriate when the schema does the work.

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

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

The description gives a specific verb and resource ('Return one workflow's full field list') and enumerates the payload contents (types, required flags, option sets), so an agent knows exactly what comes back. It does not distinguish itself from near-siblings like describe_workflow or describe_workflow_template, which is the main gap.

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 a concrete usage rule with a named sibling: call this before submit_request to learn mandatory values and formatting. That is clear when-to-use guidance rather than implied. It stops short of explicit when-not-to-use guidance or a comparison with describe_workflow/describe_workflow_template.

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-readonly, open-world, non-idempotent, non-destructive. The description adds genuinely new and important context: real mail goes to a real person, and the first call sends nothing. That is the key safety behavior an agent needs and it isn't in 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?

Three tight sentences, front-loaded with purpose, then consequence, then procedure. No filler or restated title text.

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

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

Given a single-required-param invitation tool with no output schema, it covers purpose, consequence, confirmation requirements, and the full call sequence. Nothing an agent needs to avoid a harmful call is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond by framing 'confirmed' as a cross-call sequencing contract ('call with confirmed=false first... call again with confirmed=true'), tying individual parameters to the required invocation order rather than just their individual 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 ('Send an Approveit invitation to an email address') and the effect on the real world. An agent can instantly distinguish it from read-oriented siblings like search_team_users or get_user_context.

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 confirm the address and role with the user first, and gives a precise two-step procedure: confirmed=false for a preview, then confirmed=true to send. The alternative path (re-preview on ambiguity) is stated, leaving no inference needed.

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 a read-only, non-destructive, closed-world read, so the safety profile is covered. The description still adds genuine behavior beyond them: one page per call with count as the total, retry-by-offset when truncated, and the field_values_unavailable counter that must be disclosed so a partial read is never presented as complete. It is slightly weaker on visibility/permission scoping, which is pushed into individual parameter docs rather than stated once up front.

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 two motivating questions, then filter-by-filter, then pagination caveats. Every sentence is actionable, but the description is long and restates several schema parameter docs (offset/limit paging, status semantics), which is redundant given 100% coverage.

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 12 parameters, no required fields, and no output schema, the description fills exactly the gaps that matter: it explains the response envelope (count, single page, truncated, field_values_unavailable) and how to page, so an agent can both call and interpret results correctly.

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

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

Schema coverage is already 100%, so the baseline is 3. The description earns above that by explaining cross-parameter semantics the schema cannot: that field_filters reaches line-item table columns and thus values search cannot, that scope=awaiting_my_approval already implies statuses, and how include_field_values complements rather than replaces filtering. Much of the per-parameter text is duplicated from the schema, which keeps it from a 5.

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

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

States a specific verb and resource ('List approval requests visible to this user, newest first') and immediately frames the two questions it answers, which distinguishes it from describe_approval_request, analyze_field, and summarize_approvals. An agent can route to it without opening the schema.

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

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

Explicit routing is given repeatedly: use field_filters rather than search when the user names a field and value, use workflow_query when they name the workflow, use get_workflow_details if the field name is unknown, and use scope=awaiting_my_approval rather than approver_id for the current user. Exclusions are stated (don't combine awaiting_my_approval with status; never present another user's queue as this one's).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the domain meaning of a workflow, and the fallback rule that an empty search should be followed by listing all rather than reporting that nothing exists — a non-obvious behavior an agent would otherwise get wrong.

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

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

Three short sentences, front-loaded with the action and scope, followed by the minimum domain definition needed and the entry condition. No filler, no repetition of the schema, and each sentence carries distinct 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 one-optional-param read tool with full schema coverage and no output schema, the description covers purpose, domain meaning and starting condition well. The remaining gap is what each list entry contains (id, name) that the agent would need to chain into describe_workflow or submit_request; without an output schema that would have been worth one clause.

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 entry for search_query already explains name-or-purpose matching and the empty-result fallback. The description itself adds no parameter meaning beyond that, so the baseline of 3 applies; it neither compensates for nor introduces anything the schema lacks.

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

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

States a specific verb and resource with scope ("List the approval workflows this user can submit requests against") and even defines what a workflow is, so the agent knows the returned items carry fields and approvers. It does not explicitly distinguish itself from describe_workflow or list_workflow_templates, which are the nearest siblings, so differentiation is inferred rather than stated.

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

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

"Start here when the user wants to submit something but has not named a specific workflow" gives a concrete entry condition and implicitly excludes the case where the user already named a workflow. It stops short of naming the alternative tool to call in that case (describe_workflow) or stating exclusions such as templates, but the usage context is clear without inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds useful context that these are copyable prebuilt templates, but says nothing about how results are filtered or whether the full catalog is returned when query is omitted.

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, zero filler, with the resource scope front-loaded and the follow-up action second. The parenthetical examples earn their space by anchoring what 'template' means.

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

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

For a one-parameter read tool with full schema coverage and no output schema, the definition is nearly sufficient. The one meaningful gap is that it never states what the listing returns (names, ids, descriptions) — an agent needs to know it gets an identifier it can hand to create_workflow_from_template.

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 description says nothing about the query parameter or that the catalog is fuzzy-searchable; that work is done entirely by the schema, which is at 100% coverage and gives examples and omission guidance. With the schema fully documented, the baseline of 3 applies — nothing is added, but nothing is contradicted.

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 the prebuilt workflow templates') and enumerates concrete examples (purchase order, invoice, time off, vendor onboarding, access request), which makes the catalog scope tangible. It does not distinguish itself from describe_workflow_template or list_workflows, so sibling differentiation is only partial.

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

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

'Use before create_workflow_from_template' gives an explicit sequencing rule that tells the agent when this tool belongs in a flow. It offers no when-not guidance and never mentions describe_workflow_template as the alternative for inspecting a single template's details.

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 the preview-does-nothing semantics, the two-step confirmation flow, and the approver-identity precondition that causes failure. The 'decision of record' framing correctly reinforces destructiveHint=true rather than contradicting it.

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

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

Four short sentences, front-loaded with the action and the confirmation requirement, then the failure condition, then the two-step mechanics. No filler and every clause 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?

For a destructive, non-idempotent mutation with no output schema, the description covers the safety posture, the preview-vs-record distinction, and the precondition. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so parameter docs are already complete and a baseline of 3 applies. The description adds real value by explaining the confirmed default and the required ordering of the two calls as a workflow, not just a boolean flag.

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 ('Record ... rejection of a request') plus the scope condition 'waiting on their decision'. It is immediately distinguishable from approve_request and cancel_request 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 sequences the two calls: confirmed=false first for a preview, then confirmed=true to record, and warns 'confirm with the user first'. It also names the exclusion condition ('Fails if the user is not the current approver'), leaving nothing to inference about when this tool applies.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the resolution purpose and the submit_request linkage, but says nothing about matching behavior (partial/fuzzy matching), whether multiple candidates can be returned, or what happens on no match — meaningful gaps for a lookup tool that agents will often chain into submit_request.

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, front-loaded with the core action and followed by the concrete use case. The long em-dash enumeration of entity types is slightly listy but is doing real work by scoping what can be searched.

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

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

There is no output schema, so the description carries the burden of describing the return value; it implies an id but does not say whether a list of candidates or a single match comes back, nor how ambiguity is surfaced. It is adequate for a 3-parameter lookup, but the return shape is left for the agent to discover.

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

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

Schema coverage is 100%, so each parameter is already documented, including the empty-query count behavior and the workflow_id scoping rationale. The description adds little parameter-level meaning beyond reinforcing that query holds a user's spoken name and that entity_type spans the eight listed types. Baseline 3 is appropriate 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+resource: 'Resolve a name to an id' for reference data, then enumerates the entity kinds (vendors, customers, departments, locations, cost centers, categories, taxes, products). This clearly separates it from siblings like search_team_users or list_workflows, and the 'id that submit_request expects' phrasing pins down its role in the flow.

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?

'Call this to turn a user's words (\'Acme\', \'Marketing\') into the id that submit_request expects' gives an explicit trigger and names the downstream tool it feeds. It stops short of stating when NOT to use it (e.g., team members go to search_team_users) or what to do when multiple matches come back, so it is clear context without full exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds the workflow context but says nothing about matching behavior (exact vs partial), result ranking, or result limits, which matter for a lookup that returns ids.

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: what it searches first, why you would call it second. No filler, no restatement of the title, and the purpose is front-loaded.

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

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

For a one-parameter read-only lookup with a fully documented schema and no output schema, the definition covers purpose and call motivation adequately. The remaining gap is what a result contains and how matches are ranked, which would help an agent consuming the returned ids.

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 the single query parameter thoroughly (name, job title, department). The description says "by name or email," which does not add meaning and actually diverges from the schema's stated searchable fields, so it earns no credit above baseline.

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

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

"Find people in the team by name or email" gives a specific verb plus a scoped resource, and the second sentence explains the workflow role it plays. It is clearly distinct from write-oriented siblings like invite_team_member or update_request, though it never distinguishes itself from search_entities.

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

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

The description states a concrete use case: resolving an approver or manager to an id when a workflow field asks for a person. That is real when-to-use guidance, but there is no when-not guidance and no mention of when to prefer the sibling search_entities.

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, it discloses that this notifies real approvers, that preview writes NOTHING, that validation reports all blockers at once instead of guessing, and that missing required fields cause downstream errors that are unrecoverable from inside the tool. That is exactly the behavioral context the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) 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?

Three dense sentences, front-loaded with purpose, then prerequisites, then the two-step protocol. Nothing is repeated from the schema and every clause (notify real approvers, nothing written on preview) carries operational weight.

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

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

There is no output schema, but the description compensates by explaining what the preview returns (every blocker at once) and what the confirmed call does. For a five-parameter mutation tool with nested objects and open-world effects, an agent has everything it needs to call this correctly and safely.

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

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

Schema coverage is 100% and the property descriptions already carry the heavy detail (UUID keys, dollar amounts, tax ids, step_approvers shape), so the baseline is 3. The description still adds meaning at the parameter level: it explains the confirmed flag's preview contract and reinforces that all required fields, including workflow-specific ones, must be populated, which is a small but real increment over the schema.

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

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

The description opens with a specific verb plus resource ('Submit a new approval request against a workflow'), and the word 'new' plus the submission framing distinguishes it from update_request, approve_request, and reject_request in the sibling list. An agent can route to it without opening the schema.

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

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

It states explicit prerequisites ('Call get_workflow_details first and supply every required field'), an explicit sequencing rule (preview with confirmed=false, then confirmed=true), and a human-in-the-loop condition ('confirm the values with the user before calling'). The when-not case is implicit but clear: do not call with confirmed=true until the preview is clean and the user has agreed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is free to focus on semantics, which it does: results are broken down by currency and by downstream outcome rather than a single scalar. It also discloses the identity constraint that the current user's id cannot be looked up, which is real behavioral context not in the annotations. It stops short of describing grouping limits or ordering.

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

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

Four tight sentences, each with a distinct job: what it computes, when to prefer it, the current-user rule, and the date format. The aggregation scope is front-loaded and nothing is repeated without purpose.

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 three-parameter read-only aggregate with no output schema, the description covers purpose, alternative, identity resolution, and date format, which is nearly everything needed to invoke it correctly. Minor gaps remain on result shape granularity (e.g., whether groups are bounded or ordered) and on the unusual idempotentHint=false for a read operation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the default-to-current-user behavior for approver_id. The description reinforces the omit-approver_id rule and the YYYY-MM-DD format but adds little syntax or meaning beyond what the schema states, 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: total up the value of approval requests a person APPROVED in a date range, with the aggregation dimensions named (by currency, by what later happened). This clearly separates it from listing siblings such as list_approval_requests.

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

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

Gives concrete trigger questions ('how much did I approve this month', 'what did the CFO sign off on in Q1') and explicitly excludes the alternative path of listing every request and summing manually. It also routes the agent to search_team_users for any approver other than the current user.

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 destructiveHint=true annotation: it discloses that saving discards all existing approvals, clears approvers, and lists the status transitions per request state (pending/change-requested revert, deferred/scheduled/draft keep status). It also details who gets re-notified and warns the agent to inform the user before calling rather than after.

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 critical side effects are front-loaded ahead of the mechanics, and each sentence conveys distinct information about statuses or notifications. It is on the long side and partly repeats the confirmed-flag wording already in the schema, but no sentence 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?

For a destructive, non-idempotent mutation with a nested field map and no output schema, the description covers consequences, status transitions, notification behavior, and a preview-then-commit flow. Nothing essential to invoking it safely is missing.

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

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

Schema coverage is 100%, so the field map, confirmed, and ar_identifier are already documented in the schema. The description restates the two-step confirmed protocol and the 'only changed fields' semantics that the schema already carries, adding little new meaning beyond it, 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 ('Change field values on an approval request') plus a scope constraint ('the user submitted and that is still open'). This clearly separates it from approve_request, reject_request, and cancel_request, which act on requests rather than editing their values.

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

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

Gives an explicit precondition ('still open') and an exclusion ('editing a request that has already been approved is rejected'), and spells out the call sequence: preview with confirmed=false, then save with confirmed=true. It does not name sibling tools or say where to obtain field ids beyond a passing mention, so it falls short of a full when/when-not/alternatives statement.

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