FavCRM

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

With annotations already marking this as non-read-only and non-destructive, the description adds meaningful behavioral context: it validates the token and sends a 6-digit verification code, and notes it is part of a multi-step process. However, it does not cover edge cases like invalid token handling or email delivery failures, so it stops 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?

The description is two sentences long, front-loaded with 'Step 1', and every sentence serves a purpose: defining the action and directing to the next step. There is no 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 tool has one parameter, a full output schema, and annotations describing side effects, the description is complete for its scope. It clearly identifies the tool's role in a workflow and the expected next call, so an agent can use it correctly without additional 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%, so the schema fully documents the token parameter. The description does not add new meaning beyond what the schema already provides, but it aligns with the described behavior, keeping the baseline score of 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 clearly states it is 'Step 1 of agentic team invite acceptance' and specifies the action: validates a token and sends a code. It also distinguishes itself from the sibling accept_team_invite_verify by naming the next step, making the purpose 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?

The description explicitly explains when to use this tool—as the first step of accepting an invite—and instructs the agent to call accept_team_invite_verify next. This provides direct contextual guidance and an alternative/next-step reference, which is clear and 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?

Annotations indicate non-read-only and non-idempotent behavior; the description adds concrete side effects (joins user to company, returns a one-time key). It does not describe failure modes or code reuse consequences but adds meaningful 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?

One dense, front-loaded sentence with no filler. Every phrase delivers needed context: step position, verification, side effect, and output.

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

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

With an output schema present and a fully documented 3-parameter schema, the description adequately covers the workflow step and side effects. It could mention what happens on invalid or already-used codes, but the current information is sufficient for typical 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?

Input schema has 100% coverage with descriptions for token, code, and optional name. The description adds little parameter-level detail beyond 'emailed code,' so the schema carries the burden.

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 specific actions: verifies the emailed code, joins the invited user to the company, and returns a one-time MCP API key. It clearly identifies the resource and process and distinguishes itself from the sibling accept_team_invite_request by labeling it 'Step 2.'

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?

Frames tool as 'Step 2 of agentic team invite acceptance' and the schema notes the token comes from create_team_member_invite, implying a sequential workflow. It does not explicitly name alternatives or exclusions, but the step context 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?

Beyond annotations (which are all false), the description adds useful context that the document is stored as a single unit and that embedding/retrieval is handled elsewhere. This helps set expectations about what the tool does and does not do. No contradictions with annotations.

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

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

The description is three concise sentences, front-loaded with the action and resource, then use cases, then a behavioral note. Every sentence earns its place with no fluff 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 simple 2-parameter tool with an output schema present, the description covers the purpose, typical usage, and storage/retrieval behavior. It is complete enough for an agent to select and invoke the tool correctly, though it doesn't address uniqueness of names or explicit differences from url-scraping tools.

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% for both parameters (name and content), so the description adds little beyond what the schema already provides. The baseline of 3 applies; the tool description doesn't add meaningful parameter-level detail.

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 begins with a clear verb+resource ('Add a free-form text document to the knowledge base') and explicitly lists use cases (policies, FAQs, notes, brand voice), distinguishing it from retrieval tools like query_company_knowledge and URL-based tools like scrape_knowledge_url.

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 explicit context on when to use the tool ('Use for pasted policies, FAQs, internal notes, brand voice references') and clarifies that embedding/retrieval happens elsewhere, implying it is not for retrieval. However, it does not explicitly name alternative tools or list when-not-to-use scenarios.

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 non-read-only mutation with no destructive intent, so the bar is lower. The description adds the important requirement that each block must be a valid block object and enumerates the accepted types, which helps the agent validate inputs. It doesn't disclose behaviors like uniqueness constraints, ordering guarantees, or error handling, but it adds useful 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?

Two sentences, no filler. The first sentence states the purpose, the second covers block validity and supported types. 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 tool's complexity (19 distinct block types), the schema carries the full burden of field-level detail, and an output schema exists. The description covers the core semantics—append, valid block shape, available types—leaving nothing essential unexplained. The only gaps are optional behavioral notes (e.g., whether block IDs must be unique), but the schema is rich enough to compensate.

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 100% coverage, comprehensively documenting postId and blocks, including a full oneOf discriminator for every block type. The description's phrase '{ id, version, type, data }' adds only a minimal mnemonic; the schema remains the authoritative reference. The baseline 3 applies.

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

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

The description opens with 'Append one or more blocks to the end of a post,' using a specific verb and resource that clearly distinguishes it from sibling tools like replace_post_block, remove_post_block, and reorder_post_blocks. The scope is unambiguous and immediately actionable.

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 frames the tool's core use case: adding blocks to an existing post. It does not explicitly contrast with alternative operations (replace, remove, reorder) or state when not to use it, but the context is clear enough for typical appending scenarios, which justifies a 4.

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 destructiveHint=true and idempotentHint=true. The description adds behavioral context by specifying 'remove it from active survey lists,' clarifying that archiving is a non-destructive (or partially destructive) operation that hides the survey rather than completely erasing it. This complements the annotations without contradiction.

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

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

The description is a single sentence that is front-loaded with the verb and resource, followed by the key behavioral outcome. Every word earns its place with no 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 simple one-parameter tool with clear annotations and an output schema, the description sufficiently covers the operation's effect. It lacks details such as reversibility or what happens to survey responses, but these are not essential for agent invocation and the annotations fill 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% — the only parameter, surveyId, is already described as 'Survey ID to archive.' The tool description does not add further parameter semantics, 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 uses a specific verb ('archive') and resource ('survey'), and adds the effect 'remove it from active survey lists,' clearly distinguishing it from other survey operations like create_survey, update_survey, and delete_survey. This is explicit 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?

The description provides clear context: archiving removes a survey from active lists, which implies its use case without explicitly naming alternatives like delete_survey. It does not explicitly exclude other tools, but the phrase 'remove it from active survey lists' conveys when this tool is appropriate (when you want to hide but not necessarily permanently delete).

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=false, so the agent knows this is a mutation. The description adds no further behavioral context (e.g., whether assignments are overwritten, required permissions). It does not contradict annotations, but it also doesn't go beyond 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?

The description is a single, well-structured sentence that front-loads the core purpose and then provides a precise parameter hint. No wasted words.

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

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

Given the simplicity of the operation (2 params, full schema descriptions, and an output schema), the description is sufficient for an agent to decide and invoke. A minor gap is not stating whether the assignment replaces existing assignments, but this is not critical for basic usage.

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

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

