Wayfront

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

The description's 'List' wording aligns with the readOnlyHint and destructiveHint annotations, and it does not contradict them. It adds functional context about the catalog, though it does not discuss permissions or rate limits; annotations already cover the primary side-effect profile.

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 a single, focused sentence that communicates the tool's purpose and key requirement without redundancy or unnecessary detail.

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

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

Given the lack of an output schema, mentioning the automation rules and the supported catalog gives a reasonable sense of what will be returned. It could be more explicit about output shape or filtering, but it is sufficient for a simple read/list 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?

The schema already provides clear descriptions for both parameters, including the enum action and the meaning of pipeline_id. The description reinforces that pipeline_id is required but adds little beyond the schema's existing parameter documentation.

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?

Clearly states the tool lists a pipeline's automation rules and the supported catalog of triggers, conditions, actions, and references. The read-only intent is unambiguous and easily distinguished from the sibling automation-write tool.

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 notes that pipeline_id is required for every action, which gives necessary invocation guidance. It does not explicitly mention when not to use it or contrast with automation-write, but the read-only wording and sibling name make the appropriate use 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?

The description discloses important side effects (downstream writes, webhooks, Slack messages) and a restriction (status-sync-managed rules cannot be edited), going beyond the annotations' destructiveHint. This gives the agent a clear picture of consequences.

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 concise and well-structured, using a few short sentences. It states the core function, key requirements, and important caveats without unnecessary elaboration.

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 write tool with no output schema, the description covers the essential context: it lists supported actions, mentions the need to read the catalog, and highlights side effects and edit restrictions. It does not describe return values, but that is a minor gap for this tool type.

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 description does not add much beyond it. It reiterates that pipeline_id is required and references the 'list' catalog, but these details already exist in the parameter descriptions. The baseline for high coverage is 3, and no significant extra meaning is added.

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 explicitly states the tool's function with a specific verb ('Create, update, toggle or delete') and a clear resource ('pipeline automation rules'). This distinguishes it from the sibling automation-read tool.

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 advises reading automation-read first for supported triggers/conditions/actions, giving a clear usage order. While it doesn't explicitly say 'use this when you need to modify automations', the intent is obvious and the guidance is helpful.

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, covering the safety profile. The description adds the specific output scope (definitions, IDs, types, options), which provides useful behavioral 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?

A single, front-loaded sentence that is entirely relevant and contains no filler. Every word earns its place.

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

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

For a simple read-only list tool with one parameter and no output schema, the description fully conveys what the tool does and what it returns. No critical information is missing for an agent 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?

The single parameter 'action' has 100% schema coverage with an enum description ('Action to perform.'). The description does not add any additional meaning beyond the schema, so the baseline score 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 states a clear verb ('List') and a specific resource ('client custom-field definitions'), and enumerates the exact data returned (IDs, types, options). This distinguishes it from the sibling 'client-custom-field-write' and other read tools.

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

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

The name and description make the use case obvious—reading custom-field definitions. While no explicit exclusions or alternative tools are named, the distinction from the write counterpart is implicit and sufficient for an agent to select it.

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

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

Openly describes modifying/clearing data and notes that file-type fields cannot be set via MCP, which is consistent with destructiveHint=true. It does not mention irreversibility, but the destructive nature is conveyed.

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

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

Three concise sentences with no filler; each sentence adds necessary operational context.

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

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

Covers required inputs, clear/update semantics, read-tool discovery, and a key limitation. No return-value details are provided, but no output schema exists and this is a write 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?

All parameters have descriptive schema text, and value encoding for checkboxes, dropdowns, and null-clearing is explained in detail. There is a slight inconsistency between the required array and the prose requirements, but the field-level descriptions compensate.

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?

Description states a specific action ('Set or clear') on a specific resource ('client custom-field value') and points to the read tool for discovering definitions, so its purpose 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?

Provides usage details: required identifiers, null-clearing behavior, and the file-type-field limitation. It does not explicitly discuss alternative write tools for unsupported fields, but the guidance is clear enough.

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. The description adds the 'visible' qualifier, which implies some accounts may be hidden, but does not explain the mechanism or consequences. It does not contradict 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?

A single sentence that is front-loaded with the core action and resource, and includes the key capabilities (filtering, sorting, pagination). No waste, every word 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 read-only tool with a fully described schema (6 params, nested filters, enums), the description is adequate. It does not explain return formats, but no output schema exists and the action semantics (list vs show) are implicit in parameter names and schema descriptions. The 'visible' nuance is a small 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% with detailed descriptions for all parameters, including enums, defaults, and filter field examples. The description's mention of filtering, sorting, and pagination adds no meaning beyond what the schema already provides, so it stays at 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?

The description states the verb (list/show) and resource (client accounts) clearly, and mentions filtering, sorting, and pagination. It is specific enough to differentiate from client-write (which mutates) and client-custom-field-read (different resource), though it does not explicitly name 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?

No guidance on when to use this tool vs alternatives. The description does not mention client-write, client-custom-field-read, or other read tools, nor any conditions that would favor one over the other. The 'visible client accounts' phrase hints at a scope but is not actionable.

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

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

The description discloses important behavioral traits: welcome_email defaults to true and can send an external email, update is partial with omitted fields untouched, null clears fields, and email cannot be cleared. It also notes address merge behavior. Annotations already indicate destructiveHint=true, so the description adds meaningful context beyond that. It doesn't mention side effects like email sending beyond welcome_email, but the key behaviors are covered.

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

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

The description is compact and front-loaded with the core purpose. It packs significant behavioral detail into a few sentences without redundancy. It could be slightly more structured, but it earns its place with high information density.

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 tool's complexity (17 params, nested address object, two actions with different requirements), the description covers the critical semantics: create vs update, null clearing, email constraints, and address merging. It doesn't explain return values, but there is no output schema and the description focuses on invocation semantics. It is complete enough for an agent to call the tool correctly in most cases.

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 parameters. The description adds value by explaining the create/update distinction and the null-clearing semantics, which are not fully obvious from the schema alone. It also clarifies the address merge behavior and email constraints. This goes beyond the baseline 3 for full schema coverage.

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

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

The description clearly states the tool creates or updates a client account, and distinguishes the two actions with their key semantics. It names the resource (client account) and the specific operations, making it easy to differentiate from sibling read tools like client-read.

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

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

The description explains when to use 'create' vs 'update' and highlights important constraints like email being required for create and not clearable on update. It doesn't explicitly name alternative tools, but the action enum and per-field notes provide clear usage context. It could be improved by explicitly stating when to prefer client-write over other write tools.

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

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

The description discloses meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations: collaboration flags, invoice visibility rules, owner_is_member behavior, and what show returns. This gives an agent a realistic model of the tool's domain effects without contradicting the annotations.

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

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

The description is information-dense but well-structured, front-loading the purpose before explaining domain rules and action-specific details. It is longer than average, but the added context about collaboration and invoice visibility earns its place for a domain with nested semantics.

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

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

There is no output schema, so the description must carry return-value information. It explicitly states what show returns and implies list returns standard company records. Given the tool's moderate complexity and 7 parameters, the description is largely complete, though list output details are not fully spelled out.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that client_id finds companies where the client is a member or owner, that company_id is required for show, and by clarifying which parameters apply to which action. This is helpful semantic context beyond the raw field descriptions.

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

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

The description opens with a specific verb and resource: "List or show client companies (client teams)." It distinguishes the two actions, list and show, and explains the core concept of a company grouping client accounts. This clearly separates it from the sibling company-write tool.

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

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

The description provides concrete guidance on when to use each action: list for filtered queries including finding companies by client_id, show for retrieving owner and member details. It does not explicitly name company-write as the mutation alternative, but the readOnly annotation and sibling naming make the boundary 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 only declare readOnlyHint=false and destructiveHint=true. The description adds substantial behavioral detail: the non-unique name caveat, default flag values for add_member, the system-wide side effects of ownership changes (invoice visibility, portal management, subscription sharing), and the permanent, irreversible nature of delete including what data is destroyed. This goes well beyond the annotations.

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

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

The description is a single dense paragraph that front-loads the purpose but then packs many behavioral rules into run-on sentences. Every claim is relevant and the length is justified for a six-action tool, but it would be more scannable with bullet points or clearer segmentation.

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 write tool with six actions and 10 parameters, the description covers the essential preconditions (company-read first, client-write first), action-specific requirements (new_owner_client_id), default values, side effects, and the irreversible delete outcome. No output schema exists, but the tool is a write operation and return-value details are not essential for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds cross-parameter meaning beyond the schema by explaining how owner_client_id and new_owner_client_id affect invoice visibility and subscription sharing, and that update_member changes only the flags supplied. This elevates the agent's understanding of the parameters' interactions.

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 set and resource: 'Create, update or delete client companies (client teams) and their membership.' It mentions the sibling company-read tool and instructs calling it first, clearly distinguishing write behavior from read behavior.

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

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

It explicitly tells the agent to call company-read 'list' with client_id first to check for existing teams, and to create a client with client-write before add_member. It also explains when new_owner_client_id is required for remove_member and how update_member differs from add_member, giving clear when/when-not guidance.

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

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

The annotations already establish read-only and non-destructive behavior, and the description adds concrete behavioral details about list/show actions, filtering, sorting, and pagination. There is no contradiction between the description and annotations.

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

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

The main description is a single, front-loaded sentence that states the resource, actions, and key capabilities. The longer field lists live in the schema and do not bloat the prose description.

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 absence of an output schema, the description adequately conveys that the tool returns coupon data and supports pagination. It does not spell out the exact response shape or error behavior, but the core context for invoking the tool is present.

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 schema already describes all parameters, so the baseline is 3. The description adds available field lists and a filter example, but much of this repeats the schema and the 'Purity filter' phrasing is unclear, providing only marginal additional 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?

The description clearly identifies the tool as reading discount coupons via 'list' or 'show' actions and mentions filtering, sorting, and pagination. It does not explicitly distinguish itself from the sibling coupon-write tool, though the name and actions make the read purpose evident.

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 no guidance on when to use this tool versus coupon-write or other read-oriented sibling tools. It lacks explicit context such as 'use for read-only coupon access' or 'use coupon-write for modifications.'

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 indicate write and destructive behavior. The description adds useful context by explicitly warning that updates replace supplied discounts and can affect what clients pay, which goes beyond the raw schema.

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

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

The description is compact, front-loaded with the core action, and packs essential operational details into two sentences without unnecessary 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?

Despite having no output schema, the description covers the necessary context: permissions, required inputs, update behavior, and financial impact. It is sufficiently complete for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100% and the description adds meaningful constraints not obvious from types alone, such as 'required for create', 'pass null on update to clear', percentage limits, and fixed-coupon behavior. This strongly supports correct parameter usage.

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?

Description clearly states the tool creates or updates discount coupons, distinguishing it from the read-only sibling coupon-read. The verb and resource are specific and 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?

Mentions required coupon permission, creation requirements (unique code, type, discounts), and warns that updates replace discount collections. It does not explicitly say 'use coupon-read for retrieval', but the create/update framing makes the intended usage 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 establish the safe read-only profile, so the bar is lower. The description adds a non-obvious behavioral constraint: results are scoped to activities visible to the authenticated staff member, which is meaningful auth-driven filtering not captured in 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?

Two tight sentences, front-loading purpose then the required parameter and capabilities. No filler or 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 read-list tool with full schema coverage, no output schema, and annotations carrying the safety profile, the definition covers purpose, required input, capabilities, and the visibility caveat. The return shape and total-count behavior are left unspecified but not critical.

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 pagination defaults, sort syntax, filter operators, and the action enum all documented in the schema itself. The description only restates that filtering/sorting/pagination exist and that deal_id is required, adding no syntax 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 (list) and resource (logged and scheduled activities for a deal), which distinguishes it from deal-activity-write and user-activity-read by the 'read' scope and 'deal' target. It does not name a sibling explicitly, but the resource is unmistakable.

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 a clear precondition ('Requires deal_id') and notes filtering/sorting/pagination support, which implies read-and-inspect use. However, it never states when to prefer this over user-activity-read or how it relates to deal-activity-write, leaving routing to inference.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses that delete permanently removes the activity from both the deal and contact, that update preserves omitted scheduling fields, and that changes flow through normal permissions and history logs. This is meaningful mutation and side-effect context an agent needs before acting.

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?

Five dense sentences, all front-loaded around the action requirements and then the behavior notes; each sentence carries distinct information with no filler. It is slightly long but nothing reads as redundant.

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

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

With no output schema needed and annotations covering the safety profile, the description still covers all four actions, their parameter requirements, scheduling behavior, and delete side effects, leaving nothing an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so per-field meaning is already documented; the description still adds cross-action semantics, e.g. that update only accepts scheduled_at for a pending activity and can reschedule/reassign, and that a create without scheduled_at logs a completed activity. This goes slightly beyond the per-parameter schema text.

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

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

The description opens with a specific set of verbs (create, update, delete, complete) acting on a clear resource (deal activities), so the tool's function is unambiguous. It does not explicitly distinguish itself from the deal-activity-read sibling, relying on the write/read naming convention instead, which keeps it from a full 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?

It gives clear conditional guidance tied to actions: deal_id always required, activity_id required for update/delete/complete, content required for create/update, and scheduling fields only apply on create/update. It stops short of naming alternatives or stating when not to use this tool versus the read counterpart.

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

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

Annotations already declare readOnly, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: conversation ticket permissions are required, an unstarted conversation returns an empty list, and staff notes are excluded because they are activities. This adds auth and edge-case transparency, though no rate-limit or pagination behavior beyond the schema.

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

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

Four short sentences, front-loaded with the core purpose and required parameter. The permission note and empty-list edge case follow logically, and every sentence carries useful 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 6-parameter list tool with nested filters and no output schema, the description covers the key non-schema behaviors: permissions, empty-conversation return, and staff-note exclusion. It does not describe the returned message shape, but with rich sort/filter field lists in the schema and no output schema, that omission is minor.

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 parameters are already fully documented. The description reiterates that deal_id is required and that filtering, sorting, and pagination are supported, but adds no syntax or semantic detail beyond what the schema provides. 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?