Schema coverage is 100%, and both parameters already have descriptions ('users.id from list_staff.userId' and 'Service ID'). The description repeats the userId source, adding no new semantic 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 ('Assign a staff member to a booking service') with a specific verb and resource, and adds a useful pointer on how to obtain the userId. This distinguishes it from sibling tools like list_staff or set_staff_availability.

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

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

The description gives clear context: it tells the agent to use list_staff to get the appropriate userId, implying a typical workflow. It does not explicitly mention alternatives or exclusions, but the guidance is sufficient for a simple assignment tool.

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

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

The description adds meaningful behavioral context beyond annotations: it verifies job ownership and success, and explicitly states it does NOT charge credits because they were charged at submit time. This is useful safety/billing information not present in the annotations. Minor gap: it doesn't mention whether an existing featuredImage is overwritten, but otherwise 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?

Three sentences, front-loaded with the purpose in the first sentence, followed by use cases and key behavioral notes. Every sentence earns its place; no 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?

With an output schema present and a fully self-describing input schema, the description covers the essential context: what it does, when to use it, the verification behavior, and the credit implication. It is complete for this tool's complexity.

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 all parameters documented (jobId, postId, assetIndex, pollIfRunning, pollTimeoutMs). The description adds only context that the job is 'ai-media job's output' and 'featuredImage', but doesn't provide additional meaning beyond the schema. 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 clearly states the tool attaches a previously generated ai-media job's output as the post's featuredImage. This specific verb+resource+field combination distinguishes it from related siblings like generate_post_cover, upload_post_cover_from_url, and attach_tags.

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

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

Explicitly states when to use: when generate_post_cover timed out (job kept running) or when reusing the same generation across multiple posts. This provides clear context and names the alternative tool, fulfilling the 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 indicate a non-read-only, non-destructive operation, so the agent knows it's a mutation. However, the description adds no behavioral context beyond that—it does not clarify whether tags are appended to existing tags or replace them, nor any idempotency nuance. For a write operation, this is a notable gap.

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

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

The description is two short sentences with no filler. It front-loads the action and then provides a practical use case. Every word earns its place, so a 5 is appropriate.

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 low complexity, complete schema coverage, annotations, and presence of an output schema, the description is nearly sufficient. The main missing element is explicit behavior regarding existing tags (additive vs. overwrite), but the combination of structured data and description is fairly complete. A 4 reflects this 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%, and the schema already describes both tagId and accountIds clearly. The description adds little beyond 'one or more tags' and 'member/account' (which is also in the schema), so the baseline score of 3 is warranted.

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 ('Attach one or more tags') and the resource ('member/account'), distinguishing it from sibling tools like detach_tags. The phrase 'Useful for segmenting members after filtering' adds purpose context without 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?

It provides a clear usage context ('after filtering') that helps an agent know when to use it, but it does not explicitly mention alternatives or when not to use it (e.g., detach_tags for removal). This is clear context without exclusions, so a 4 is appropriate.

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, so the destructive nature is known. However, the description adds no further behavioral context beyond the annotation, such as irreversibility, side effects on related resources, or confirmation requirements. It adds zero value beyond structured data.

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 wasted words. It is front-loaded with the action and immediately conveys the core purpose. 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?

The tool is simple with full schema coverage, an output schema, and clear annotations. The description is minimally adequate but lacks usage guidance and any extra behavioral context. Given the availability of structured fields, a score of 3 reflects that it is sufficient but not rich.

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 both bookingId and reason having descriptions. The description's note 'Optionally provide a reason' merely reiterates the schema's optional flag, adding no new semantic meaning. 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 clearly states the action: 'Cancel a booking.' This is a specific verb and resource, and it distinguishes the tool from sibling tools like confirm_booking, complete_booking, and mark_no_show. The purpose is immediately clear.

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

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

The description provides no guidance on when to use this tool versus alternatives such as mark_no_show or update_booking_settings. It only states what the tool does, without any context for selecting it. This is a missing opportunity for decision support.

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

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

Annotations already flag destructiveHint=true, so the description's 'Destructive' label is redundant, but it adds valuable context: what gets destroyed (auto-renew and future billing) and what persists (existing paid periods stay valid). This goes beyond the annotations and does not contradict them.

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

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

The description is compact: two sentences, front-loaded with the primary action, followed by key consequences. Every sentence adds value and there is no filler or restatement of the tool name.

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

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

For a simple single-parameter mutation with an output schema and annotations, the description covers the essential behavioral outcomes clearly. The only gap is the lack of explicit guidance on how this relates to pause_subscription, but overall it is sufficiently 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?

The input schema already fully documents the single parameter subscriptionId with 100% coverage. The description adds no additional parameter-level semantics, so it receives the baseline score for high 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 and resource: 'Cancel a subscription.' It adds specific behavioral details (turns off auto-renew, prevents further billing cycles) that clarify the operation. However, it does not explicitly distinguish itself from the sibling tool pause_subscription, so it falls short of a 5.

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

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

The description implies when to use this tool by emphasizing its destructive, terminal nature ('prevents further billing cycles'), which helps differentiate from a pause. However, it does not explicitly state when not to use it or name alternatives such as pause_subscription, leaving the when-to-use guidance implicit.

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 behavioral context beyond the readonly/idempotent annotations by specifying what is checked: token scopes, enabled modules, subscription state, and quota. This clarifies the scope of the preflight without contradicting the annotations. It stops short of noting that no operation is actually executed, but 'preflight' conveys this.

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, well-structured sentence that front-loads the purpose ('Preflight whether an intended operation is allowed') and then lists the check dimensions and parameter options. Every word contributes meaning, with no redundant or filler content.

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

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

With an output schema present and annotations providing safety signals, the description is sufficiently complete. It covers the tool's purpose, the specific constraints checked, and how to invoke it with the relevant parameters. No significant gap remains for a preflight check 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?

The input schema already covers all four parameters with descriptions, so the baseline is 3. The description adds valuable guidance by instructing the caller to provide toolName, quotaCode, or moduleCode, which clarifies that these are the primary selection keys and implies at least one should be supplied. This improves the parameter semantics beyond the schema alone.

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

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

The description begins with the specific verb 'Preflight' and clearly identifies the resource being checked: whether an intended operation is allowed by token scopes, enabled modules, subscription state, and quota. This distinguishes it from sibling tools like execute_tool or get_plan_status by focusing on permission/eligibility checking rather than execution or plan status retrieval.

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 'Preflight whether an intended operation is allowed' clearly implies use before invoking an operation, providing clear context. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the highest tier.

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 it's a non-read-only, non-destructive, non-idempotent operation. The description adds meaningful behavior beyond that: the resulting copy is in DRAFT status and the name gets '(Copy)' appended. It does not explain all side effects (e.g., what data is copied), but the core behavior is well disclosed.

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

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