States a specific verb and resource: 'List client-facing messages in a deal conversation.' It distinguishes itself from deal-message-write by being a read, and from deal-activity-read by noting 'staff notes are activities.' An agent can identify the tool's purpose without opening the schema.

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

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

Gives clear context: requires deal_id, supports filtering/sorting/pagination, and conversation ticket permissions apply. The clause 'staff notes are activities' implicitly routes staff-note queries to deal-activity-read. It stops short of explicitly naming that alternative or other sibling message tools, so it is not a full when/when-not guide.

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, destructive, and open-world, yet the description adds genuinely new behavioral context: creates trigger outreach gates and notifications, each create emits a separate message even for repeated text, updates are limited to your own message, and edits/deletes cannot recall already-delivered email. That last point is exactly the kind of irreversibility detail an agent needs before calling a destructive tool.

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

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

Front-loaded with purpose and then layered by increasing specificity, with no filler sentences. It loses a point only because the parameter-requirement sentence duplicates what the schema and its required[] array already state.

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 four-parameter mutation tool with no output schema but with annotations covering the safety profile, the description supplies everything needed to call it correctly: ownership limits, notification side effects, non-recall of delivered mail, and routing for out-of-scope content. Nothing material is missing.

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

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

Schema description coverage is already 75% and the schema documents all four parameters, including the action-conditional requirements. The description largely restates those same facts (deal_id required everywhere, message_id for update/delete, message max 65535 chars) without adding format or validation 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?

The first sentence gives a specific verb set (create/update/delete) and a specific resource (client-facing messages on a deal), which cleanly separates it from the read sibling deal-message-read. It further disambiguates from deal-activity-write by explicitly stating that internal notes belong there.

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 when to use it (client-facing messages, with create/update/delete variants), when not to use it (internal notes -> deal-activity-write; staff-only messages are rejected outright), and the per-action parameter preconditions. The routing rule to the alternative sibling is explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context: responses include visible pipeline card IDs usable by pipeline-item-write, and monetary values are access-gated by invoice permissions. No pagination limits or failure modes are described, 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?

Roughly four sentences, front-loaded with the verb/resource and then the cross-tool routing. Sentences are information-dense but slightly cramped, packing data-model, permissions, return values, and siblings together with no explicit separation.

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

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

For a read-only tool with full schema coverage and no output schema, the description covers the notable extras an agent needs: the parent/child relationship with contacts, the pipeline_id correlation to pipeline-item-write, and the invoice-access requirement for deal values. It omits return shape and pagination envelope details, but these are minor for a read tool.

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

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

Schema coverage is 100% and each parameter already carries its own description, sort syntax, and filter examples, so the schema does the heavy lifting. The description only reinforces that list supports filters, sorting, pagination and an optional pipeline_id, adding no syntax or semantics 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 pair (list/show) on a named resource (sales deals) and clarifies the data model: multiple deals can belong to the same contact. An agent can distinguish this read tool from deal-write, deal-activity-read, and deal-message-read without opening schemas.

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

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

Explicitly routes activity and conversation reads to deal-activity-read and deal-message-read with deal_id, and notes deal values require invoice access. It does not explicitly state when to choose 'show' over 'list' beyond the schema's id requirement, so it falls short of full when/when-not guidance.

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

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

Annotations already flag this as a destructive, non-read-only, open-world write. The description adds substantial context beyond them: create also builds the first pipeline card, update preserves omitted fields and accepts null to clear, reassignment moves activities and the conversation while invoices keep their original client, closed deals lock value and service, and closing a deal closes its conversation ticket and can fire integrations. These side effects are exactly what an agent needs and are not derivable from annotations.

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

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

Front-loaded with the action list, then prerequisites, then side effects, then sibling routing, then the delete boundary. Every sentence is functional, though the dense run-on enumeration of required fields and null-clearing rules makes it a heavy read with little visual structure.

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

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

For a 13-parameter multi-action mutation tool with no output schema, the description covers required inputs, side effects, state locks, reassignment consequences, integration triggers, and sibling alternatives. 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 92%, so the baseline is 3. The description goes further by stating cross-parameter constraints the per-field schema cannot express – create requires user_id/pipeline_id/stage_id/title plus either value or service_id, and the null-clearing/locking rules for company_id, owner_id, service_id, and value on update.

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 opening sentence names the exact resource (sales deals) and enumerates every action the tool supports (create, update, mark_won, mark_lost, reopen). It also explicitly distinguishes itself from pipeline-item-write, deal-activity-write, and deal-message-write, so an agent can route without opening the sibling schemas.

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

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