Two sentences, front-loaded with the primary action and followed by essential detail. Every word earns its place; no filler or repetition of schema 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 tool's moderate complexity (3 parameters, output schema present), the description covers the key behavior and output characteristics. It doesn't mention potential limitations or when to prefer create, but the combination of description, annotations, and schema is sufficient 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 description coverage is 100% with clear descriptions for name, entityId, and entityType (including enum values). The description reinforces the name default ('Original Name (Copy)') but adds no new parameter-level information 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 verb 'Duplicate' with the resource 'existing record' and enumerates the specific entity types (product, tier, campaign, etc.), distinguishing it from create/update siblings. It also specifies the resulting DRAFT status and naming convention.

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 its use case as a copy operation, clearly distinguishing it from create_* tools that start fresh. It does not explicitly mention alternatives or exclusions, but the 'Duplicate' verb and entity list provide clear context for 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 indicate non-read-only and non-destructive, but the description adds specific mutational effects: 'Creates/updates accounts and applies points, stamps, and credit deltas.' This gives concrete behavior beyond the annotations, though it does not elaborate on idempotency or failure scenarios.

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

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

The description is two sentences long and front-loads the core action ('Commit a previewed customer import') followed by essential usage and effect details. Every word 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?

For a complex two-phase operation, the description covers the workflow (preview → commit), the required data provenance, and the high-level effects. It does not explain output schema or error handling, but those are not strictly necessary given the structured schema and the tool's focused scope.

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 50% with many fields lacking descriptions. The description compensates by clarifying the critical relationship: the rows and sessionId must come from preview_customer_import. This adds semantic meaning that is not fully present in the schema, especially for the rows array.

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: 'Commit a previewed customer import' and specifies the exact side effects: 'Creates/updates accounts and applies points, stamps, and credit deltas.' It distinguishes itself from the sibling tool preview_customer_import by referencing it explicitly as the source of the data.

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 a clear prerequisite: 'Pass the same rows and sessionId returned by preview_customer_import.' This tells the agent when this tool is appropriate (after a preview) and what to pass. It does not explicitly list exclusions or alternative tools, but the context is strong 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 indicate a non-readonly mutate operation. The description adds valuable behavioral context beyond annotations: 'Triggers commission calculation if configured' and clarifies the state change to completed. This is useful for an agent deciding to invoke the tool.

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

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

Two concise sentences, front-loaded with the primary action, followed by a relevant side effect. No wasted words.

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

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

For a simple single-parameter mutation tool with an output schema, the description fully covers the action, side effects, and required parameter context. Complete and 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 coverage is 100% (bookingId has a description). The description does not add extra parameter semantics, but the schema already documents the only parameter. Baseline 3 is appropriate since the description adds no incremental value 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 ('Mark a booking as completed') with a specific verb and resource. It distinguishes from sibling tools like cancel_booking and confirm_booking by indicating the completed state.

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 appropriate usage context (when a booking should be marked completed) and notes the side effect of commission calculation. It does not explicitly mention alternatives or exclusions, but the context 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?

The description adds minimal context beyond the annotations: it implies a state change from pending to confirmed. However, it does not disclose side effects, permissions, or reversibility. With readOnlyHint=false already indicating a write operation, the description provides only a slight additional context about the pending-state constraint.

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 is front-loaded with the action. It contains no unnecessary words or information, making it highly efficient.

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 simplicity (one parameter, output schema present), the description is adequate but lacks usage context and behavioral details. The lack of guidance on when to use confirm versus other booking operations leaves a gap in completeness.

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% for the single bookingId parameter, so the schema fully documents the parameter. The description adds no extra semantic information about the parameter beyond what the schema already provides.

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

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

The description clearly states the action ('Confirm') and the resource ('a pending booking'), using a specific verb and object. It distinguishes from sibling tools like cancel_booking or complete_booking by specifying the 'pending' state, making the purpose 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 is provided on when to use this tool versus alternatives, prerequisites, or conditions. The description simply states what it does without any context on when it should be invoked.

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 behavioral context beyond annotations by explaining the conversion action and the optional linked deal creation. It does not detail side effects like whether the lead is removed, but given the annotations (readOnly=false, destructive=false) and the concise description, it provides reasonable 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?

The description is a single, concise sentence that front-loads the core purpose and includes an optional behavior. Every word 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 7 parameters and an output schema, so the description need not explain return values. The description is sufficient to understand the primary purpose and the optional deal creation, while the schema covers details. It could be slightly more explicit about the lifecycle of the original lead, but overall it is complete enough.

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 7 parameters are documented in the schema with descriptions, achieving 100% coverage. The description adds value by mentioning the 'linked pipeline deal' concept, which clarifies the relationship between the deal-related parameters and the core conversion action.

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 a specific verb and resource: 'Convert a lead account to an active customer.' It also mentions the optional creation of a linked pipeline deal, which distinguishes it from sibling tools like create_deal or update_account.

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 a clear usage context: converting a lead into a customer with optional deal creation. It does not explicitly compare to alternatives or state when not to use, but the context is evident from the description and tool name.

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 this is a write operation (readOnlyHint=false). The description adds context by noting that a primary contact is created and that membership enrollment is optional and can be deferred, which is not fully encoded in the schema. It does not disclose side effects like duplicate handling, but for a create tool this is sufficient.

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

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

The description is two sentences, front-loaded with the action, and contains no superfluous detail. Every word contributes to conveying the primary purpose and the key alternative. This is a model of conciseness.

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

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

Given the output schema exists and the input schema is fully described, the description is adequate. It covers the core action and the enrollment deferral. It could mention when to use `create_contact` for standalone contacts, but for a create tool with rich schema, this 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 the baseline is 3. The description adds value by linking contact-related parameters (name, email, phone) to the notion of a 'primary contact', and clarifies that enrollment is optional. This provides interpretive guidance beyond the standalone 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 clearly states the tool creates a CRM account/customer, with the specific verb 'Create' and the resource 'account/customer'. It also mentions the primary contact feature, distinguishing it from generic contact creation. This is unambiguous and action-oriented.

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

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

The description explicitly directs the user to use `enrol_membership` when the account already exists, providing a clear when-not to use this tool for membership enrollment. This gives an actionable alternative, satisfying the 'explicit when/when-not/alternatives' criterion.

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 readOnlyHint=false, so the write nature is known. The description adds the workflow context but doesn't disclose potential failure modes (e.g., what if slot is unavailable) or side effects beyond creation. This is implied but not 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?

Two succinct sentences: first states the purpose, second gives a clear workflow. No redundant information, effectively front-loaded.

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

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

With a comprehensive schema (8 params, 5 required) and an output schema present, the description covers the essential workflow and needed fields. It doesn't mention optional params like staffId/resourceId, but those are well-documented in the schema, so completeness is good.

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 fully documented. The description paraphrases service, member, date, and time, but adds no additional semantic meaning beyond what the schema already 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 clearly states 'Create a new booking for a member' with a specific verb and resource, distinguishing it from the many create_* siblings. It also references the workflow with get_available_slots, making the purpose unambiguous.

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

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

The description explicitly instructs to 'Use get_available_slots first to find valid times' before creating the booking, providing clear context on when to use this tool. It doesn't mention exclusions, but the prerequisite workflow is well-stated.

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

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

Annotations only indicate readOnlyHint=false (a write operation), so the description carries the burden of disclosing behavioral traits. It explicitly states the broadcast is NOT sent and requires admin review, which is key behavioral context beyond the annotations. It doesn't mention other side effects like idempotency, but the draft nature is well disclosed.

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 concise sentences, front-loaded with the core purpose and then the critical caveat. Every word earns its place; there is no redundant or filler content.

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

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

Given the tool has an output schema, return values don't need explanation. The description covers the essential context: it creates a draft, not sent, admin review required. It could add a note about how scheduledAt behaves with drafts (e.g., scheduled after approval), but the current description is complete enough for most use 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 description coverage is 100%, so parameters are already well-documented (e.g., channel enum, scheduledAt ISO date, recipientFilter object). The description adds only the draft-related context that affects how the created broadcast behaves, but it doesn't provide additional parameter-level details beyond the schema. 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: 'Create a DRAFT WhatsApp or SMS broadcast campaign.' It clearly distinguishes this from other create_* tools by emphasizing the draft status and the need for admin review, avoiding confusion with create_campaign or other send-related 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 description clearly implies when to use this tool: when you need to create a broadcast that won't go out immediately but requires admin approval. It doesn't explicitly name alternatives, but the context of the broadcast not being sent and the existence of validate_campaign and request_send_approval siblings gives enough context. No explicit exclusions are provided, so it falls short of a 5.

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

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

Annotations are present but minimal (readOnly false, destructive false), so the description adds value by noting that campaigns are created in DRAFT by default and that recipientSource='list' is normalized to 'individual'. These are meaningful behavioral traits not disclosed 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 two sentences, front-loaded with the primary action, and contains no redundant filler. Every sentence adds either scope clarification or config guidance.

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 8 parameters, nested channelConfig, and an output schema, the description covers key behavior: supported channels, default status, and alias handling. It does not explicitly mention scheduling or segment/recipient options, but the schema documents those thoroughly, making the description adequate.

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 parameters (100%), giving a baseline of 3. The description adds specific guidance for email channelConfig ('subject + htmlBody + optional plainTextBody') and reiterates the alias behavior, which is slightly more detailed than the schema's existing description of 'normalized to individual'.

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 'Create a marketing campaign (email, SMS, or WhatsApp) in DRAFT.' This clearly identifies the verb ('Create'), resource ('marketing campaign'), and scope (supported channels and default status). It distinguishes the tool from siblings like create_broadcast and create_template by specifying campaign creation.

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 usage details for email channelConfig and clarifies the recipientSource alias, but does not explicitly state when to use this tool versus alternatives like create_broadcast or update_campaign. The usage context is implied rather than directly contrasted with sibling 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?

Annotations already declare readOnlyHint=false, so 'create' is consistent. The description adds the flat-table behavior and namespacing requirement, which is useful beyond annotations. However, it does not disclose potential duplicate handling, permissions, or confirmation behavior; output schema likely covers return details but is not visible here. With annotations present, this is adequate but not rich.

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

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

Two sentences, front-loaded with the action and resource, and every clause adds value: the examples clarify usage, and the flat-table constraint prevents misuse. No filler or irrelevant 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 simple create operation with 4 parameters, an output schema, and annotations, the description covers the essential context: what is created, examples, and a key sub-category caveat. It does not explain return values, but the output schema presumably covers that. A minor gap is lack of explicit alternative guidance, but that is handled in usage_guidelines. Overall, sufficiently complete for the tool's complexity.

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 adds contextual meaning for the name parameter (sub-category namespacing) and gives examples, but it does not add details for slug, sortOrder, or description beyond what the schema already provides. Thus it meets the baseline without exceeding 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 states a specific verb and resource: 'Create a CMS post category' with concrete examples ('Equipment', 'Injection — Botox'). This clearly distinguishes it from sibling tools like create_product_category and create_service_category by specifying 'CMS post category'.

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 usage context: it is for CMS post categories, and it explicitly instructs on sub-category handling via namespaced names because 'the table is flat.' While it doesn't explicitly name alternatives or exclusions, the scope is well implied and the sub-category guidance is 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?

Annotations already signal readOnlyHint=false and destructiveHint=false, indicating a non-read-only, non-destructive write operation. The description adds the constraint that the account must already exist, which is useful behavioral context. It does not elaborate on idempotency or side effects, but annotations cover the safety profile adequately.

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 sentence of nine words, concise and front-loaded with the action. It contains no redundancy or extraneous information, earning full marks for conciseness.

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

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

The tool is a straightforward create operation with six parameters, an output schema, and good annotation coverage. The description is sufficient for an agent to understand the core operation, though it does not mention the special 'isPrimary' parameter or clarify how primary contacts are handled. Given the simplicity, the description is adequately complete without needing extensive detail.

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 covers all six parameters with descriptions at 100% coverage. The description adds no additional parameter-level detail, so it does not improve upon the schema. Baseline 3 is appropriate given the schema already provides full 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?

The description uses the specific verb 'Create' with the resource 'contact' and specifies the context 'on an existing CRM account,' clearly distinguishing this from sibling tools like create_account or create_deal. It implies a prerequisite (existing account) and 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?

The description states the tool creates a contact on an existing account, implying the need for an existing accountId. However, it does not provide explicit guidance on when to choose this over alternatives like create_lead or update_contact, nor does it mention any exclusions or prerequisites beyond 'existing CRM account.'

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 readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description adds minimal behavioral context beyond what annotations provide, only noting that options apply to select/multiselect types. It does not disclose side effects such as permanent creation, uniqueness constraints, or any conditional requirements, so the description adds limited value.

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, front-loaded with the main purpose and a helpful parameter hint. Every word earns its place, with 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?