Gives concrete when-to-use conditions for each action, including create prerequisites (user_id, pipeline_id, stage_id, title, and either value or service_id) and the boundary 'Does not delete deals.' It also names the alternatives and the conditions that select them (pipeline-item-write to move cards, deal-activity-write with deal_id, deal-message-write for client 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 declare readOnlyHint true and destructiveHint false, and the description 'List or show' is consistent with no side effects. There is no contradiction, though the description adds no additional behavioral 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?

The description is a single clear sentence, and parameter descriptions are concise without redundant fluff. No unnecessary text is present.

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 tool, the description adequately covers actions and parameter usage, including defaults and action-specific requirements. There is no output schema, so return format is not needed, and the read-only annotation and sibling naming add sufficient context.

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 descriptions clarify action-specific applicability, such as 'Required for show' and 'for list'. The filter description includes an example and the sort description explains the :asc/:desc syntax, adding useful meaning beyond basic 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 explicitly states the verb 'List or show' and the resource 'form folders', along with filtering, sorting, and pagination. The title 'Read Tool' distinguishes it from the sibling form-folder-write tool.

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 implies usage for read operations but does not explicitly state when to use this tool versus alternatives such as form-folder-write. The read-only annotation and sibling naming provide context, but no explicit 'use this when' 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?

Discloses key behavioral constraints: parent folder must match type and nesting max 5 levels. No contradiction with annotations; readOnlyHint false and destructiveHint false align with a create operation.

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

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

Three short sentences, no filler. All sentences add value.

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

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

Covers creation constraints and points to form-write for filing, enough for a simple create tool without output schema. The presence of form_folder_id for 'show' in schema while action only lists create creates minor ambiguity.

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 covers all 6 params with descriptions; description reinforces that name/type are required for create and explains parent_id constraints. form_folder_id is described but action enum only supports create, a minor ambiguity.

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?

Clearly states the tool creates a form folder and distinguishes it from form-write by saying filing forms goes there. Names the resource and action precisely.

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 required inputs (name, type), parent same type, and 5-level nesting limit, plus directs to form-write for filing. Could more explicitly state when to use this vs read tool, but context is strong.

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

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

The description adds context about the data returned ('forms and their fields and linked services') and mentions filtering/sorting/pagination. Since the annotations already declare readOnlyHint, openWorldHint, and destructiveHint, the description provides a bit more behavior insight without needing to repeat safety flags.

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 a single concise sentence that front-loads the main purpose ('List or show forms') and follows with key details. No fluff or redundant information, making it easy to parse quickly.

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

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

The description gives a reasonable idea of what to expect (forms, fields, linked services) and mentions list capabilities. Since there is no output schema, the description provides enough context for an agent to understand the tool's scope, though it lacks details on the response structure or difference between list/show responses.

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

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

The input schema provides descriptions for all parameters (100% coverage per context), including detailed examples for sort and filters. The tool description itself does not add extra meaning beyond the schema, but the schema is already clear, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List or show forms and their fields and linked services.' It uses specific verbs (list/show) and identifies the resource (forms), making it easy to distinguish from write tools like form-write.

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 mentions that 'Lists support filtering, sorting and pagination,' giving some usage guidance for the list action. However, it does not explicitly state when to use this tool versus alternatives (e.g., form-write for modifications) or provide conditions for when not to use it.

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

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

Clearly discloses destructive behavior: 'Updating fields replaces the full list and deletes omitted fields; preserve existing field IDs.' Also notes 'Field edits are blocked for forms with white-labeled services.' These details go beyond the annotations (destructiveHint) by explaining exactly what happens, making behavior fully transparent.

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 five sentences, with the primary purpose stated first ('Create or update forms.'). Each subsequent sentence adds a distinct, necessary detail without redundancy or fluff.

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

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

For a tool with 11 parameters and nested field objects, the description covers key behavioral rules (replacement/deletion semantics, form-type requirements, white-label blocking) while relying on the fully covered schema for parameter details. It provides sufficient context for correct invocation without over-explaining.

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 descriptions already cover all 11 parameters, so baseline is 3. The description adds cross-parameter semantics such as 'Creation requires type, name and the full initial fields list' (conditional requirements) and 'Order/contact forms require email' (domain rules not obvious from individual parameter descriptions), providing additional meaning beyond the schema.

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

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

The description opens with 'Create or update forms,' which clearly names the verb and resource. It distinguishes this write tool from siblings like form-read and form-folder-write by focusing on form creation/update operations.

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

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

Provides usage guidance such as 'Creation requires type, name and the full initial fields list' and 'Omit fields to change form settings only.' It also notes domain rules like order forms requiring a service-bearing field. However, it does not explicitly state when not to use this tool versus alternatives, though the context makes it inferable.

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?

While annotations already indicate read-only and non-destructive behavior, the description adds transparency by specifying what is returned (canonical source URL and bounded document content), which is not covered by annotations.

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

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

The description is concise, using two sentences to convey the action, the input, and the output. No unnecessary details or 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?

The description provides the key contextual details: the source of the ID, the action, and the return type. It could be slightly more explicit about what 'bounded document content' entails (e.g., size limits or format), but it is sufficient for an agent to use the tool correctly.

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

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

The single parameter document_id is well described as an ID returned by search-wayfront-docs, with a warning not to guess IDs. This fully covers the parameter's meaning and source.

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

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

The description clearly states the action (retrieve) and the resource (Wayfront help-center document), and distinguishes it from the related search tool by specifying that it uses a document_id from search-wayfront-docs.

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 'using a document_id returned by search-wayfront-docs' implies the correct workflow (search first, then retrieve), providing context on when to use this tool. However, it does not explicitly name alternatives or state when not to use it, but the guidance is sufficient.

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 safe-read profile is covered without the description. The description is consistent with those hints (“Query invoices”) but adds no behavioral detail such as pagination limits, filter operator semantics, or what is returned. With annotations carrying the safety burden, a 3 is appropriate.

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, purpose front-loaded, then the actions enumerated inline. No filler or repetition; every clause carries information.

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

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

For a read-only query tool with 100% schema coverage, no output schema, and annotations covering the safety profile, the description covers the essentials an agent needs to pick the right action. It could note that the result set is paginated/filterable in a way that matters for query planning, but nothing critical is missing.

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

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

Schema description coverage is 100% and the schema already documents page, sort, limit, filters (with the full field list and status ID mapping) and invoice_id. The description names filtering/sorting/pagination but adds no syntax, operator, or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (query) and resource (invoices), and breaks the tool into its two concrete actions, list and show, each with a one-line scope. An agent can tell the two modes apart immediately. It does not differentiate itself from sibling tools, though no sibling covers invoices, so the gap is minor.

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 action descriptions imply when to use list (filtering/sorting/pagination) versus show (single record by ID), which is real usage guidance. However, there is no explicit when-not guidance, no prerequisites, and no routing to alternatives among the many sibling read/write tools.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with a read-only listing operation. The description adds no additional behavioral details beyond what the annotations provide.

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

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

The description is concise and efficiently communicates the tool's purpose and key capabilities without unnecessary detail.

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

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

The description provides enough context for invoking a list operation, including filter and sort field lists. It does not describe the return shape, but for a straightforward list operation this is not a significant omission.

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?

All parameters have descriptions, and the filter parameter includes an example and a list of available fields. The sort parameter also enumerates valid fields. This goes beyond basic schema coverage and helps clarify how to construct queries.

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

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

The description clearly states the tool's purpose: listing logs. It identifies the resource ('logs') and the action ('list'), and distinguishes it from sibling tools by the specific log-domain focus.

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 conveys usage context by explaining that the tool supports filtering, sorting, and pagination for log queries. It does not explicitly compare to alternatives, but the purpose is clear enough for an agent to know when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds useful behavioral context beyond the schema: the 'visible order' precondition, the staff-only field in results, and support for filtering, sorting, and pagination. It does not contradict the annotations.

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

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

The description is one concise, front-loaded sentence that states the main action first, then the key prerequisite and capabilities. No filler or redundancy; every clause contributes useful 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?

The description gives a workable overview for a basic list call, but it does not define what makes an order 'visible' nor describe the output shape beyond the staff-only flag. With no output schema, some return-structure information would help; still, the rich parameter schema compensates partially.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description adds a high-level statement about requiring order_number and supporting pagination/sorting/filtering, but it does not explain parameter meanings beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource — 'List messages for a visible order' — and adds a distinguishing detail: 'including whether each message is staff-only.' This clearly separates it from write siblings like order-message-write and from ticket-message-read by scoping to orders.

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 implies the use case (reading messages for a specific order) and states a prerequisite ('Requires order_number'), but it does not explicitly contrast with alternatives such as ticket-message-read or order-message-write. Usage context is present, but when-not-to-use guidance is absent.

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

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

The description goes beyond the annotations by warning that sent messages cannot be recalled and that the normal notification, webhook, and broadcast pipeline will run. This makes side effects and irreversibility explicit.

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

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

The description is compact and well-structured: three sentences cover purpose, requirements, defaults, side effects, and irreversibility without unnecessary filler or 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?

For a simple write tool with no output schema and no nested objects, the description includes the necessary purpose, inputs, defaults, and side effects. It does not address error conditions or return behavior, but these are not critical given the tool's simplicity.

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 schema already covers all four parameters with descriptions, and the tool description adds meaningful context around order_number, message, and staff_only behavior. It does not add validation details, but the provided semantics are sufficient for basic usage.

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

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

The description clearly states the action: 'Post a message to an order.' It identifies the resource, the operation, and the required inputs, leaving no ambiguity about the tool's primary purpose.

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

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

It provides practical usage details such as requiring order_number and message, the staff_only default, and the client-notification behavior when set to false. It does not explicitly contrast with read-only alternatives, but the write-oriented purpose is clear enough.

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 the 'visible orders' scoping nuance, which is useful, but says nothing about access restrictions, return volume, or how pagination interacts with large result sets.

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; the core capability is stated immediately and nothing is redundant.

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

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

There is no output schema, but the rich 100%-covered input schema (including nested filter objects and the status ID legend) carries most of the load for a read tool. The description is adequate for invocation, though it could have noted the list-vs-show behavior or result shape since no output schema exists.

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

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

Schema description coverage is 100%, so every parameter (page, limit, sort, action, filters, order_number) is already documented in the schema with examples and enumerated values. The description's generic mention of filtering/sorting/pagination restates the schema rather than adding syntax or format detail, 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 pair ('List or show') and resource ('orders') and mentions the operational modes (filtering, sorting, pagination). It is clear what the tool does, but it does not differentiate itself from siblings like order-write or order-message-read, nor does it explain the list-vs-show distinction that the action enum implies.

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?

'visible orders' hints at the scope and the description implies the two actions, but there is no explicit when-to-use guidance, no statement of when to prefer order-write or the order-message/order-task siblings, and no prerequisites (e.g., permissions needed to see certain orders).

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 provide readOnlyHint=true and destructiveHint=false. The description adds the nuance of 'visible tasks,' implying some tasks may be hidden, which is not covered by annotations. It also mentions filtering, sorting, and pagination, giving behavioral context beyond the safety profile. No contradictions.

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 concise sentence with the core purpose front-loaded. Zero waste. Every word 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?

Given the simple read-only nature and the rich schema covering all params, the description is sufficient. It lacks explicit return format details, but with no output schema and the tool being a list operation, the expected response is clear from context. The 'visible' filter is a minor behavioral note not fully elaborated but acceptable.

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 all parameters are documented with descriptions. The description's mention of 'filtering, sorting and pagination' maps to existing params but adds no new meaning. Baseline 3 is appropriate since the schema carries the semantic weight.

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?

Description states a specific verb ('List') and resource ('tasks for an order'), clearly distinguishing it from sibling tools like order-read (orders) and order-task-write (writes). The word 'visible' adds precision. No ambiguity.

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?

Description clearly indicates when to use it (to list tasks for an order) and requires order_number. It does not explicitly mention alternatives or when not to use, but the tool name and purpose make the context obvious. No misleading 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?

The description discloses important side effects beyond the destructiveHint annotation, including assignment replacement, workflow reset behavior, bulk action effects, client email notifications, and HTML sanitization needs. This exceeds the baseline set by annotations.

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

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

The description is dense but well-organized, front-loading the purpose and then systematically covering action rules, parameter semantics, and warnings. Every sentence adds necessary information without 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 complex write operation with 11 parameters and no output schema, the description covers all critical behaviors, edge cases, and side effects. It is complete enough for an agent to use the tool safely and 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?

Although the schema already describes each parameter, the description adds crucial cross-parameter semantics like mutual exclusivity between for_client and employee_ids, precedence of deadline over due_at, and the meaning of omitting task_id. This goes well beyond the schema.

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

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

The description clearly states the tool's actions ('Create, update, delete, complete or reopen order tasks') with a specific resource and verb. It is easily distinguished from siblings like order-task-read.

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

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

The description gives detailed action-specific requirements, such as task_id for update/delete and optional task_id for complete/reopen. It does not explicitly name alternative tools to avoid, but the context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the write/irreversible nature is known. The description still adds real value beyond them: collection fields replace their complete lists, omitted fields remain unchanged, and changes can notify clients and trigger integrations.

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 compact sentences, front-loaded with the scope of the update, then the two rules that matter most (replace semantics, omitted-field preservation), then side effects. No filler.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the operation scope and the key replacement behavior. It omits permission/access requirements and any statement of what the response returns, though annotations cover the safety profile.

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

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

Schema description coverage is 100%, so every parameter already documents its format, limits, and replacement semantics (e.g., tags, employees, linked_orders all note 'replaces'). The description's field list restates what the schema carries rather than adding new syntax or constraint detail, 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 (Update) and resource (an order), then enumerates the updatable facets (status, dates, notes, service, assignments, tags, metadata, linked orders). An agent can distinguish this from order-read at a glance. It stops short of naming sibling tools, so it is clear but not maximally differentiated.

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

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

No when-to-use or when-not-to-use guidance is offered. The mention that changes 'can notify clients and trigger integrations' hints at caution but never states prerequisites, permissions, or which alternative tools to consider when a narrower write is 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the word 'accessible', implying permission-scoped results, and clarifies allowed item types in filters. These are useful but modest additions; it does not disclose return format or pagination behavior beyond what schema provides.

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 conveys the core purpose and the most important filter nuance. It is front-loaded with the verb and resource, and every phrase earns its place with 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?

The tool has 6 parameters and a nested filters object, but the schema is rich enough to carry most details. The description omits the distinction between list and show and the requirement for pipeline_item_id in show, both of which are in the schema. Given no output schema, some return-format guidance could help, but the description is adequate for basic invocation.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds one meaningful detail: that item types in filters accept user, company, or order, which clarifies the filter values for itemable_type. This is a small increment over the schema, keeping it at baseline 3.

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

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

The description states a clear verb+resource ('List or show accessible pipeline cards') and mentions key capabilities (filtering, sorting, pagination). It does not explicitly distinguish itself from sibling read tools like pipeline-read, but the name and phrasing make the target resource 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?

No guidance on when to use this tool versus alternatives. It does not mention pipeline-item-write for mutations or pipeline-read for pipeline-level reads. The description implies a read operation but offers no exclusions or alternate routes.

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

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

The description adds valuable side-effect context with 'Changes can trigger configured automations,' going beyond the destructiveHint annotation. It could further disclose irreversibility or external consequences, but this is already meaningful behavioral transparency.

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 cover the main operation, per-action requirements, domain constraints, and side effects without redundancy. The key verb phrase is front-loaded, and every sentence 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?

The description fully covers all three actions, their parameter dependencies, and entity-type restrictions, which is sufficient for a structured mutation tool with complete schema descriptions. Minor gaps like response behavior or sort_order effects are already handled by the schema or are not critical for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by mapping required parameters to each action and clarifying itemable_ref semantics: orders use order numbers while users, companies, and deals use IDs.

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

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

The description clearly states the tool's action: add, remove, or move pipeline cards, with distinct verbs and a specific resource. It is immediately distinguishable from the sibling pipeline-item-read tool and does not rely on the title alone.

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

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

It provides action-specific required parameters and pipeline type compatibility, making usage conditions clear. It does not explicitly contrast with pipeline-item-read, but the mutation actions themselves make the intended use obvious.

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 not burdened with safety disclosure. It adds useful behavioral context by noting 'accessible' pipelines (permission filtering) and that lists support filtering/sorting/pagination. This goes beyond the annotations without contradicting them.

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

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

Two concise sentences with no filler. The purpose is stated first, followed by a summary of list behavior. Every word 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 read-only tool with full schema coverage and safety annotations, the description is adequate. However, it lacks details on the return format (no output schema) and does not clarify what 'show' returns versus 'list'. The absence of output schema info leaves the agent guessing about response shape, which is a minor gap.

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

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

Schema description coverage is 100%, so all six parameters already have clear definitions. The description summarizes list capabilities but does not add meaning beyond the schema. Since the schema handles parameter documentation, the baseline 3 is appropriate.

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

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

The description states a specific verb ('List or show') and a clear resource ('accessible sales or production pipelines and their stages'), and distinguishes between the two actions. It is unambiguous and differentiates the read tool from its write counterpart by its name and content.

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 implies usage for reading pipelines but does not explicitly state when to use this tool over alternatives (e.g., pipeline-write for modifications). It mentions list capabilities (filtering, sorting, pagination) but offers no explicit when-not-to-use or guidance for choosing between 'list' and 'show' 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?

The description discloses a key side effect: omitted stages are preserved and never deleted, and explicitly routes card changes elsewhere. It does not contradict the destructiveHint annotation, though it does not elaborate on other potential destructive effects or result/error behavior.

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

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

The description is three compact sentences, front-loaded with the main purpose, and avoids repeating detailed field descriptions already covered by the schema.

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

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

For a 9-parameter write tool with nested stages, the description covers the most important behavioral context: create requirements, update semantics, stage preservation, and scope separation from pipeline-item-write. It is complete enough for normal use, though it does not touch on return values or failure modes.

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 adds meaningful cross-parameter semantics not present in the schema alone: creation requires type/name/stages, pipeline_id is required for updates, stage id presence means edit vs add, and omitted stages are preserved. This significantly clarifies the nested stage behavior.

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

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

The description opens with a specific verb-resource pair, 'Create or update pipeline structure', and clarifies that cards belong to a separate tool, distinguishing it from pipeline-item-write. The create/update action 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 when creation is needed (requires type, name, stages), how updates affect stages, and redirects card management to pipeline-item-write. It does not explicitly contrast with pipeline-read, but the write purpose is clear enough.

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 read-only and non-destructive behavior. Description adds that it returns excerpts, source links, and document IDs, which is consistent and provides useful output expectations.

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 concise sentences efficiently cover purpose, usage scenarios, and output format. No fluff or redundant 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 simple search tool with two parameters and no output schema, the description is complete: it communicates what it searches, why to use it, and what it returns, making it self-sufficient.

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

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

Schema descriptions fully cover both parameters: query as a natural-language question, limit with default and max. The description adds no extra parameter details beyond the schema, so baseline holds.

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?

Clearly states the verb 'Search' and resource 'customer-facing Wayfront help-center documentation'. Distinguishes from sibling get-wayfront-doc by noting document IDs are returned for that tool.

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?

Lists specific use cases (product setup, workflows, behavior, limitations, handoffs) and implies the companion tool for retrieval. Could be more explicit about when not to use, but the given topics are sufficient for typical selection.

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

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

The description is consistent with the readOnlyHint and destructiveHint annotations; it only describes read operations and does not imply side effects. It does not add extra behavioral details like auth or rate limits, but the annotations already cover the core read-only nature.

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 one concise sentence that enumerates the valid actions and highlights the key list capability. It avoids unnecessary prose and front-loads the main 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?

Given the lack of an output schema, the description covers the main operations and the list capabilities. It could be slightly more explicit about the differing outputs of 'show' vs 'get_task_templates', but the action enum and parameter descriptions fill most gaps.

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 schema provides detailed descriptions for most parameters, including the action enum, filter example, and sortable fields. The description adds little beyond those schema details, and the phrase 'Purity filter object' appears to be a typo that could slightly confuse, though the example mitigates 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?

The description clearly states the three read actions ('list', 'show', 'get_task_templates') and the resource type (services). It is readily distinguishable from the sibling service-write tool.

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 notes that list supports filtering, sorting, and pagination, but it does not explicitly say when to use this read tool versus the sibling service-write alternative. Action-specific requirements are left to the parameter descriptions rather than stated as usage guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds the crucial detail about what is destroyed: sync_task_templates replaces the full checklist, relationship collections replace their full lists, and any omitted template whose ID you drop is deleted. It also notes omitted fields stay unchanged and that pricing/recurrence/renewal affect future delivery, which 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?

Five tight sentences, each carrying a distinct constraint (write scope, future-delivery effects, checklist replacement, deadline units, list-replacement semantics), with the most important write-vs-read routing first. Slightly telegraphic in places but no filler.

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

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

For a 28-parameter destructive write tool with no output schema, the description covers the highest-risk gotchas: full-list replacement, deletion of omitted templates, unit conversion, and partial-update semantics. It leaves unaddressed things like auth/permission requirements and the shape of success responses, which a caller may still need.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes beyond it by calling out the replacement-and-retention workflow for task_templates and re-emphasizing the hours-vs-days conversion for deadline. It does not add new per-field detail beyond what the schema already documents for the remaining 26 parameters.

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

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

States specific verbs and resources: create/update services plus a third action sync_task_templates, all front-loaded in the first sentence. It also names the sibling service-read and its get_task_templates action, so an agent can distinguish read vs write and pick the right tool without opening a schema.

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

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

Gives concrete sequencing guidance: read service-read action get_task_templates first and retain IDs that should remain before calling sync_task_templates. It also flags the unit trap (deadlines in HOURS, not days). No explicit exclusions or when-not-use cases are stated, but the 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 indicate read-only, non-destructive, and non-open-world behavior. The description adds no further side-effect or behavioral detail beyond the obvious 'View' action, so it meets but does not exceed the baseline.

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

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

The description is a single concise sentence with no filler, redundant wording, or unnecessary detail. It is well-structured and immediately understandable.

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

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

For a simple read-only tool with no output schema, the description gives enough context about what is being viewed. It could slightly improve by mentioning that no other actions are supported, but the enum already conveys this.

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 only parameter 'action' has full schema coverage with an enum of ['view'] and a generic description. The tool description adds no additional semantic detail beyond what the schema already makes clear.

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?

Description clearly states the tool's function with a specific verb ('View') and resource ('current workspace branding and settings'), and it is easily distinguished from the sibling 'settings-write' tool.

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 implies read-only usage but does not explicitly state when to prefer this tool over alternatives such as 'settings-write' or 'workspace-info'. No direct when-to-use or when-not-to-use guidance is provided.

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 indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate mutation. It adds useful constraints about logo URLs and excluded actions, but does not detail potential overwrite or irreversible side effects. No contradiction with annotations.

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

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

The description is a single concise sentence that lists the affected fields and includes important constraints and exclusions without unnecessary detail or 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 simple update semantics and full schema parameter descriptions, the description provides enough context for an agent to invoke the tool correctly. It includes practical exclusions and URL constraints; a return-value description is not necessary since no output schema is declared.

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 schema already covers 100% of parameters with examples and constraints, so the baseline is 3. The description reinforces the logo URL requirement and adds exclusion context, but does not significantly extend the parameter-level meaning 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 uses the specific verb 'Update' and enumerates the exact workspace settings affected (name, colors, timezone, contact link, currency, business information, email sender name, logos). This clearly distinguishes it from the sibling settings-read tool.

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 clearly implies this tool is for modifying workspace settings, and explicitly lists what it does not do (connect Stripe, set custom domain/sending email, switch live mode). This gives useful exclusionary guidance, though it does not explicitly say 'use settings-read to view settings'.

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

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

The description aligns with readOnlyHint and destructiveHint annotations, confirming no side effects. It does not add details about return format or error conditions, but the annotations already cover the key behavioral aspects.

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 a single, focused sentence that immediately conveys the tool's purpose with no unnecessary verbiage. It is optimally concise.

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

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

The description is adequate for a simple read operation. It specifies the subject (notification settings and events) and the scope (already-connected Slack workspace). Absence of an output schema is acceptable given the tool's simplicity, though it could clarify the exact return 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?

The only parameter 'action' has an enum of ['view'] with a generic description 'Action to perform.' While the schema fully specifies the allowed value, the description adds minimal context beyond what is already evident from the enum.

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

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

The description clearly states the tool's function: viewing notification settings and available events for a connected Slack workspace. It distinguishes it from the sibling slack-write tool by focusing on read-only actions.

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 implies usage for read-only inspection of Slack configuration. It does not explicitly state when to avoid using it, but the read-only nature is obvious from the verb 'view' and the annotation, making it sufficient for typical use.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutating nature is known. The description adds valuable behavioral context beyond that: it specifies the partial update semantics (only listed events change) and the dependency on connection/licensing, which are not captured in annotations. This helps an agent anticipate side effects and failure conditions.

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

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

The description is three concise sentences: purpose, behavior, and prerequisite. It is front-loaded with the main action, then clarifies scope and requirements. Every sentence earns its place without redundancy or filler.

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

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

For a write tool with two parameters (one required) and no output schema, the description covers the essential aspects: what it updates, how partial updates work, and prerequisites. It does not mention error handling or post-update confirmation, but those are not typically required for a mutation tool. The annotations already signal destructiveness, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema fully documents both 'action' and 'events' (including nested event fields). The description does not add new parameter-level meaning; it only reiterates the partial update behavior that the schema already hints at via the events description. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the verb 'Update' and the resource 'notification events and channels' for an already-connected Slack workspace, making its purpose unambiguous. It also adds the partial-update behavior ('Only listed events change; others remain unchanged') which distinguishes it from a full overwrite and implicitly from the read 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?

It provides clear context for when to use the tool (updating Slack notifications for a connected workspace) and prerequisites (Slack must be connected and licensed, connecting requires the Wayfront interface). It does not explicitly name alternatives like slack-read, but the context is sufficient for an agent to infer when to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior that annotations cannot: the access scope ('Available to every staff member') and the exact return payload (ID, first/last name, role, is_you). It does not discuss pagination beyond what the schema's limit field already explains, so it falls 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?

Purpose is front-loaded in the first clause, followed by access scope, return shape, a parameter hint, and sibling routing. Four sentences, each carrying distinct information with no repetition of the name or title.

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

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

With no output schema, the description correctly enumerates the return fields so the agent knows what comes back, plus access scope and sibling alternatives. For a zero-required-param read lookup this is complete enough to call correctly without further inference.

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

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

Schema description coverage is 100%, so the baseline is 3 — the schema already documents limit, search, and assignable_to thoroughly. The description restates the assignable_to behavior ('list only staff whose role can access tickets or orders') and frames its purpose via the ticket-write/order-write example, but adds no format or syntax 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 verb and resource ('Find colleagues by name to get their staff user IDs') and names the two most confusable siblings, team-tool and team-management-tool, with the boundary between them. An agent can distinguish this lookup tool from the team-management 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?

Explicitly routes the agent: use this tool for staff IDs (e.g. the employees list on ticket-write/order-write), use team-tool for full member details, and team-management-tool for invitations and role changes. It also gives the selection condition for assignable_to. When-to-use and when-to-prefer-alternatives are both covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the read-only, safe, closed-world profile is covered without the description. The description confirms this is a query-only tool but adds no behavioral context beyond what annotations and the schema already convey (no rate limits, no return-shape caveats), which is the expected lower bar when annotations carry the safety load.

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 terse sentences, front-loaded with the overall purpose and immediately followed by the action breakdown. Every clause earns its place with no filler or 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?

For a multi-action read tool whose params are fully documented by the schema and whose safety profile is carried by annotations, the description names both actions and their scope adequately. No output schema exists, but the return values are simple query results, so little is missing; a note on pagination defaults or filters syntax would have pushed it higher.

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 page, sort, limit, filters, and subscription_id in detail. The description adds no parameter-level detail (no format, constraint, or interaction notes) beyond the schema, so the baseline 3 for high coverage applies.

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

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

The description gives a specific verb+resource (query subscriptions) and enumerates the two actions with their distinct behaviors (list = filtered/paginated query, show = single by ID). It is clear and self-contained, but it does not differentiate itself from any sibling (e.g., other read tools), which is what would be needed for a 5.

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

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

The action descriptions imply when each mode applies (list for many, show for one by ID), but there is no explicit when-to-use guidance, no mention of alternatives, and no exclusivity/condition statements. Usage is inferable only from the action split, so it lands at the minimum-viable implied level.

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

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

The readOnlyHint and destructiveHint annotations already communicate safety, and the description is consistent with them. However, the description adds little beyond the annotation, such as pagination, ordering, or error behavior.

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 a single clear sentence that is immediately understandable and front-loaded with the primary action and resource.

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 list tool with no output schema, the description adequately states what is returned (tags and IDs). It is complete enough for basic usage, though it omits potential details like ordering or filtering.

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 schema covers the single parameter with an enum and description, so coverage is high. The tool description reinforces that 'action' is 'list', but it does not add substantial parameter-specific meaning beyond the schema.

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

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

The description clearly states the action ('List'), the resource ('workspace tags'), and the expected output ('their IDs'). It is specific and easily distinguished from sibling tools like tag-write.

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 implies a read-only usage by saying 'List', and the annotation reinforces this, but it does not explicitly mention when to use this tool versus alternatives such as tag-write.

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?

Read-only and destructive hints are already provided by annotations, so the description only needs to add context. It proactively mentions the required permission and the fact that this is a create operation, which is useful behavioral information.

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

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

The description is two short sentences with no redundant or filler content. It front-loads the primary purpose and then provides key usage details efficiently.

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

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

The description is adequate for the simple create operation and covers permission and key parameters. It does not describe return values, but no output schema is present and this is not essential for deciding when or how to call the 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?

Every parameter has a schema description, and the tool description adds practical meaning: name is required for creation, sort_order is optional and controls display order, and action is fixed to 'create'. This clarifies how to actually invoke the tool.

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

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

The description clearly states the tool creates a workspace tag, using a specific verb and resource. This distinguishes it from tag-read and other write tools for different resources.

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 specifies required inputs (name) and the required permission (tag-management). It does not explicitly differentiate from tag-read, but the create action and resource make the primary use case 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?

Describes side effects for each action: 'emails them their login' for create, 'changes their permissions' for update, and 'creates a new permission set' for create_role. It also mentions the constraint that roles cannot exceed your own permissions. While it doesn't dwell on potential destructive consequences, the actions are inherently non-destructive (no delete) and the description covers the key impacts. No contradiction with the destructiveHint 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?

The description is compact, using three sentences to cover all actions and key constraints. While it could be formatted with bullet points for clarity, it remains efficient and avoids redundancy. No filler or unnecessary wording.

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?

Provides sufficient context for correct usage: it identifies the three actions, points to the team query tool for reading and role IDs, states admin/owner restrictions, and clarifies the welcome email default. Given the tool's complexity (40 parameters), the description covers the essential operational context without needing to explain every permission field.

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% — every parameter has a description with relevant 'For "action"' qualifiers. The description text adds no extra parameter-level detail beyond what the schema already provides, but it does reinforce the role_id lookup via the team query tool. Baseline 3 applies because schema fully covers parameter semantics.

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?

Clearly states the tool's purpose ('Manage team members and roles') and enumerates the three distinct actions (create, update, create_role) with specific verbs. It also distinguishes itself from the read side by noting that reading team members belongs in the team query tool.

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

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

Provides explicit guidance on when to use this tool versus alternatives: reading team members is delegated to the team query tool, and role IDs are to be discovered via that query tool. Also states usage restrictions (admin-only for create_role, workspace-owner-only for admin accounts) and notes the welcome_email 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no behavioral detail beyond what the schema already exposes (action enum). It does not disclose any rate limits, permissions, or response characteristics beyond the read-only nature, which is already known from annotations.

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

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

Two sentences with zero wasted words. The core purpose is front-loaded, and the action breakdown is immediately clear. Structure is exemplary.

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

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

For a read-only tool with complete schema documentation and no output schema, the description covers the two actions and their parameter associations sufficiently. It could mention that it is the read-only counterpart to team-management-tool, but that is not essential for correct invocation. Overall, the agent has enough to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a high-level mapping: 'filtering, sorting, pagination' aligns with filters, sort, page, and limit; 'get a single team member by user ID' aligns with user_id. However, this is mostly a paraphrase of the schema descriptions and adds little new 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?

The description states a specific verb ('Query') and resource ('team members'), and immediately distinguishes two actions with distinct purposes ('list' with filtering/sorting/pagination, 'show' with user ID lookup). This clearly identifies the tool's function and separates it from write-oriented siblings like team-management-tool.

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 guidance on when to use this tool versus alternatives. The description does not mention team-management-tool or any other sibling, nor does it provide exclusions or conditions. The agent must infer from the action names and context.

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

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

The description is consistent with the readOnlyHint annotation and clearly states that it lists templates or returns full source, implying no destructive behavior. It adds useful context about the template type and source exposure, though it does not mention potential output size or permissions.

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 a single, focused sentence that efficiently conveys both capabilities and optional filters. There is no redundant wording or unnecessary detail.

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

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

For a read-only tool with no output schema, the description gives enough context about what actions are available and what the 'show' action returns. It does not describe the list output format in detail, but the purpose is clear and the parameter schema fills most remaining gaps.

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

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

The input schema already covers all parameters with clear descriptions, and the tool description restates the action-based filtering and show behavior. Since schema coverage is 100%, the description adds moderate context but does not significantly deepen parameter meaning beyond what is already provided.

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

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

The description clearly identifies the resource as workspace Twig templates and states the two supported actions: listing and showing full source. It does not explicitly differentiate itself from template-write or other read tools, but the action set and resource are specific enough.

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 filtering and the show action, but it does not say when to prefer this tool over sibling tools such as template-write or other read tools. There is no explicit 'use this for read-only operations' guidance in the description itself.

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

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

The description clearly discloses destructive behavior by stating that reset permanently deletes a custom page and that no version history exists. It also notes validation behavior (invalid Twig syntax rejected), consistent with the destructiveHint 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?

The description is compact and front-loaded, stating the core purpose first and then adding necessary warnings and usage guidance in four sentences. Every sentence contributes operational or safety-relevant information.

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

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

Given the destructive action and lack of an output schema, the description provides the essential context: intended use, required read-before-write flow, reset consequences, syntax validation, and absence of version history. It is complete enough for an agent to invoke the tool safely.

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

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

The input schema already provides full coverage of all parameters with detailed descriptions, including action enum semantics, data as full replacement source, template_name requirements, and is_active behavior. The description text itself does not add additional parameter-level meaning beyond that schema coverage.

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

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

The description clearly states the tool updates or resets workspace Twig templates used by client pages and emails, making its purpose and resource type explicit. It also distinguishes itself from template-read and other write tools by naming update and reset actions.

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 instructions to read template-read first before updating to preserve intended content, and explains when to use update versus reset. It also warns that resetting a custom page permanently deletes it and that invalid Twig syntax is rejected.

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 read-only and non-destructive behavior; the description adds useful context about visibility (only visible tickets) and staff-only content. It does not add richer behavioral detail like auth requirements, output shape, or how staff-only messages are treated, so it stays at the baseline-plus level.

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 states the action, scope, and capabilities with no filler. 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 read-only list tool with six schema-described parameters and no output schema, the description covers the essential preconditions, scope, and capabilities. A slightly richer mention of return structure or why visibility matters would make it 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%, so parameters are already documented in the input schema. The description adds only that ticket_number is needed and that filtering/sorting/pagination are supported, which adds no meaning beyond the schema.

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

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

The description names a specific verb and resource: "List messages for a visible support ticket", and adds the staff-only distinction. This clearly separates it from read/list siblings and from the write counterpart by focusing on read-only listing.

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

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

It states the hard prerequisite that ticket_number is required and says filtering, sorting, and pagination are supported, which implies when this tool is appropriate. It does not explicitly tell the agent when to prefer this over ticket-message-write or order-message-read, leaving destination decision 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?

The description adds meaningful behavioral context beyond the annotations: messages cannot be recalled, and the normal notification, webhook, and broadcast pipeline runs. This is consistent with destructiveHint and readOnlyHint.

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 brief and direct, conveying essential behavior and side effects in three sentences without unnecessary filler or 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?

The description covers inputs and side effects, but since there is no output schema, it does not indicate what the tool returns on success or failure. This leaves some ambiguity in expected outcomes for an agent.

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