The tool has 7 parameters (4 required) and an output schema, but the description doesn't mention uniqueness restrictions on fieldName, whether options are required for select/multiselect types, or what happens on duplicates. It provides the core purpose but leaves these contextual gaps that a user would need to infer or discover elsewhere.

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 each parameter already described. The description's note 'Use options for select or multiselect fields' reinforces the schema's description for options but doesn't add new meaning. Since the schema already documents everything, the baseline of 3 is appropriate; the description adds little 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 verb 'Create' and the resource 'custom field definition for CRM entities', which is specific and unambiguous. It differentiates from sibling tools like update_custom_field and delete_custom_field by the verb, but doesn't explicitly name alternatives or contrast with them. The additional note about options for select/multiselect adds clarity but isn't strictly needed for 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?

The description provides no explicit guidance on when to use this tool vs alternatives (e.g., update_custom_field). It implies usage for creating a new field, but doesn't state prerequisites, exclusions, or when another tool would be more appropriate. The only hint is 'Use options for select or multiselect fields', which is more about parameter usage than tool selection.

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

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

Annotations already convey that this is not read-only and not destructive; the description adds little beyond that. It mentions optional linking but does not disclose permission requirements, side effects, or default behaviors, leaving gaps in 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?

A single sentence that is front-loaded with the action and object, and contains no unnecessary words. It is direct and efficient.

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 very brief for a tool with 10 parameters, although an output schema exists. It does not mention prerequisites, default stages, or constraints, so it is adequate but not fully complete for complex scenarios.

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?

Since schema description coverage is 100%, the schema already documents all parameters clearly. The description's mention of optional linking adds slight context but does not meaningfully extend parameter semantics beyond what is already available.

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 a specific verb ('create') and resource ('CRM sales pipeline deal'), and adds optional linking to customer account and contact, which distinguishes it from siblings like update_deal and delete_deal.

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 use for creating a new deal but does not explicitly mention alternatives or when not to use it. Without guidance on when to prefer this over related tools, the usage context is inferred but not stated.

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

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

Beyond annotations, the description discloses that the draft appears inline in the composer and that no customer communication occurs. Annotations already cover read-only/destructive hints, so the added context of non-sending is valuable but not exhaustive.

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, front-loaded sentences. Every clause earns its place: the action, the location, the trigger condition, and the critical exclusion of sending.

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 presence of a complete schema and output schema, the description sufficiently covers purpose, trigger, and key behavioral boundary. No critical context is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter-level meaning beyond what the schema already provides, but the schema fully documents each field.

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: 'Create a draft reply suggestion that appears inline in the FavCRM Inbox composer.' It clearly distinguishes from sibling tools by noting it does not send anything to the customer.

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

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

Explicitly states when to use: 'Use this for message.inbound events with replyPolicy="suggest"'. Also provides a clear exclusion—'it does not send anything to the customer'—which guides the agent away from using it for sending.

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 this is a non-read-only, non-idempotent operation. The description adds that it returns the new invoiceId and that line items are optional, which is useful. It does not detail side effects or error conditions, but for a create operation the behavior is largely captured.

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

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

The description is two sentences, immediately states the primary action, and includes the return value. No fluff 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, combined with the complete schema and annotations, covers the essential aspects for a create invoice tool. It mentions the key return value and optional line items. It lacks some nuance (e.g., server-side total calculation is only in schema), but overall it is adequate.

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 well documented. The description adds minimal param semantics ('Optionally include line items inline'), which reinforces the schema. It does not go beyond the schema in explaining formats or defaults.

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 'Create a new invoice for a customer' with a specific verb and resource. It distinguishes from sibling invoice tools (e.g., get_invoice, void_invoice) by explicitly naming the creation action and mentioning returning the invoiceId.

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 clear context on what the tool does and notes that line items are optional ('Optionally include line items inline'). However, it does not explicitly exclude alternative tools, but there are no other tools that create invoices, so the usage is unambiguous.

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 this is a write operation (readOnlyHint=false) and not destructive. The description adds the target entity types but does not disclose any additional behavioral traits such as whether the note is appended, returns an ID, or triggers side effects. It matches the annotations, so no contradiction, but adds minimal behavioral insight.

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, front-loaded with the verb, and contains no filler words. It efficiently communicates the action and target entities.

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 nature of the tool, the description is nearly complete, but the 'member/account' vs. 'account' mismatch is a clear gap. It does not provide usage context or highlight the isPinned option, though the schema covers parameter details. The output schema exists, so return values are not needed.

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 100% of parameters, so the baseline is 3. However, the description introduces 'member/account' while the entityType enum only includes 'account', 'booking', 'ticket', and 'invoice'. This discrepancy could mislead an agent into using an invalid entityType 'member'. The description adds no value beyond the schema and actually introduces confusion.

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 'Add' and identifies the resource ('a note') and the target entities (member/account, booking, ticket, or invoice). This clearly distinguishes it from sibling tools like create_post or create_task, which have different purposes. The scope is immediately understandable.

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 when to use the tool: whenever a note needs to be added to one of the listed entity types. However, there is no explicit when-to-use/not-to-use guidance or mention of alternatives, which would be helpful for less obvious cases. The lack of exclusions or context beyond the target list leaves some ambiguity.

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 indicate this is a write operation (readOnlyHint false), and the description adds the crucial context that the rule is created as a draft, implying it won't be active immediately. This goes beyond the annotations by disclosing the draft state, though it doesn't mention permissions or a publish step.

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

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

The description is two sentences, front-loading the primary action and key details. Every word adds value: it names the resource, the draft state, and the main configurable aspects. No fluff 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 tool has 6 parameters, nested objects, and enums, but the schema is comprehensive (100% coverage) and an output schema exists. The description covers the main aspects (trigger type, products, discounts) and relevant context ('as draft'), though it doesn't explicitly mention the 'description' parameter or the triggerConfig structure. Overall sufficient given the schema richness.

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 each parameter is already documented in the input schema. The description provides only a high-level summary (trigger type, conditions, products with discounts) that maps loosely to triggerConfig and products, without adding new semantic detail beyond what the schema already offers.

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 ('Create'), the resource ('offer rule'), and a key detail ('as draft'), which distinguishes it from related tools like list_offer_rules and get_offer_rule. It also specifies the domain (upsell/cross-sell), making it unambiguous.

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

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

The description implies when to use this tool (when creating a draft offer rule) but does not explicitly state alternatives or exclusion criteria. The sibling tools include list_offer_rules and get_offer_rule, but no direct guidance is provided for choosing between create and other operations.

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 readOnlyHint=false properly align with 'Create' as a write operation, with no contradiction. The description adds useful context about preserving a legacy UUID during migration, but does not disclose other behavioral aspects like duplicate handling or error cases. Since idempotentHint=false and an output schema exist, the description need not cover everything.

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

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

Two short sentences, with the primary action front-loaded and the optional id behavior clarified in the second. Every word contributes, with no fluff 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 full input schema, output schema, and annotations, the description is complete enough for an agent to select and invoke the tool. The migration note covers the one non-obvious option, while the structured metadata handles parameter details and return values.

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

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

The input schema has 100% coverage with descriptions for all 10 parameters, so the description carries little burden here. The note about preserving a legacy UUID adds some meaning for the id parameter, but the schema already mentions legacy migration and non-standard formats, so added value is minimal.

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 opens with 'Create a shop outlet/location', using a specific verb and resource. This clearly distinguishes it from sibling tools like update_outlet and list_outlets, as well as other create_* tools.

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

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

It explicitly states when to pass the optional id: 'during migration' to preserve a legacy UUID. This gives clear context, though it does not mention alternatives or exclusions. Given there is no close sibling, this is sufficient 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 description adds behavioral context beyond the annotations by explaining the dual behavior (checkout vs portal) and the user-consent requirement. Annotations already indicate it's a write operation (readOnlyHint=false) and not destructive, which is consistent. However, it does not disclose side effects like whether it charges the user or sends email, though the schema mentions the confirm parameter, so partial coverage exists.

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 concise sentences that front-load the main action and the usage condition. It contains no unnecessary filler or repetition, making it highly efficient and well-structured.

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 moderate complexity (5 parameters, 0 required, output schema present), the description combined with the detailed schema and annotations is sufficient for an agent to understand when and how to invoke it. It clarifies the two use cases, the consent requirement, and the type of link generated. The output schema likely covers return values, so the description doesn't need to.

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

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

With 80% schema description coverage, the baseline is 3. The schema already provides detailed descriptions for parameters like planId, confirm, planCode, returnUrl, and billingCycle, including important notes like 'Either planId or planCode is required' and 'confirm required true'. The description itself does not add parameter-level meaning beyond what the schema offers, so it stays at the 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 clearly states the tool creates a Stripe Checkout link for new paid subscriptions or a Stripe Billing Portal link for existing subscriptions. It uses a specific verb ('Create') and identifies the exact resources, making it easy to understand what the tool does. It also distinguishes this from sibling tools by specifying the two use cases.

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

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

The description explicitly says 'Use only after the user explicitly asks to upgrade or fix billing,' providing a clear when-to-use condition. It also distinguishes between the two scenarios (new subscription vs existing subscription), which helps the agent choose the correct behavior. This is strong, explicit usage guidance even without naming alternatives.

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

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

Annotations already mark this as a write operation (readOnlyHint=false). The description adds valuable behavioral context: excerpt is plain-text-only and auto-derived if omitted, and structured fields must go in meta rather than excerpt — details not present in annotations. It doesn't cover return behavior, but an output schema exists to handle that.

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 sentences that lead with the core purpose, then add two crucial caveats. No wasted words, no repetition of schema field descriptions. The structure is front-loaded and focused.

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 16 parameters and a complex nested block schema, the description correctly highlights the key preconditions and pitfalls without drowning in detail. It references sibling tools needed for setup, and the output schema handles return values, so the description is complete 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 description coverage is 100%, so the schema fully documents all 16 parameters. The description reinforces a couple of key constraints (excerpt plain-text, meta for structured fields) that are already in the schema, but adds no new semantic meaning 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 opens with 'Create a new CMS post (blog_post, page, or any custom post type),' clearly stating the action and resource. It differentiates from sibling tools like update_post, delete_post, and list_posts by focusing on creation, and references related setup tools to avoid confusion.

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

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

Explicitly states the prerequisite that the post type must already exist, and names list_post_types and create_post_type as the tools to discover or add post types. It also directs custom field schema definition to create_post_type_field, giving clear when-to-use and alternative 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 description adds useful behavioral context beyond annotations: it explains that fields are stored in meta on each post and advises against using excerpt for structured data. While it doesn't detail return values or side effects of creation, the annotations already indicate this is a non-readonly, non-destructive write operation.

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

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

Three sentences, front-loaded with the core purpose, then essential workflow guidance and a caveat. Every sentence adds value and there is no repetition of schema or annotation 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 provides the complete context needed: what the tool does, when to use it, how it relates to other tools, and a key data-storage implication. The output schema exists to explain return values, so no further detail is required. This is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already covers all 10 parameters with detailed descriptions and defaults, so the description doesn't need to add parameter-specific semantics. It provides only broad examples ('slug', 'label'), and the schema carries the full burden for parameter understanding.

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 specific action ('Define a new custom post type') with concrete examples ('treatment', 'service'), and clearly distinguishes this tool from siblings like create_post and create_post_type_field. It names the resource and what the tool does unambiguously.

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

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

Explicitly explains when this tool must be used ('Required before creating posts of that type') and directs the agent to the next step ('use create_post_type_field to define its structured field schema'). It also warns against using excerpt for structured data, providing clear guidance on proper usage.

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

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

Annotations indicate this is a write operation (readOnlyHint=false) but not destructive. The description adds beyond annotations by disclosing that 'The field key becomes the key in meta when creating/updating posts' and providing special repeater behavior. This gives an agent useful behavioral context about side effects and the role of the key parameter, which annotations alone don't 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 two sentences, front-loaded with the core purpose, and every sentence adds value: the first states the action, the second clarifies the key/meta relationship and gives usage guidance for repeaters. No wasted words.

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

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

The tool is complex with 9 parameters and nested objects, but the description captures the essential usage context (repeater fields, meta key, avoiding excerpt storage). The rich input schema and output schema carry the detailed field options and return format. The description is sufficient for an agent to decide when and how to invoke it, though it could briefly mention that it's for post type fields specifically (already clear from the name) or provide a general tip about field types.

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 small amount of parameter context by explaining the repeater usage ('fieldType="repeater" with fields=[...]') and the meta-key behavior, but the schema already describes these parameters in detail (e.g., the 'fields' parameter description is extensive). The description doesn't compensate for any parameter ambiguity beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Add a custom field to a post type schema.' This is a specific verb+resource that distinguishes it from sibling tools like create_post_type (which creates the post type itself) and update_post_type_field (which modifies an existing field). It also includes the concrete consequence that the field key becomes the meta key, adding further clarity.

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 explicit usage context by saying 'Use fieldType="repeater" with fields=[...] for repeatable structured rows' and 'Use this instead of storing structured data in excerpt.' This gives a clear alternative and a specific scenario, though it doesn't enumerate all cases when not to use the tool or name sibling tools explicitly.

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 this is not a read-only or destructive operation. The description adds valuable behavioral context beyond the annotations: the product is created in DRAFT state and requires merchant activation. This discloses that the product will not be immediately active/advertised, which is critical for agent understanding.

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, compact sentence of 14 words that states the core purpose and the key behavioral nuance (DRAFT + merchant activation). It is front-loaded with the action 'Create' and contains zero redundant or filler content. Every word contributes valuable 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 that an output schema exists (so return value details are not required in the description), the tool is a create operation with full schema documentation and safety annotations. The description covers the essential purpose and the draft/activation workflow. It is sufficiently complete, though it could optionally mention prerequisites (e.g., existence of categories) but such details are handled by the schema's optional fields.

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 all 8 parameters documented in the input schema (e.g., price as decimal string, productType enum). The description itself does not add any parameter-level meaning, leaving the schema to fully describe each field. Thus the baseline score 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 uses the specific verb 'Create' and clearly states the resource is 'a new shop product' with the important qualifier 'as DRAFT'. This distinguishes it from sibling tools like list_products, update_product, and create_product_category. It precisely conveys both the action and the resulting state.

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

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

The description gives clear context by stating the product is created as DRAFT and that the merchant reviews and activates it from the portal. This implies when to use this tool (initial creation) versus other tools like update_product for modifications. However, it does not explicitly name alternatives or specify when not to use it, so it lacks explicit exclusion 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 indicate a write operation (readOnlyHint=false). The description adds useful context about creating subcategories via parentId, which is not in annotations. However, it does not disclose permissions, idempotency, or failure 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?

Two concise, front-loaded sentences with no superfluous content. The primary action and key subcategory behavior are stated 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?

Given the simple create operation, full input schema, and presence of an output schema, the description is sufficient. It covers the purpose and the one non-obvious usage (subcategories), while the schema handles parameter details.

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

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

Schema coverage is 100% with all parameters already described. The description only reiterates parentId's role without adding format, constraints, or behavior 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 identifies the action (create) and resource (product category), and it adds a key distinguishing behavior (using parentId for subcategories). However, it does not explicitly differentiate from sibling tools like create_category or list_product_categories.

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 a clear usage instruction for parentId to create subcategories, implying the tool's context. But it does not state when to prefer this tool over alternatives or when not to use it, especially given overlapping siblings like create_category.

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 indicate it's a non-read, non-destructive, non-idempotent operation, so the bar for extra disclosure is lower. The description adds valuable behavioral details: codes are uppercased server-side and the value is a string interpreted differently for percentage vs fixed_amount. These are non-obvious, useful behaviors beyond what 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 two sentences: the first states the purpose, the second provides key parameter and server-side behavior. Every word earns its place, and the most important information is front-loaded. It is appropriately sized for a tool with rich schema coverage.

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

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

With 17 parameters and an output schema, the description doesn't need to enumerate every field. It covers the critical cross-parameter semantics (type/value) and server-side uppercase behavior, which are not apparent from the schema or annotations. Optional fields like posEnabled are already self-descriptive in the schema, making the description sufficiently complete 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?

Input schema already covers all 17 parameters with descriptions (100% coverage), so the baseline is 3. The description adds semantic meaning for type and value, clarifying the relationship between them and explaining the string-based value format ('10' = 10% or 10 currency units). This reduces ambiguity that the schema alone leaves unresolved.

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 a promotion / discount code,' which uses a specific verb and resource. It clearly distinguishes from related tools like update_promotion, list_promotions, and delete_promotion by focusing on creation. The purpose is unambiguous and actionable.

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 clear context: this tool is for creating promotions and discount codes. It doesn't explicitly mention when not to use it or point to alternatives, but the context is sufficiently clear for an agent to infer when to invoke it. No exclusions are given, which aligns with a score of 4.

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 convey that this is a mutating operation (readOnlyHint=false, destructiveHint=false). The description adds useful context about it being 'bookable' and the requiresResource linkage, but does not disclose additional behavioral details like uniqueness constraints or side effects.

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, each earning its place. The first states core purpose, the second provides usage context. No wasted words 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 straightforward create operation with a fully documented schema, output schema, and annotations, the description is sufficient. It clearly explains what the resource is and when to use it, with no critical 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?

Schema description coverage is 100%, so the schema fully documents every parameter. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score 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?

Description uses specific verb 'Create' with clear object 'bookable resource' and gives examples (room, equipment, vehicle), distinguishing it from sibling tools like create_service or create_booking. The purpose 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?

The description provides clear context: 'Used by services that have requiresResource=true.' This tells the agent when to use the tool, though it does not explicitly mention alternatives or exclusions.

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

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

Annotations already indicate this is a mutation (readOnlyHint false), and the description adds the static/dynamic distinction. It doesn't disclose downstream requirements like populating static segment members via set_segment_members, but the description adds moderate value beyond 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 concise sentences. The first states the action, the second explains the key type decision. No wasted words or filler content.

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

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

The output schema exists and annotations clarify it's a write operation. The description is minimal but the schema covers the complex criteria structure. It could mention that STATIC segments require later member assignment via set_segment_members, but this is not a critical omission for basic usage.

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 parameters are well-documented. The description adds meaning to segmentType by explaining that STATIC is for manual member lists and DYNAMIC is for criteria-based auto-filtering, which goes beyond the schema's simple enum label.

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 'Create a new customer segment' with a specific verb and resource. It also distinguishes the two segment types (STATIC vs DYNAMIC), which helps differentiate it from sibling segment-related tools like set_segment_members or preview_segment_count.

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 on when to use STATIC vs DYNAMIC segment types, which is useful for parameter selection. However, it does not explicitly contrast with alternatives like update_segment or set_segment_members, though the tool name and siblings make this somewhat implicit.

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 readOnlyHint=false, so it's a write operation. The description adds that it sets duration, price, capacity, and policies, giving some sense of what side effects occur. However, it doesn't describe any validation, immediate persistence, or permissions, though with annotations present, the bar is lower. This is average 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?

Two sentences, front-loaded with the action, and each sentence earns its place. The first states the purpose, the second gives a useful prerequisite tip. No fluff or repetition of schema details.

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

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

Given the tool's complexity (20 params, output schema exists), the description is minimal but sufficient for selection. The schema fully documents parameters, and the description adds a prerequisite hint. It doesn't explain all possible relationships (e.g., allowedTierIds dependency) but those are in the schema, so the context is adequately complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description groups parameters into 'duration, price, capacity, and policies' but doesn't add specific meaning beyond what each schema property already describes. It provides a high-level summary but no extra 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?

The description clearly states the tool's primary action: 'Create a bookable service.' It specifies key attributes it sets (duration, price, capacity, policies) and distinguishes it from related sibling tools like create_service_category or create_service_schedule by focusing on the service entity itself.

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

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

Provides explicit prerequisite usage: 'Use list_service_categories first if you want to attach to an existing category.' This gives clear context for when to call another tool. It doesn't discuss exclusions or alternative tools, but the prerequisite is valuable and the overall 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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is clear. The description adds the purpose of grouping bookable services but does not disclose additional behavior such as duplicate handling or effects on existing services. This is acceptable but not rich.

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

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

The description is a single, well-structured sentence that is front-loaded with the action, includes a clarifying example, and contains no wasted words.

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

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

For a simple create tool with an output schema and full parameter descriptions, the description is nearly complete. It provides purpose and examples, though a brief note on when not to use it (e.g., for non-service categories) would fully round it 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 description coverage is 100%, with each parameter (name, sortOrder, description) already documented. The description does not add parameter-specific meaning beyond the examples in the purpose, so it meets the baseline without exceeding 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 uses the specific verb 'Create' with the resource 'service category' and provides a clear purpose ('to group bookable services') with concrete examples. This distinguishes it from sibling tools like create_category and create_product_category.

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 when to use this tool: when creating a category to group bookable services. However, it does not explicitly mention alternatives or exclusions, though the context is distinctive enough to guide 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 only indicate readOnlyHint=false and destructiveHint=false, so the description must handle behavioral context. It does not mention permissions, whether the package becomes immediately active, or any side effects. The only added info is about parameter usage, not about the tool's behavior or 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?

Two sentences, no fluff. The first sentence defines the action and resource, the second delivers an essential usage nuance. It is front-loaded and efficient.

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 8 parameters and an output schema, the description defines the resource and covers the key conditional logic (applicableType/applicableItems). However, it does not mention preconditions, required permissions, or what happens after creation. Given the schema's richness and the presence of an output schema, it is reasonably complete but not exhaustive.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaningful semantics by explaining the relationship between applicableType and applicableItems: using SELECTED with specific items limits the package. This clarifies a parameter dependency that the schema only tersely states, going beyond the 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 states 'Create a service package/prepaid session bundle' with a specific verb and resource, clearly distinguishing it from sibling create_* tools like create_service or create_product. The phrase 'limit the package to specific booking services or events' further clarifies the 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?

The description gives a practical usage hint: 'Use applicableType=SELECTED with applicableItems to limit the package to specific booking services or events.' This tells the agent when to use these parameters, though it does not explicitly mention alternatives like update_service_package or delete_service_package. The guidance is useful but not comprehensive regarding tool selection.

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

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

The annotations already indicate a non-read-only, destructive-safe create operation. The description adds no context about side effects, such as whether existing schedules are overwritten, whether slots are generated immediately, or permission requirements. It only restates the purpose without disclosing additional behavioral traits.

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

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

A single, direct sentence with no extraneous words. It front-loads the core action and object, making the tool's purpose 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?

The tool has 12 parameters and an output schema, but the rich schema descriptions and annotations offset the brief description. The description lacks usage nuance about recurrence edge cases, but the schema addresses defaults and formats, making it adequate for a create 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 input schema provides complete descriptions for all 12 parameters (100% coverage), so the schema carries the semantic load. The description's mention of 'recurring weekly/daily availability' aligns with recurrence fields like recurrence, byWeekday, and recurrenceEndDate, but adds no detail beyond what the schema already documents.

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 action ('Create'), the target ('a bookable schedule window'), and the scope ('for a service'), distinguishing it from booking tools like create_booking and update operations like update_service_schedule. The phrase 'including recurring weekly/daily availability' adds specificity to the tool's recurring capability.

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 such as set_resource_availability or list_service_schedules. The description implies it is for creating service-level schedule windows but does not mention exclusions, prerequisites, or scenarios where another tool should be preferred.

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 little beyond annotations. While readOnlyHint=false signals a write operation, the description does not disclose important behavioral traits such as whether payment is charged, what happens to existing subscriptions, or any prerequisites. It merely restates the two creation modes without deeper side-effect context.

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

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

The description is two concise sentences, front-loaded with the primary purpose and no wasted words. It earns its place by conveying the essential decision between tier-based and custom subscriptions.

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 minimal but the rich schema covers all parameter details, and an output schema exists. However, it does not mention that accountId is required, and calling the tool 'recurring' while billingCycle includes 'one_off' could create ambiguity. Adequate when combined with structured data, but with noticeable 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?

Schema coverage is 100%, providing a baseline of 3. The description adds semantic value by explaining the relationship between tierId and amount/currency ('Bind to a membership tier or set a custom amount + cycle'), which is not fully explicit in the schema alone.

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

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

The description clearly states the tool creates a recurring subscription for a member, using a specific verb and resource. Among sibling tools like cancel_subscription, pause_subscription, and resume_subscription, this uniquely identifies the creation action, making it easy to distinguish.

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 on when to use the tool ('Create a recurring subscription for a member') and offers a key usage decision: 'Bind to a membership tier or set a custom amount + cycle.' It does not explicitly name alternatives or exclusions, but the tier-vs-custom guidance is sufficient for typical usage.

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

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

The annotations already indicate this is a write operation (readOnlyHint=false). The description adds behavioral context beyond annotations by explaining draft vs. published status and the consequence of 'immediate portal access' when published. It is consistent with the annotations and adds useful nuance.

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, immediately starts with the action and resource, and contains no filler. Every phrase contributes meaning, making it highly efficient.

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 has 9 parameters including nested objects (questionBlocks, settings) and there is an output schema, the description is brief. It covers creation and publishing but does not clarify the structure of the required questionBlocks array, leaving the agent to rely entirely on the schema and output schema for structural details.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description echoes some parameter meanings ('custom question blocks' for questionBlocks, 'set status to published' for status), but it does not add extra format or syntax details beyond what the schema already provides.

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

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

The description clearly states 'Create a survey' with a specific resource and adds scope via 'custom question blocks.' It also mentions the publish behavior, which provides useful context, but it does not explicitly differentiate from closely related siblings like update_survey.

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 when to use the tool (when creating a survey) and gives a functional hint about publishing ('Publish it later or set status to published'). However, it does not state when not to use it or name alternatives such as update_survey or create_survey_invitation.

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