HelpWell

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent. The description goes beyond them by describing the concrete effect (promotes the held note to the customer's message and reopens the conversation) and the admin-only restriction. It still doesn't say whether the action is reversible or whether the held note is removed, which matters for a destructive operation.

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

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

Three short sentences, front-loaded with the object being acted on and followed immediately by the effect and the permission gate. No filler.

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

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

With one parameter, full schema coverage, and no output schema, the description covers the essential context: what a held reply is, what accepting does, and who may do it. The only real gap is the absence of any statement about reversibility or the fate of the original note.

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

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

Schema description coverage is 100% and the single messageId parameter is already documented as coming from get_conversation. The description's mention of a reply 'held as a note' gives useful context about which id to pass but adds no format or sourcing detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (accept) and resource (held emailed reply) and explains the resulting state change: the note becomes the customer's message and the conversation reopens. It does not explicitly name the sibling dismiss_held_reply as the opposite action, so it stops short of full sibling differentiation.

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

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

Usage is implied by the setup sentence (a reply held because it failed sender checks), and 'Admins only' adds a permission prerequisite. However, it never states when not to use it or points to dismiss_held_reply as the alternative, leaving routing to inference.

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

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

Annotations already declare the write/non-destructive/non-idempotent profile, so the bar is lower. The description adds genuinely useful context beyond them: the call returns CNAME and TXT records the customer must place at their DNS provider, and verification is not part of this call.

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

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

Three short sentences, front-loaded with the action, then the return payload, then the workflow boundary. Every sentence conveys information an agent needs; nothing is padding.

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

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

With no output schema, the description correctly carries the return-value burden by naming the CNAME/TXT records. For a two-parameter additive tool with full schema coverage and annotations, this is nearly complete, though it does not say what happens if the domain is already connected.

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

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

Schema description coverage is 100%, so both parameters are already documented (including the help.acme.com example, which the description merely repeats). The description adds no format, constraint, or hostname-validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (connect) and resource (a customer domain to a hosted product's help center), with a concrete example (help.acme.com). It implicitly distinguishes itself from the similar-sounding add_mail_domain/add_redirect siblings by scoping to the help center.

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 final sentence 'DNS verification is a separate action' tells the agent this tool does not complete the workflow and routes the verification step elsewhere. It does not explicitly name check_help_center_domain or state when not to use it versus add_mail_domain, so it stops short of full 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?

With annotations already declaring non-readOnly, non-destructive, non-idempotent and closed-world, the description adds real context beyond them: it discloses the return payload (DNS records, valuable since there is no output schema), that verification is deferred to a separate action, and that an existing domain is reused. It does not mention auth/connection requirements or what happens to an existing domain's purpose configuration.

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

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

Three short sentences, front-loaded with the action and scope, followed by the return value and the verification caveat. No filler or repetition.

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

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

For a 4-parameter mutation with no output schema, the description covers the essential gaps: what is created, that DNS records come back, and that verification is out of scope. It is only marginally short on failure/precondition behavior and how it differs from register/reuse siblings.

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% — name examples, region enum with default, purposes enum with per-value meanings and tracking default are all documented in the schema. The description only restates 'one domain' and 'the chosen purposes', adding no syntax or constraint detail beyond the schema.

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

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

Clear specific verb+resource: adds one domain to the workspace's Resend account for chosen purposes. It does not explicitly distinguish itself from close siblings like register_mail_domain or reuse_resend_domain, which handle the same resource — the phrase 'or reuse it if it is there' actually blurs the boundary with reuse_resend_domain rather than clarifying it.

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

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

It gives one useful routing cue — 'Domain verification is a separate action' — steering the agent toward verify_mail_domain afterward. But it offers no guidance on when to prefer this over register_mail_domain or reuse_resend_domain, and no prerequisites (e.g., Resend connection required) are stated.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent). The description adds genuinely useful audience context ('the customer never sees it'), but it says nothing about the idempotency behavior that the schema only hints at via requestId, nor about permissions or notification side effects beyond mentions.

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

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

Three short sentences, front-loaded with the core action and scope. The visibility sentence earns its place; the mentions sentence is slightly redundant against the schema but still brief and on-point.

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, well-documented four-parameter mutation with clear annotations and no output schema, the description covers what and audience. It is close to complete; only the when-to-use routing against reply_to_conversation and save_reply_draft is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the requestId repeat-safety semantics. The description's mention guidance ('Mention teammates by user id to notify them') largely restates the existing mentions parameter description, adding no new syntax or format 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?

States a specific verb and resource ('Add an internal note to a conversation') and distinguishes itself from the reply-family siblings by making clear the customer never sees it. It never names a sibling like reply_to_conversation or save_reply_draft explicitly, so the differentiation is implicit rather than stated.

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

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

Usage is only implied: an agent can infer 'use this when you want an internal-only annotation rather than a customer-facing reply.' There is no when-to-use statement, no exclusions, and no named alternative among the many conversation-related siblings.

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

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

The annotations already declare this is a write operation that is non-destructive, non-idempotent, and closed-world. The description adds one meaningful behavioral detail beyond annotations: the admin-only authorization requirement. It does not address the implications of non-idempotency (e.g., creating duplicate rules) or describe the response.

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

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

A single, front-loaded sentence with zero waste. It defines the resource, explains the domain term 'playbook', and states the key access constraint all in one pass.

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 two-parameter write tool with full schema coverage and annotations covering the safety profile, the description supplies enough context to call it correctly: purpose, admin restriction, and playbook definition. The main remaining gap is that it does not route the agent to 'update_playbook_rule' when modifying an existing rule.

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

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

Schema description coverage is 100%, so both parameters are already well documented by the schema. The description adds no additional syntax, format, or constraint details for 'productId' or 'content' beyond what the schema provides.

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

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

The description states a specific verb ('Add') and resource ('rule to a product's playbook') and even defines what a playbook is. It does not explicitly name the sibling 'update_playbook_rule' or otherwise differentiate itself from it, so it falls short of the top score.

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

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

It gives a prerequisite ('Admins only') but does not say when to use this tool versus alternatives such as update_playbook_rule, nor does it provide any when-not-to-use guidance. Usage is implied by the tool name and purpose, not explicitly guided.

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, idempotentHint=true, and destructiveHint=false; the description usefully adds the upsert semantics ('a new rule for an address already mapped replaces it'), which explains the practical consequence of an overlapping write. It does not mention permissions or validation failures, but the annotation coverage keeps the bar low.

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

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

Two tight sentences: the first states what the tool does and why, the second front-loads the replacement behavior. No filler or redundancy.

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

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

For a three-parameter mutation tool with full schema coverage and annotations covering safety and idempotency, the description supplies the missing behavioral piece (replacement of existing mappings). Return values are not explained, but no output schema exists and the tool's outcome is self-evident.

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, and the description adds real meaning beyond the schema by clarifying that 'from' accepts either a full URL or a bare path. It adds nothing about productId or slug, which the schema already covers.

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

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

States a concrete verb and resource ('send an old help center address on to one of this product's articles') and scopes it to help center redirects, which is clearly distinct from siblings like remove_redirect and list_redirects. An agent knows exactly what this creates without opening the schema.

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

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

Gives clear context for use ('so old links keep working'), implying the migration/legacy-URL scenario. It does not name alternatives such as list_redirects to check existing mappings or remove_redirect to undo, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the agent knows this mutates state but is not flagged destructive. The description adds that the call returns DNS records to add, which is useful behavioral context absent from the annotations. It does not address non-idempotency (what happens on repeat calls) or interaction with already-existing domains, leaving a real gap for a mutation 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?

Compact – three short sentences, with the core action front-loaded. The phrase "in one step" duplicates the title and the quoting style around the layout keywords is slightly awkward, but no sentence is wasted.

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

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

There is no output schema, and the description correctly covers the return value (DNS records). Layout semantics are well covered, but for a non-idempotent mutation tool the description is silent on limits, repeat-call behavior, and how it interacts with pre-existing domains or the sibling add/verify tools – a moderate completeness gap rather than a fatal one.

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 67%: root and region are documented in the schema, but layout is a bare enum with values only. The description carries the semantic burden for layout by explaining what each preset actually configures (root/news./reply. vs everything on mail.), which the schema cannot convey. Region's meaning remains schema-only, which is acceptable.

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 concrete verb and resource: it adds email domains in one step using a preset layout. It implicitly distinguishes itself from single-domain siblings like add_mail_domain or register_mail_domain by emphasizing the one-step/batch nature, but it never names those alternatives explicitly, so sibling differentiation is left to inference.

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 real usage context for choosing between layouts ("recommended" for a full setup, "single" for a Resend plan with few domains), which is genuinely helpful. However, it offers no guidance on when to use this tool versus add_mail_domain/register_mail_domain, nor any prerequisites (e.g., domain already verified, existing domains present).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that by stating the article 'is saved like an editor save and goes live,' which tells the agent the effect is a production publish. It does not disclose whether the live article is overwritten, whether the action is reversible, or whether confirmation is required.

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, and the core action and its effect are front-loaded. Every clause earns its place by clarifying scope and outcome.

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?

Adequate for a mutation tool whose schema is fully documented and whose annotations carry the safety hints. Still, for a destructive publish with no output schema, it omits what happens to the previously live article and whether the publish can be undone, which an agent should know before invoking it.

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

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

Schema description coverage is 100%, so all three parameters are already documented; the description's mention of 'as drafted or with your edited Markdown' maps loosely to the optional 'proposed' field but adds no syntax or format detail beyond the schema's 'whole article file ... front matter included.' Baseline 3 is appropriate.

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

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

States a specific verb (publish) and resource (one proposed article update from Code updates), and clarifies the two modes of operation (as drafted, or with your edited Markdown). An agent can distinguish this from edit_code_update, discard_code_update, and decide_code_update_batch without opening any schema.

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

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

Usage is implied by 'publish one proposed article update,' and the outcome ('goes live') hints at when the agent would want this rather than editing. However, it never names the alternatives (edit_code_update, discard_code_update, decide_code_update_batch) or states preconditions/exclusions, leaving routing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation risk is covered structurally. The description adds genuine context on top: the effect is permanent (the guidance becomes part of the agent's playbook), approval is restricted to admins, and an optional replacement text can be supplied instead of the proposed one. Repeat-call or error behavior is still unstated, keeping this 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?

A single sentence that front-loads the action, then the effect, then the permission constraint. Every clause carries information and nothing is redundant.

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

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

For a two-parameter mutation tool with no output schema but full annotation coverage, the description supplies the effect, the auth requirement, and the optional-override behavior an agent needs before calling it. Only the return/confirmation behavior and failure modes are left implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; the baseline is 3. The description's phrase 'optionally with edited guidance text' corroborates the optional 'proposed' override but adds no format, length, or validation detail beyond the schema.

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

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

The description gives a specific verb and resource ('Approve a pending proposal') plus the outcome ('joins the product's playbook the AI agent follows'), which is far more informative than the title alone. It does not, however, name the sibling it is distinguished from (e.g. dismiss_training_proposal or list_training_proposals), so the agent must infer the boundary from the domain wording.

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?

'pending proposal' and 'Admins only' imply the applicable context and a prerequisite, but there is no explicit when-to-use/when-not statement and no named alternative such as dismiss_training_proposal for rejecting a proposal. Usage is inferable rather than 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 flag destructiveHint=true and idempotentHint=true; the description usefully reframes that by explaining the article and its history are preserved and the action is reversible via update_article. That is real context beyond the annotations. It stops short of mentioning permission requirements or the resulting article state.

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

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

Three short sentences, zero waste, with the effect front-loaded before the reversal path and the 'not deleted' clarification. Nothing is padded or repeated.

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

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

For a two-param mutation with no output schema, the description covers the key agent questions: what changes, what is retained, and how to reverse it. It could note whether article versions/history remain listable after archiving, but that 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 coverage is 100% — slug (including collection) and productId are both documented in the schema, including provenance ('from list_articles', 'from list_products'). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Take a help article out of the help center') and immediately narrows the effect: removed from public help center AND away from the AI agent, while retaining the article and its history. It explicitly distinguishes itself from deletion ('Articles are not deleted from here'), so an agent can separate it from any destructive/trash semantics.

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

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

Gives a clear reversal path — 'update_article with status "published" brings it back' — which tells the agent both when this tool is appropriate and how to undo it. It doesn't spell out prerequisites or a case where a different tool is preferred, but the 'not deleted from here' note implicitly rules out the delete interpretation.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, covering the safety profile. The description adds no behavioral context beyond the annotation, such as whether the assigned teammate is notified, whether existing assignment is replaced, or what side effects occur.

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 action and lists the possible assignment targets compactly. Every clause earns its place, 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?

For a simple two-parameter mutation tool with complete schema coverage and annotations that communicate the safety profile, the description gives enough to understand the tool's core purpose. The main gap is the absence of when-to-use guidance, but overall it is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the meaning of "ai" and null. The description restates the same semantics without adding new format or syntax details, so the baseline score of 3 applies.

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

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

The description states a specific verb (give/assign) and resource (conversation), and enumerates the three possible assignment targets: teammate, AI agent, or unassigned. This is clear and unambiguous, but it does not explicitly differentiate the tool from siblings like update_conversation or reply_to_conversation.

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

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

The description explains what values can be passed for the assignment target, but it provides no guidance on when to use this tool versus alternatives such as update_conversation, merge_conversations, or snooze_conversation. There are no prerequisites, conditions, or exclusions 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world), so the bar is lower. The description adds real context beyond that: work happens asynchronously ('Drafts reach Code updates for review as they are written'), is bounded by a build budget, and runs on the workspace model. It stops short of saying whether the call blocks or how progress is polled.

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

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

Two tight sentences with the action front-loaded and no filler. The second sentence about drafts arriving is dense but each clause earns its place; nothing is wasted.

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

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

For a non-idempotent, no-output-schema build tool, the description tells the agent where results land (Code updates for review), which resolves the main 'what happens next' question. It omits duration/blocking behavior and any link to the approval tools that consume the drafts.

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

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

Schema description coverage is 100%, so both productId and about are already documented and baseline is 3. The description mentions the repo source, model, and budget but adds no syntax or meaning for the two declared parameters (e.g., whether `about` influences extraction quality).

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

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

States a specific verb (build/start building) and resource (the product's knowledge base) with its source (connected GitHub repositories), which separates it from siblings like retry_product_setup or approve_code_update. Sibling differentiation is present implicitly via the Code updates workflow, but it never names an alternative tool explicitly.

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

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

Usage is implied by the prerequisites it names (connected GitHub repos, workspace model, build budget) rather than stated as an explicit when-to-use rule. There is no guidance on when NOT to run it, or how it relates to approve_code_update / decide_code_update_batch as follow-on steps.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: cancellation is not atomic - mail already handed to the provider cannot be recalled, only unsent mail is suppressed. It still doesn't say whether the cancel is reversible or what error states look like.

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

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

One sentence, front-loaded with the action and its scope, followed by the one behavioral caveat that matters. No padding 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 single-parameter destructive tool with no output schema, the description plus annotations cover the essentials: what it does, what states it applies to, and the partial-cancellation caveat. Missing only secondary details such as reversibility and permission requirements.

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

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

There is a single parameter with 100% schema coverage, and the schema description even points to list_newsletters as the id source. The description adds no additional meaning about campaignId, so the baseline 3 for full schema coverage is correct.

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

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

States a specific verb (stops) plus the resource (newsletter) and narrows the applicable states to 'scheduled or sending', which cleanly separates it from create_newsletter, schedule_newsletter, update_newsletter and preview_newsletter without needing to name them.

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 'scheduled or sending' gives clear context for when the tool applies, so an agent knows it should not be used on a draft or an already-sent campaign. It stops short of naming alternatives or stating exclusions explicitly (e.g. what to do for a draft, or whether update_newsletter is the right path instead).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes beyond them by disclosing real side effects: a viewer's open conversations return to the queue, and the workspace always retains an owner. It omits whether the change is immediate/irreversible in other respects or what happens to in-flight assignments for other roles.

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

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

Three short sentences, front-loaded with the action and immediately followed by the two most important behavioral constraints. No preamble 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 two-parameter mutation tool with no output schema and covering annotations, the description supplies the key side effects and the owner-invariant. Remaining gaps are permission requirements and error behavior for the last-owner case, which are minor given the annotation coverage.

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

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

Schema coverage is 100% and the role enum is fully documented in the schema, so the description is not required to carry parameter meaning. It adds no additional semantics about userId or role, so the baseline 3 applies.

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

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

States a specific verb (change) and resource (a teammate's role), which is readily distinguished from invite_teammate, remove_teammate, and list_team in the sibling set. It is clear, but it never explicitly names those neighboring tools, so differentiation relies on the reader's inference.

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 offers no when-to-use or when-not-to-use guidance and no prerequisites (e.g., which roles may perform this change, whether a teammate must first be invited). The only workflow hint, 'The teammate id from list_team,' lives in the schema rather than the description.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and (notably) readOnlyHint=false, so the safety profile is supplied. The description adds that the operation inspects DNS, certificate, and liveness, and 'now' implies a freshly triggered live probe rather than a cached read - context that helps explain why readOnlyHint is false. It does not disclose latency, rate limits, or what happens if the domain is misconfigured.

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

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

A single front-loaded sentence with zero filler: verb, resource, and the three things inspected. Nothing is redundant with the title or schema.

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

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

For a one-parameter check tool with annotations and no output schema, the description covers purpose and the substance of the result (DNS, certificate, live status), which is enough for an agent to call it correctly. It stops short of describing the result shape or error behavior on failure, which is a minor gap given there is no output schema.

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?

Only one parameter and schema coverage is 100%; the schema itself documents that domainId comes from list_help_center_domains. The description adds no syntax, format, or ID-sourcing detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb ('check') plus specific resource ('a custom help center domain'), and it enumerates what is inspected: DNS records, certificate, and live status. It is distinguishable from check_mail_domain/verify_mail_domain by resource, though it never names those siblings explicitly.

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

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

Usage is only implied: the word 'now' suggests an on-demand re-check of a domain that has already been added (via add_help_center_domain) or is being troubleshot. There is no explicit when-to-use statement, no prerequisite, and no mention of alternative tools like list_help_center_domains or the mail-domain equivalents.

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

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

Annotations already cover the safety profile (idempotent, non-destructive, not open-world), and the description adds the important detail that this is a refresh-and-DNS-lookup rather than a verification trigger. This explains why readOnlyHint is false despite the 're-read' framing — it re-fetches and stores state — though it doesn't state side effects on cached status explicitly.

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

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

One sentence, front-loaded with the core action, ending with the discriminating clause. No filler or restatement of the title.

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

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

With no output schema, the description does convey what the call produces (refreshed status plus DNS records). It could note whether this changes the domain's verification state or when a refresh is warranted, but for a one-parameter refresh tool it is nearly 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?

There is a single parameter with 100% schema description coverage ('Email domain id.'), so the schema carries the parameter burden. The description adds no format, prefix, or sourcing detail beyond the schema, which is the expected baseline for a fully covered single-param tool.

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

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

The description names specific verbs and resource: re-read the domain's status from Resend and re-look-up its DNS records. It also distinguishes itself from verify_mail_domain with the clause 'without asking Resend to verify', so an agent can route between the two without opening either schema.

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

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

The negative constraint 'without asking Resend to verify' implicitly selects this tool over the verify_mail_domain sibling for a non-mutating refresh. It gives clear context but never states explicitly when to prefer a plain refresh over a verification, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds useful behavioral detail by listing the checks performed and surfacing the canSend decision field, but says nothing about cost, latency, or what happens if checks fail beyond the boolean.

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

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

Two tight sentences, front-loaded with the pre-flight framing and then a compact enumeration of check categories. Every clause earns its place, though the final sentence is slightly clipped and relies on the reader to infer what canSend contains.

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

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

With no output schema, the description carries the full burden of explaining returns, and it only names one field (canSend) out of what is clearly a multi-part check result. The input side is fully covered by the schema, but an agent cannot tell the shape or granularity of the diagnostic output it will receive.

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

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

There is a single parameter with 100% schema description coverage ("Newsletter id from list_newsletters."), so the schema fully documents it. The description adds no additional meaning about campaignId, which is the correct baseline of 3 when structured data does the heavy lifting.

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

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

The description names a specific operation (a send pre-flight for a newsletter) and enumerates exactly what it evaluates: sender, post-consent audience counts, suppressions, frequency cap, email setup readiness, and content/link checks. It is clearly distinguishable from nearby siblings like get_newsletter_results or preview_newsletter, though it never explicitly contrasts itself with them.

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 send pre-flight" implies the tool is used before scheduling or sending, and the closing line ties canSend to schedulability, so the usage context is inferable. However, it never states when to use this versus preview_newsletter, count_newsletter_audience, send_test_newsletter, or schedule_newsletter, and offers no prerequisites 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact: the no-filter case counts the entire contact base. It says nothing about cost, latency or result precision on a large workspace.

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, front-loaded with the verb and scope, with the default behavior in a compact parenthetical. No filler and nothing an agent must skip past.

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 filterable count tool with zero required params, 100% schema coverage and no output schema, the description covers the essential ambiguity (what happens with no filters). Minor gaps remain: it does not state that it returns a single integer or how multiple filters combine.

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

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

Schema description coverage is 100%, so every parameter (search, productId, segmentId, emailStatus with its enum) is already documented, including where IDs come from. The description's enumeration of 'search, segment, product or email status' merely restates those same axes without adding format or combination semantics (e.g. whether filters AND together).

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

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

States a specific verb (count) and resource (contacts) with the filter axes spelled out, so the agent immediately knows this returns a number rather than records. It does not name the sibling it competes with (search_contacts, count_duplicate_contacts), so the differentiation is implied rather than stated.

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

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

Usage is implied by the verb — use this when you need a count rather than the contacts themselves — and it clarifies the no-filter default ('all contacts when none is given'). However, it never says when to prefer count_contacts over search_contacts or count_duplicate_contacts, and lists no prerequisites 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful semantic detail by defining what counts as a duplicate (shared email address), but says nothing about the shape of the result or whether pairs vs contacts are counted.

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

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

A single front-loaded sentence that delivers the whole definition 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?

For a zero-parameter count tool with no output schema, the description defines the metric well enough to call correctly. The only minor gap is that the return shape (a single integer vs grouped counts) is left implicit.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to compensate for, and it correctly avoids inventing filtering options.

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?

Defines a specific metric: the count of contacts that share an email address with another contact. An agent can tell it apart from count_contacts (which counts all contacts) and from merge_duplicate_contacts, though it does not explicitly name those siblings as the boundary.

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 the implied use case (quantifying duplicate overlap) but gives no explicit when-to-use, no when-not, and never points to the closely related siblings list_merge_candidates or merge_duplicate_contacts. An agent must infer the routing itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral substance beyond that: the count is applied after consent and suppressions and is broken into eligible, in-scope, not-subscribed, suppressed, and frequency-cap categories, and confirms nothing is persisted. It does not describe the return shape, but annotations raise the bar lower.

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

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

Front-loads the answer (count of addresses) in a single compact sentence, with the 'Nothing is saved' clause placed last to reinforce the non-persisting behavior. The middle enumeration of count categories is dense but informative; nothing is wasted.

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

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

For a read-only count tool with a deeply nested schema and no output schema, the description conveys the counting basis, the suppressions/consent layer, and the category breakdown. It is nearly complete, though without an output schema the exact return shape (single number vs. per-category breakdown) remains ambiguous.

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

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

Schema description coverage is 100% and both parameters (audience, productId) are documented in depth in the schema itself, so the baseline is 3. The description names the audience inputs (segments, tags, filters, exclusions) but adds no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb+resource ('how many addresses an audience would reach now') and clarifies the counting basis (segments, tags, filters, exclusions). It is clearly a counting tool, but it never distinguishes itself from close siblings like count_contacts, check_newsletter, or preview_newsletter, so an agent must infer which counter applies.

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

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

Usage is implied by 'would reach now' and 'Nothing is saved', signalling a dry-run/pre-flight estimate, which is useful context. However, there is no explicit when-to-use guidance and no routing to alternatives (count_contacts, preview_newsletter, get_newsletter_results), so the agent is left to infer the right tool.

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=false), and the description adds real behavioral context: the article defaults to a draft unless status is 'published', it is indexed for search and the agent, and passing gapId marks the question drafted. It omits any auth/permission requirements, so not a full 5.

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

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

Three sentences, front-loaded with the core action, with the draft-default and collection/gapId details following logically. Dense but every sentence carries information; no filler.

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

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

For a 7-parameter creation tool with no output schema, the description covers the creation semantics, default status, collection targeting, and the gapId side effect. It leaves the 'description' field and product scoping unaddressed, but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: collection accepts an id, an existing title, or a new name, and gapId has the side effect of marking the question drafted. The 'description' parameter is left unaddressed.

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+resource ('Write a new help article in a hosted product'), and 'new' implicitly distinguishes it from update_article. It does not explicitly name a sibling alternative, so it falls short of full differentiation.

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

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

It gives conditional guidance for one path ('Pass gapId when the article answers an unanswered question') and the default status behavior, but offers no when-to-use-this-vs-alternatives guidance against draft_article_from_conversation or update_article. Usage is implied rather than spelled out.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description still adds real behavioral context: the entry is a draft by default and only 'published' status exposes it on the public changelog and widget. That public-visibility side effect is exactly the kind of consequence an agent needs before setting status. It omits auth/permission requirements and whether publishing is reversible.

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, zero filler, with the core action front-loaded and the consequential status behavior immediately after. Every clause earns its place.

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

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

For a 7-parameter creation tool with no output schema, the description covers the publishing side effect but not the required parameters (productId, title) or the return value an agent would need an entry id for later update/delete. Adequate but with clear 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 71%, so the schema documents most fields. The description adds genuine meaning for 'status' by explaining what 'published' actually does (public changelog + widget visibility), which goes beyond the schema's bare 'Defaults to draft'. It says nothing about body, tags, version, or summary, so moderate value only.

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

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

States a specific verb and resource ('Write a changelog entry'), so the action is unambiguous. It does not, however, differentiate itself from close siblings like update_changelog_entry, draft_changelog_from_releases, or delete_changelog_entry, leaving that disambiguation to the name alone.

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

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

The description contains no when-to-use or when-not-to-use guidance and never names an alternative such as update_changelog_entry (for modifying an existing entry) or draft_changelog_from_releases (for AI-assisted drafting). An agent must infer usage purely from the verb 'write'.

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

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

Annotations already declare readOnly=false, destructive=false and idempotent=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: the collection id is derived from the title and becomes the first segment of article slugs, which has real consequences for later article URLs. It does not address permissions or visibility defaults, 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?

A single dense sentence that front-loads the action, then the accepted fields, then the ordering constraint and the id-derivation rule. Nothing is padded and nothing is repeated from the structured fields.

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 creation tool the description covers purpose, fields and the slug/id rule, and with no output schema it need not explain returns. However it omits the required productId linkage and whether the new collection is immediately live versus draft, leaving gaps an agent would want before creating one.

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 every parameter is already documented in the schema and the baseline is 3. The description names title, description and icon but adds no meaning for productId or the visibility enum beyond what the schema states.

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

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

States a specific verb and resource ('Start a new collection in the help center') and immediately scopes it with the fields it accepts and the ordering constraint ('before any article is filed in it'). An agent can distinguish this from update_collection or create_article without opening any schema.

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

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

The phrase 'before any article is filed in it' implies the sequencing use case, but the description never names alternatives (create_product, update_collection) or states when a collection is the right container versus, say, a product. Usage is inferable rather than explicit.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), but the description adds real behavioral value beyond them: consent remains unknown, suppressed addresses are rejected, and an existing contact with the same address is filled in rather than duplicated. It does not mention permissions or what the call returns, but for an annotated mutation tool this is solid disclosure.

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

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

Three tight sentences, zero filler, with the core create/upsert behavior front-loaded before the consent and suppression caveats.

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

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

For a mutation tool with no output schema and a nested attributes object, the description covers the behavioral edge cases an agent most needs (consent state, suppression, upsert). Missing only return-value expectations and any permission requirements, which keeps it short of full 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 80% (4 of 5 properties documented, only 'name' bare), so the schema already carries most parameter meaning. The description adds only indirect parameter insight — that no consent parameter exists here and that opt-in needs a separate action — without clarifying any parameter's format or constraints.

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

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

States a specific verb and resource ('Adds one contact to a product by email') and immediately distinguishes its behavior from a plain create by noting the upsert case ('or fills in an existing contact with that address'), which separates it from update_contact and search_contacts in the sibling list.

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

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

Gives clear operational context and implicit exclusions: suppressed addresses are not added, and opt-in recording 'is a separate action requiring its source' (pointing away from set_contact_consent). It stops short of explicitly naming the alternative tools or stating when a caller should prefer update_contact over this tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the source can be a campaign or a raw document, but says nothing about what happens on duplicate names, required permissions, or reversibility of a saved template.

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 front-loads the primary use case (saving an existing newsletter) and appends the secondary mode. Efficient with no filler, though the trailing 'or a full email document' is slightly loose.

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 creation tool with 5 params, a nested object, 40% schema coverage, and no output schema, the description resolves the main dual-mode ambiguity but omits return-value expectations and leaves several parameters unexplained.

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 only 40%, so the description should compensate. It reinforces the campaignId ('existing newsletter') and document ('full email document') semantics, but those already carry schema descriptions, and it adds nothing for name, category, or description.

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

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

States a specific verb (saves) and resource (template) and clarifies that the source can be either an existing newsletter via campaignId or a full email document. This distinguishes it from create_newsletter (which makes newsletters) and update_email_template, though it doesn't explicitly name those siblings.

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

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

The 'or a full email document' clause implies the two supported input modes, giving some usage signal, but there is no explicit when-to-use guidance, no when-not, and no reference to alternatives like create_saved_reply or update_email_template.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, but the description still adds lifecycle context annotations cannot express: the created journey remains a draft until publish_journey is called. It omits validation failure behavior and whether repeated calls create duplicates, but the draft-state disclosure is genuinely useful beyond the 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?

Three short sentences, zero filler, front-loaded with the action and followed by the lifecycle constraint and the routing advice in order of importance.

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

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

For a mutation tool with no output schema, the description covers what it produces, its lifecycle state, and sibling routing, which is enough to call it correctly given the richly documented schema. It would be stronger if it noted whether the definition is validated or what happens on an invalid step definition.

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

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

Schema description coverage is 100% and the single 'definition' parameter is documented in exhaustive detail (trigger enums, step types, step count bounds). The phrase 'a full definition' adds only a hint that an existing complete journey document can be reused, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Saves a new draft journey') and immediately names the sibling that advances it ('publish_journey') plus the two lighter-weight alternatives ('a recipe or generate_journey'). An agent can distinguish this from create_journey_from_recipe, generate_journey, and publish_journey without opening any schema.

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

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

Explicitly routes the agent away from this tool when a recipe or generate_journey would suffice, which is real selection guidance. It stops short of stating the condition under which a hand-authored full definition is actually required (e.g. custom step types like branch/wait_event), so the 'when to use this one' side is implied rather than stated.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent write. The description adds value beyond them by disclosing the output is a draft (not published), that email steps are created empty, and that ready email content is required before publication – real workflow context. It does not say whether repeated calls create duplicate journeys or what auth is needed.

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, zero waste, and the core action is front-loaded before the publishing caveat. Nothing is redundant with the title.

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

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

For a low-complexity two-parameter tool with no output schema, the description covers the action, the resulting state (draft), and the publication prerequisite. It omits only follow-up details such as the returned journey identifier or next steps, which is a minor gap.

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

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

Schema description coverage is 100%, so both parameters (recipe, productId) are already documented with their source list tools. The description adds no syntax, format, or selection guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Copies a recipe into a new draft journey.' The 'from a recipe' framing implicitly separates it from create_journey and generate_journey, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

Usage is implied rather than stated: the recipe id must come from list_journey_recipes (per the schema) and the second sentence hints at a downstream prerequisite to publish. There is no explicit when-to-use-this-vs-create_journey guidance, leaving the agent to infer the choice.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that nothing is sent (draft-only) and that content is used verbatim with no AI generation or template selection — real behavioral context beyond the annotations. It stops short of noting auth/consent implications or limits on repeated calls.

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

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

Three tight sentences, zero filler, with the core action front-loaded and the draft-only/no-AI caveats immediately following. Every sentence carries distinct information.

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

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

For a 15-parameter mutation tool with a nested audience object and no output schema, the description covers the essential semantics (draft, no send, no AI). It omits any mention of audience targeting or productId, but those are documented thoroughly in the schema, so the gap is minor.

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

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

Schema description coverage is 93%, so the schema already documents nearly every parameter, including the rich nested audience filters. The description only lists a handful of content fields (subject, title, introduction, sections, button) and adds no syntax or format detail, so baseline 3 is appropriate.

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

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

States a specific verb and resource ("Saves a new newsletter draft from plain fields") and enumerates the content fields it consumes, so the agent knows exactly what it produces. It also distinguishes its behavior from AI/template-driven siblings ("without AI generation or template selection"), though it never names generate_newsletter explicitly.

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

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

"Nothing is sent" and "without AI generation or template selection" imply this is the tool for author-supplied content versus AI drafting, and that a send step is separate. However, no sibling is named and there is no explicit when-to-use/when-not statement or prerequisite guidance, leaving the alternative-selection decision to inference.

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

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

Annotations already flag a non-readonly, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds crucial context beyond that: it is a draft, visitors see nothing until publish. It omits return shape and any permission limits, but the key behavioral trait is 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?

Three short sentences, zero waste, with the draft scoping front-loaded and the sibling pointers following. Every sentence earns its place.

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

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

For an 11-parameter creation tool with no output schema, the description covers purpose, lifecycle (draft vs published) and the copy-drafting alternative, while the rich schema handles the parameter detail. Output/return values are not described, which is a minor residual 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 91% and the properties already explain content, trigger, audience, goal, frequency and schedule in detail. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Saves a new chat message, pop-up or banner as a draft") and immediately distinguishes the three message kinds. It also implicitly differentiates from publish_proactive_message and write_proactive_message_copy, so an agent can place it in the create/draft slot without opening a sibling schema.

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

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

Clearly signals the create-as-draft flow and names two alternatives with their roles: publish_proactive_message to make it visible, write_proactive_message_copy to draft the wording. No explicit when-not-to-use or preconditions, but the routing 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuine context beyond them: hosted mode is fully provisioned 'before this returns' (a synchronous, potentially slow side effect) and the call yields a product id plus setup status. It does not mention failure/retry behavior, but retry_product_setup exists as evidence that setup can fail.

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

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

Front-loaded with the core action, then the mode semantics, then the return value. Three sentences, all earning their place. The middle sentence is dense but not padded.

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

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

There is no output schema, so the description must and does say what comes back ('the new product id and its setup status'). Combined with annotations covering safety and a fully documented schema, an agent has what it needs. The absence of explicit failure/retry guidance is the only gap, and retry_product_setup exists as a sibling signal.

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 earns a step above by explaining what 'hosted' and 'connected' actually mean operationally, which the schema only hints at with 'Default hosted.' It does not add anything for name or siteUrl, but those are self-documenting in the schema.

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

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

States a specific verb and resource ('Add a product to the workspace') and immediately elaborates on the two creation modes, which is exactly what separates it from get_product/list_products/update_product. An agent can tell what this does without opening the schema.

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

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

The description explains the hosted-vs-connected distinction, which is effectively a usage decision, but it never states when to reach for create_product versus siblings like update_product or retry_product_setup, nor any preconditions (e.g. whether a workspace can hold multiple products). Usage is implied rather than routed.

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 this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds genuinely new operational detail: the supported merge variables ({{first_name}}, {{agent_name}}, {{product}}) and the pipe fallback syntax, which an agent cannot learn from the schema or annotations and which directly affects how the body must be authored.

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

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

Two sentences, zero filler. The purpose comes first and the templating rule follows, so the agent gets the most decision-relevant information up front.

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 4-parameter create with annotations covering safety and no output schema, this is adequate but thin: it is silent on the tags and shared parameters beyond the schema, on whether a duplicate title is rejected, and on what the call returns. Nothing an agent strictly needs is missing, but the definition does not go out of its way to be complete.

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

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

Schema coverage is 75% (title, body, and shared are documented; tags is not), so the baseline would be 3. The description goes beyond the schema by specifying the templating grammar that governs valid body content, which the schema only describes as 'the reply text, up to 8,000 characters.'

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 ('Save a reply') and clarifies the resulting artifact is a team-insertable snippet for the composer. It does not distinguish itself from close siblings like update_saved_reply, render_saved_reply, or delete_saved_reply, so an agent must infer the create-vs-edit boundary from the name alone.

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

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

It says what a saved reply is for (composer insertion) but gives no when-to-use guidance, no prerequisites, and never names an alternative such as update_saved_reply for editing or render_saved_reply for previewing. This matches the calibration case of a bare 'update settings' tool, which scored 2.

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 this as a non-read, non-destructive, non-idempotent write. The description adds real behavioral context beyond that: it creates a saved, reusable audience and explicitly does NOT send messages, which is the key side effect an agent needs to know.

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

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

Two tight sentences: the first defines the artifact and its downstream use, the second delivers the critical no-send caveat. Every clause earns its place and the definition is front-loaded.

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

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

For a create tool with no output schema, the description covers purpose and usage but omits what is returned (e.g., a segment id) and what happens on duplicate names, which matters given idempotentHint=false. Adequate but with clear gaps for a creation action.

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%, but the undocumented parameter (`name`) is trivial and self-evident, while the complex `rules` parameter is already exhaustively documented in the schema (fields, operators, mode, date syntax). The description only restates 'rules on contact fields,' adding 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?

States a specific verb and resource ('Saves a segment') and clarifies its scope ('contacts matching rules on contact fields'). It differentiates from sending tools with 'saves the rules without sending messages,' though it does not name the closest siblings (list_segments/update_segment).

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

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

Usage is implied rather than stated: the description explains the segment becomes a targeting audience for newsletters, journeys and messages, which hints at when to create one. It offers no explicit when-not condition or alternative (e.g., update_segment for existing segments, list_segments to inspect).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered structurally. The description adds real value by stating the outcome of publishing ('makes those articles live'), but says nothing about what discarding does to the pending proposals or whether either action is reversible.

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, zero filler, with the dual action and scope front-loaded. Every clause carries information.

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

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

For a mutation tool with strong annotations and no output schema, the description covers scope, both actions, and the publish consequence. The remaining gap is the discard side-effect, which is minor given destructiveHint=true.

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 67%: batchId and productId are documented in the schema, while the decision enum's semantics are not. The description hints at the two outcomes ('publish, or discard') and the batch scope but adds no syntax or mapping detail beyond the schema.

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

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

The description states specific verbs (publish/discard) and the precise resource ('every proposal still waiting in one code check'), making the batch scope clear. It does not explicitly name the single-item siblings approve_code_update/discard_code_update, so the differentiation from them is left implicit.

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?

'Every proposal still waiting in one code check' implies when to use this over a single-item decision, but no alternative tool is named and no precondition (e.g. obtain batchId via get_code_updates) is spelled out beyond the schema. Usage is inferable, not explicit.

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

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

Annotations already disclose write, non-idempotent, non-destructive, closed-world behavior, so the bar is lower. The description usefully adds the reserved-namespace rule ('lf_'/'icp_' are HelpWell's own), but it says nothing about what happens on a repeat call for a non-idempotent write, whether an existing field name errors, or permission requirements.

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 immediately followed by the constraint that matters most. Dense but every clause carries information; the first sentence is slightly run-on but nothing is wasted.

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

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

For a four-parameter mutation with no output schema and thin schema coverage, the description covers the concept and reserved keys but omits conflict/error behavior and the meaning of the non-idempotent write. Enough to attempt the call, not enough to predict its failure modes.

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

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

Schema description coverage is only 25% (only 'field' documented), so the description has to compensate. It does add real value for 'field' via the reserved-prefix rule and explains the purpose of 'type' ('so segments, journeys and personalization treat it right'), but 'label' and 'description' remain undocumented and the seven enum values are never characterized.

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

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

States a specific verb+resource ('Create a contact field') and distinguishes two distinct modes: pre-declaring a field before its first value, and pinning a guessed field to a type. It reads clearly against near-neighbours like list_fields and unlock_field, though it never names them explicitly.

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

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

The two clauses imply when each mode applies ('ahead of its first value', 'lock a guessed one'), which is better than nothing. But there is no explicit contrast with alternatives (update_contact, unlock_field, list_fields) and no stated prerequisite such as an existing guessed field being required for the locking mode.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is documented. The description adds genuine context beyond that by stressing permanence ('for good') and routing to the non-destructive archival path, though it does not describe return behavior or confirm irreversibility explicitly.

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

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

Two sentences, zero filler, and the crucial warning about permanence is front-loaded before the alternative route. Every clause earns its place.

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

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

For a two-parameter delete tool with full schema coverage, complete annotations, and no output schema, nothing an agent needs to call it safely and correctly is missing. The destructive semantics and the safer alternative are both stated.

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

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

Schema description coverage is 100%, so both parameters (id, productId) are already documented in the schema, including the cross-reference to list_products. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Delete') and resource ('a changelog entry'), and explicitly clarifies the permanence with 'for good'. It distinguishes itself from the sibling update_changelog_entry by name, so an agent can tell it apart without opening a schema.

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

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

Explicitly names the alternative (update_changelog_entry with status 'archived') and the exact condition that selects it: when you want it off the public changelog but kept. Both the when-to-use and the when-to-use-something-else are covered.

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

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

Annotations already declare destructiveHint=true and non-idempotent behavior. The description adds useful context beyond that: it confirms the action cannot be undone and specifies that emails already started from the template are not affected. It does not cover permissions or error behavior, but the added side-effect detail is meaningful.

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

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

Three short sentences, perfectly front-loaded with the core action first and side-effect caveats after. Every sentence 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?

Given the destructive annotations and fully documented single parameter, the description provides the essential behavioral context an agent needs: it is irreversible and does not cascade to active emails. Missing details like permission requirements or behavior when the template ID is invalid are minor for this simple tool.

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

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

Schema coverage is 100% and the single templateId parameter is fully described in the schema, including its source ('list_email_templates'). The description adds no further parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific verb ('Deletes') and resource ('a saved template'), making the core action unambiguous. It does not differentiate from sibling delete tools (e.g., delete_saved_reply, delete_journey) or connect to the email-template family, so a 5 is not warranted.

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

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

The description gives no guidance on when to use this tool versus alternatives such as update_email_template or list_email_templates. It simply states what the tool does, leaving the agent to infer context and prerequisites.

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, readOnlyHint=false and idempotentHint=false, so the agent knows this is an irreversible-style mutation. The description adds one genuinely useful behavioral detail — that deletion does not block the sender — but says nothing about permissions required, permanence, or side effects on the conversation/history.

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 short, front-loaded sentence with the action first and the distinguishing constraint last. There is no filler and nothing that could be trimmed without losing information.

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

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

For a one-parameter tool with rich annotations and no output schema, the description is adequate but thin on the aspects that matter for a destructive operation: whether the deletion is permanent, whether the email can be recovered, and what the agent should expect afterward.

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

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

Schema description coverage is 100% and the single emailId parameter is fully documented in the schema ('The id from list_external_mail'), which even cross-references the sibling listing tool. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (delete) and a specific, scoped resource (one email from the External tab). The phrase 'without blocking its sender' implicitly contrasts it with sibling operations like mark_external_mail_spam or list_blocked_senders, though no sibling is named explicitly.

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

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

Usage is only implied: 'one email' and 'from the External tab' suggest single-item deletion from a specific mailbox view, and 'without blocking its sender' hints at when not to use spam/block flows. There is no explicit statement of when to prefer this over mark_external_mail_spam, move_external_mail_to_inbox, or list_external_mail.

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

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

Goes well past the destructiveHint=true annotation by disclosing exactly what is destroyed (enrollees exit, queued sends are cancelled) and what survives (history is retained and can be restored, in a paused state). For a destructive, non-idempotent mutation this is the precise lifecycle context an agent needs.

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

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

Two short sentences, zero filler, with the destructive effect stated first and the recovery path second. Every clause conveys a distinct fact.

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

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

No output schema exists, yet the description covers the observable effects, what persists, and how to undo the action, which is everything needed to call this single-parameter destructive tool responsibly.

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

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

The single journeyId parameter is fully documented in the schema ('Journey id from list_journeys'), so the schema carries the load and the description adds nothing about the parameter. Baseline 3 applies when coverage is 100%.

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

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

Names a specific verb and resource ('Deletes a journey') and immediately scopes what that means operationally, which separates it from siblings like discard_journey_draft, stop_journey_run, pause_journey and restore_journey. An agent can pick this tool without opening any other definition.

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 signals the reversal path explicitly ('restore_journey brings it back paused'), which gives the agent a clear alternative to consider before deleting. It stops short of stating when deletion is preferred over pause_journey or stop_journey_run, so the choice among the journey-state siblings is still inferred.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the safety profile is covered; the description goes further by disclosing the exact semantics — immediate stop, cancellation of queued journeys, stats retained, irreversibility. It also usefully clarifies that 'delete' behaves as an archive, resolving the name/semantics gap. It stops short of stating auth requirements or permission level.

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

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

Two tight sentences with zero filler; the primary effect (it stops at once) is front-loaded before the secondary consequences. Nothing could be removed without losing meaning.

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

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

For a single-parameter destructive tool with rich annotations and no output schema, the description supplies the consequences an agent needs to warn a user before calling. The only gap is the absence of a pointer to the non-destructive alternative, which would make it fully self-sufficient.

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

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

Schema coverage is 100% with a single required messageId whose description already points to list_proactive_messages. The description adds no additional parameter meaning (no format, no ID prefix, no sourced-from detail), so the baseline 3 applies when the schema does the work.

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

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

States a specific action on a specific resource: 'Archives a message' plus its consequences ('it stops at once and what journeys queued is cancelled'). An agent immediately understands this terminates a live proactive message rather than editing it. It does not, however, distinguish itself from close siblings such as pause_proactive_message or update_proactive_message.

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

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

The description conveys permanence ('cannot be brought back') but never says when to choose this over pause_proactive_message, which is the obvious non-destructive alternative in the sibling list. No prerequisites, no exclusions, no routing guidance — the agent must infer usage from consequences alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is largely covered. The description adds the shared-scope consequence ("for everyone who could use it") and reversibility ("cannot be restored"), which is useful but closely overlaps the destructiveHint the agent already sees. No mention of auth requirements or failure modes.

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, front-loaded with the action and resource, each earning its place. No hedging 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 single-parameter destructive tool whose annotations carry the safety hints, the description supplies the scope and irreversibility an agent needs before calling. An output schema is unnecessary for a delete, and little is missing.

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

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

Only one parameter at 100% schema coverage, and the schema already explains it is the id from list_saved_replies. The description contributes nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (saved reply), making it immediately distinguishable from siblings like delete_email_template or delete_journey. It stops short of naming a sibling or contrasting scope, but the action is unambiguous.

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

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

The phrase "for everyone who could use it" implies the operation removes a shared/workspace resource rather than a personal draft, which nudges usage. However, there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as update_saved_reply if the intent is only to modify.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description earns extra credit by scoping that destruction: 'Nothing in the knowledge base changes' tells the agent the blast radius is limited to the proposal, not published content. It still does not say whether the discarded proposal can be recovered or re-proposed.

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, zero filler, with the action front-loaded and the consequence second. Every clause carries information.

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

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

For a simple two-parameter, no-output-schema mutation, the description covers purpose and effect adequately. Missing only recoverability/reversibility detail, which an agent might want before executing a destructive discard.

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

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

Schema description coverage is 100% and both parameters already carry source hints ('proposal id from get_code_updates', 'Product id from list_products'). The description adds nothing about the parameters, so the baseline 3 applies.

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

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

States a specific verb and object ('Discard one proposed article update'), which cleanly separates it from approve_code_update, edit_code_update, and decide_code_update_batch among the siblings. The only wrinkle is a terminology drift: the tool name says 'code update' while the description says 'article update', which forces a small inference that these are the same entity.

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

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

Usage is implied by the verb 'discard' but never made explicit. There is no statement of when to discard versus approving, editing, or batching (approve_code_update, edit_code_update, decide_code_update_batch), and no prerequisites such as needing a valid proposal id from a prior listing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds the genuinely useful clarification that destruction is scoped to the draft and "the live version stays as it is", which prevents an agent from over-reading destructiveHint as deleting the journey. It does not say whether the discard is reversible or what happens when no draft 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?

A single front-loaded sentence with the scope constraint in the second clause; no filler, no repetition of the title.

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

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

For a one-parameter, no-output-schema tool whose safety profile is carried by annotations, the description covers what is dropped and what survives. Minor gaps remain around reversibility and the no-draft case, but nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter and schema description coverage is 100% ("Journey id from list_journeys"), so the schema fully documents the input. The description adds no format, sourcing, or edge-case detail beyond it; baseline 3 applies.

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

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

States a specific verb ("drops") and resource ("the unpublished draft of a journey"), and immediately bounds the scope so it cannot be confused with delete_journey or restore_journey. An agent can distinguish it from the many journey siblings without opening a schema.

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

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

Usage is implied by "unpublished draft" – call it when you want to throw away pending edits while keeping the live journey – but no alternative is named (delete_journey, publish_journey, update_journey) and no precondition is stated. Adequate but leaves routing to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely useful context beyond that: the functional blast radius (support and marketing email halt) and what is NOT destroyed (domains and settings persist, and how to restore service). No mention of permissions or confirmation requirements, so not a 5.

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

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

Three short sentences with the action stated first, consequences second, and persistence caveat last. Every sentence carries distinct information with no filler or repetition of the title.

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

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

For a zero-parameter destructive toggle with no output schema, the description supplies everything needed: what is affected, what persists, and how the state is reversed. Nothing required to invoke it correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter-level meaning is needed or missing.

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

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

Specific verb+resource ('Disconnect the workspace's Resend account') with an immediately clarified scope. The line 'Domains and settings are kept' distinguishes it from sibling domain-level tools like remove_mail_domain or list_resend_domains, so an agent can differentiate without opening schemas.

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

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

The effect ('Support and marketing email stop') implies when an agent should reach for this tool, and the restoration path ('connects a key again in Settings → Email') implies reversibility. However, it never explicitly states when this is preferable to alternatives (e.g. per-domain removal, updating sender identity) or any preconditions.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, so the safety profile is already covered. The description adds the crucial reversibility context that reopening is possible, which meaningfully softens and explains the destructive hint. It does not say whether the gap is deleted or merely hidden, so it is good 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 short sentences, zero waste, with the action and the distinguishing condition front-loaded before the undo note. Every clause earns its place.

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

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

For a two-parameter, no-output-schema tool whose annotations already carry the safety flags, the description supplies purpose, selection condition, and reversibility. Only the gap's post-dismissal state (hidden vs. deleted) is left slightly ambiguous.

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%: both id and productId are documented with their source tools (list_gaps, list_products). The description adds nothing about the parameters, so the schema-passthrough baseline of 3 applies.

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

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

States a concrete action (take an unanswered question off the list) and a decisive qualifier (without writing an article, when it needs none) that separates it from resolve_gap, which presumably produces an article. It also names reopen_gap as the inverse, so an agent can place it precisely in the gap lifecycle.

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

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

Gives a clear selection condition: use this when the gap needs no article. The undo path is pointed to explicitly via reopen_gap. It stops short of naming resolve_gap as the alternative for gaps that do need an article, so the routing is strong but not exhaustive.

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

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

Annotations already declare the full safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false). The description adds genuinely useful context beyond them: the flag is a reversible toggle and the scope is workspace-wide rather than per-user. It omits what happens to checklist progress on re-show, keeping this at a solid but not rich 3.

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

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

One sentence, zero waste, front-loaded with the primary action and followed immediately by the reversal case. Nothing could be cut without losing meaning.

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

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

For a one-parameter workspace toggle with no output schema and annotations already covering safety, this is nearly complete. The only open question is whether re-showing resets or preserves prior checklist progression, which would matter to a caller but is not addressed.

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

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

Schema description coverage is 100% and the single parameter is already documented as defaulting true with false re-showing it. The description restates that same semantics rather than adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb (hide/show) plus resource (Get started checklist) and scope (whole workspace). The name and description together make it trivially distinguishable from sibling dismiss_* tools, which target gaps, held replies, and training proposals rather than the onboarding checklist.

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 it (hide the checklist) and gives the inverse path (dismissed false re-shows it), but names no alternatives, prerequisites, or conditions under which you'd leave it alone. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely useful behavioral context beyond that: the note is preserved but marked dismissed, and the action is irreversible ('for good', 'cannot be accepted afterwards'). Specifics on what survives versus what is lost are the key value-add.

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 no filler. The permanence consequence is front-loaded in sentence one and the resulting state and irreversibility follow immediately.

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

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

For a single-parameter mutation with no output schema, the description covers what happens (dismissal), what state results (note kept, marked dismissed), and irreversibility. A brief note on the return value or permission requirements would fully close the gap, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and messageId is documented as coming from get_conversation, so the schema carries the parameter burden. The description adds no additional semantics about the id, so the baseline 3 applies.

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

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

States a specific verb (dismiss) and resource (held emailed reply), and the phrase 'cannot be accepted afterwards' implicitly distinguishes it from the accept path. It does not name the sibling tool accept_held_reply directly, so differentiation is inferential rather than explicit.

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

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

The description implies the use case (permanently discard a held reply) and hints that accepting is no longer possible, which points at the alternative. However, it never names accept_held_reply or states an explicit condition for choosing dismissal over acceptance, leaving the agent to infer the routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is largely covered. The description adds genuinely new context: the reason is persisted and 'kept for the team', and the operation is restricted to admins. It still doesn't say whether dismissal is reversible or what happens to the proposal record.

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

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

One compact sentence that front-loads the action and scope, then adds two clauses that each carry information. No filler, no restatement of the title.

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

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

For a two-parameter, non-idempotent mutation with no output schema and annotations that already cover destructiveness, the description covers purpose, permission, and reason handling adequately. The missing piece is the post-dismissal state of the proposal, which matters given destructiveHint=true.

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

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

Schema coverage is 100%, so the schema already documents both params, giving a baseline of 3. The description adds meaning the schema omits: the reason is optional and is retained for the team to see, which tells the agent the value is user-visible rather than internal.

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

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

States a specific verb (Dismiss) and resource (a pending training proposal) plus the optional reason, which cleanly separates it from the sibling approve_training_proposal by the action taken. It does not name any sibling explicitly, so it stays at 4 rather than 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?

'pending' scopes when the action is legal and 'Admins only' states a hard prerequisite, which is real usage guidance. However, it never contrasts with approve_training_proposal or explains what to do instead if the proposal is not dismissible, so the when-not side is only implied.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but not the key fact the description supplies: 'Nothing is published,' so a mutation call is actually a non-publishing proposal. That corrects a plausible wrong assumption about drafting content. It still omits what happens on repeated calls (idempotentHint=false) and any permission requirements.

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

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

One sentence, front-loaded with the transformation and destination, followed by the review path and the non-publication guarantee. No filler, no repetition of the title or schema.

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

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

With one fully documented parameter, no output schema, and annotations covering the safety profile, the description supplies what an agent needs: what is produced, where it lands, and how it is reviewed. Missing only edge-case behavior such as duplicate calls or failure when the conversation has no answer.

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% for the single conversationId parameter, so the schema carries the burden and the baseline is 3. The description adds real semantic value beyond it by specifying that the conversation's latest answer is the source, clarifying which part of a thread is consumed.

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

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

States a precise verb+resource pair ('Turn a conversation's latest answer into an article proposal in Training') and explicitly names the destination and the reviewing sibling tool, approve_training_proposal. An agent can distinguish it from create_article, draft_changelog_from_releases, and draft_reply_with_ai without opening any schema.

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

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

It gives clear workflow context: the output is a proposal in Training meant for review via approve_training_proposal, which tells the agent this is a draft-then-approve flow rather than a direct publish. It does not, however, state when to prefer this over sibling creators such as create_article, nor any prerequisite (e.g., the conversation must contain an answer).

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 this is a non-read-only, non-idempotent, non-destructive write. The description adds real behavior beyond that: only drafts are persisted, a release is drafted only once (dedup semantics that explain the idempotentHint=false), and publishing is a distinct action. It stops short of stating auth or configuration prerequisites.

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

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

Three tight sentences, front-loaded with the core action, followed by the save/dedup constraint and the publishing boundary. No filler and every sentence carries distinct information.

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

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

For a two-parameter tool with full schema coverage, annotations, and no output schema, the description covers purpose, persistence behavior, dedup, and workflow boundary. It does not mention what the draft output looks like or any prerequisite configuration, a minor gap given no output schema exists.

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

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

Schema coverage is 100%, so both parameters are already documented, including the limit range and default. The description's 'newest ... releases' loosely corroborates the limit's ordering but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Names a specific transformation (GitHub releases -> draft changelog entries) with the exact mechanism (workspace model) and input scope (repositories connected with 'Use releases for changelog drafts'). An agent can tell this apart from create_changelog_entry (manual entry) and draft_article_from_conversation without opening a schema.

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

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

Clear context for when this applies: drafting from releases of connected repositories, with an explicit boundary that 'Publishing is a separate action' so the agent knows to look elsewhere to publish. It does not name a sibling alternative (e.g. create_changelog_entry) for the manual case, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds valuable behavioral context: it returns text and sends nothing, and it consumes the workspace's AI budget, which is a non-obvious side effect. It does not describe rate limits or error behavior.

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

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

The description is a single, front-loaded sentence that packs many actions but wastes no words. The list of rework actions is dense but necessary for understanding the full scope; structure could be improved with bullets but is acceptable.

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 five parameters, an enum, no output schema, and annotations covering safety, the description is nearly complete. It explains the tool's output ('returns text'), its non-sending nature, and the AI budget cost, but could clarify that the returned text is a draft to be sent by another tool.

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

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

Schema coverage is 100%, so the schema documents all five parameters. The description adds semantic meaning to the action enum by explaining each mode (e.g., 'answer only from the help articles', 'rework a text (shorter, friendlier, formal, fix spelling, translate)'), which goes beyond the bare enum values.

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: use the workspace's AI model to draft, answer, summarise, or rework. It distinguishes itself from sending tools by stating 'sends nothing', so an agent can tell it apart from reply_to_conversation without opening the schema.

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

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

It provides clear context for when to use it (to generate AI text without sending) and notes the AI budget cost, but does not explicitly name alternatives like reply_to_conversation or save_reply_draft or state when not to use it. The implied usage is clear but lacks explicit routing.

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

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

Annotations already declare this as a non-readonly, non-destructive, non-idempotent write with no open-world access. The description usefully adds that the edit is held and not published, which annotations do not convey. However, it omits whether the saved version replaces the prior proposal, whether the edit can be revised again, and why the operation is non-idempotent.

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 tight sentence with no filler, and the non-publishing constraint is placed at the end as a qualifier. It is efficient, though the key state-changing verb is slightly buried behind 'keep an edited version'.

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

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

For a three-required-parameter write tool with full schema coverage, partial annotations, and no output schema, the description is minimally viable. It conveys the held-not-published behavior but leaves the workflow around approval, discarding, and re-editing unaddressed.

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

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

Schema description coverage is 100%, so the schema already explains itemId (proposal id from get_code_updates), proposed (whole article file including front matter), and productId. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a concrete action (keep an edited version of a proposed article update) on a specific resource, and clarifies it does not publish. It is clear enough to act on, but it never distinguishes itself from close siblings such as approve_code_update, discard_code_update, or decide_code_update_batch.

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

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

There is no when-to-use guidance and no named alternative. The only contextual clue is the trailing 'without publishing it yet', which hints that publishing is a separate step but never points to the tool that performs it or explains when to edit versus approve or discard a proposal.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the concrete consequence the agent needs: the journey's steps, emails included, run for the contact immediately. That explains why the operation is destructive and irreversible in a way the hints alone do not. It still omits what happens for paused/draft journeys or on re-enrollment.

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

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

A single front-loaded sentence with no filler; the side effect is stated before the reader can stop. The second clause ('its steps, emails included, then run for them') is slightly telegraphic but still earns its place by implying the email blast.

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

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

For a three-parameter destructive action with no output schema, the description covers the core action and consequence. It leaves open error/edge behavior (paused or draft journeys, duplicate enrollment, what is returned), which an agent would need before confidently calling it.

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 every parameter carries its own description, including the non-obvious confirm gate. The description adds nothing about individual parameters beyond the word 'one' implying contactId is singular. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb and resource with scope: 'Adds one contact to a live journey now.' The qualifier 'live' implicitly separates it from test/draft journey tools and 'one contact' fixes cardinality. It stops short of naming a sibling explicitly, so differentiation is inferred rather than stated.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. 'Now, as the inbox's Add does' hints at immediacy but gives the agent nothing to route on versus test_journey, publish_journey, or list_journey_people.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent). The description adds meaningful behavioral context beyond that: both artifacts 'stay drafts for review' (so nothing is sent), and AI must be configured first. Return format is not covered, but the key behavioral facts are.

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

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

Three tight sentences, front-loaded with the core action, then draft status, then prerequisite. 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?

No output schema exists, and the description covers the essential behaviors (AI-generated, draft-only, trigger-delayed, AI prerequisite). It does not address ctaUrl or productId, but for a 5-param tool with 80% schema coverage this is close to complete.

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

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

Schema coverage is 80%, so the schema carries most parameter meaning and baseline would be 3. The description adds the timing semantics ('sends it a while after a trigger'), reinforcing the delayMinutes/trigger relationship and the brief's role, going slightly beyond the structured fields.

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

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

States specific verbs (write, build) and resources (follow-up email, draft journey) with the AI-generation angle made explicit. This clearly distinguishes it from create_journey, create_journey_from_recipe, and draft_reply_with_ai without opening their schemas.

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

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

Provides a prerequisite ('Needs the AI set up in Settings → AI'), which is useful context, but never states when to pick this over the sibling manual/recipe builders. Usage is implied rather than contrasted with 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds real behavioural context: output is grounded only in facts in the brief, the result is a non-sending draft, and AI must be configured first. It stops short of saying what a repeated call produces (new draft each time, consistent with idempotentHint=false) or whether the draft is retrievable afterwards.

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

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

Three short sentences, front-loaded with what happens, immediately followed by the two constraints that matter most (nothing sent; AI prerequisite). Zero padding or restated boilerplate.

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 7-parameter tool with a deep nested audience object and no output schema, the description covers the essential mental model: AI writes from a brief, result is an editable draft, nothing is delivered. What is missing is any hint of the return value (e.g. draft id) and the audience-targeting dimension, which the schema carries alone.

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 86%, so the schema already documents brief, ctaUrl, format, layout, audience and productId. The description reinforces the 'brief' semantics ('using only the facts in it') and the draft nature, but adds nothing for the nested audience object or the enum options, so baseline 3 is correct.

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

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

States a specific verb and resource ('has the workspace's AI model write a newsletter from a brief') plus the persistence outcome ('saves it as a draft'). It is clearly distinguishable from siblings like create_newsletter or update_newsletter by being AI-generated rather than manually authored, though it never names those siblings explicitly.

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

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

Gives a prerequisite ('Needs the AI set up in Settings → AI') and an outcome constraint ('Nothing is sent'), which frames the intended workflow: produce a draft for human review. However, it never says when to choose this over create_newsletter / write manually, nor what to do next (preview, schedule, update) once the draft exists.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds value by disclosing that the result aggregates three distinct sources, but says nothing about ordering, pagination behavior, or freshness beyond 'recent', which are relevant for a feed-style read.

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

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

A single, front-loaded sentence with no filler; the resource path and content list are immediately scannable. Slightly dense with parenthetical detail but every element earns its place.

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

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

For a read-only, single-optional-parameter aggregator with no output schema and fully covered annotations, the description conveys enough to call it correctly and anticipate the kind of data returned. Missing only ordering/recency-window details that an agent might reasonably want.

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?

Only one parameter (limit), and the schema description already states the default (25) and maximum (100) at 100% coverage. The description adds no additional meaning about how limit affects the aggregation across the three sources, so the baseline of 3 applies when the schema does the work.

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

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

Names a specific resource (Reports → Activity) and enumerates the three content types it surfaces: email deliveries, automation runs, and audit-log workspace changes. It is clear what the tool returns, though it does not explicitly differentiate itself from close siblings like get_audit_log or get_reports, which overlap with the 'latest workspace changes' portion.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives (e.g., get_audit_log for a deeper audit trail or get_reports for aggregate metrics). The agent must infer from the content list that this is a general recent-activity overview.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description earns extra credit by disclosing the return payload (including the time-scoped 'last week's answers by confidence') that exists nowhere else since there is no output schema. It still omits auth requirements and response format details.

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 dense, front-loaded sentences listing exactly what is returned with a clarifying parenthetical for the handoff threshold. No filler or repetition.

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

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

For a zero-parameter, no-output-schema getter, the description covers most of what an agent needs by enumerating returned fields. It stops short of noting scope boundaries relative to get_ai_settings or the shape/limit of the weekly answer statistics.

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

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

The tool takes zero parameters, so the baseline is 4. No parameter guidance is needed or missing.

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 precisely enumerates what the tool returns – agent name, tone, instructions, handoff threshold, low-confidence handling, allowed tools, plus last week's answer stats – so an agent knows exactly what resource it retrieves. However, it never states purpose with a verb or distinguishes itself from the adjacent get_ai_settings/update_agent siblings, leaving the boundary to inference.

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

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

There is no when-to-use guidance, no prerequisite, and no mention of alternatives. Given siblings like get_ai_settings and update_agent, the reader gets no help deciding which to call for agent configuration vs. global AI settings.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is met structurally. The description adds a genuinely useful behavioral fact beyond them: the OpenRouter key itself is never returned, only its connection status — important for an agent reasoning about secrets. It stops short of noting auth/permission requirements.

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 compact sentence with no filler; every listed field earns its place. It reads as a fragment rather than a full clause, which slightly hurts front-loading clarity, but the density is appropriate for a trivial read tool.

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

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

With no output schema, the description compensates by listing the returned values, and annotations cover the safety profile. What remains missing is any statement of permissions or whether an unconnected key yields a partial result, but for a zero-arg settings read this is close to 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?

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter behavior for a zero-arg call.

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 enumerates exactly what is read back — key connection status, model, monthly spending cap, daily training proposal cap, current usage — which pins down the resource and scope (workspace AI configuration). It is a verbless fragment, so it never explicitly says 'retrieves', but the field list makes the purpose unambiguous and separates it from the mutating sibling update_ai_settings.

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

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

There is no when-to-use guidance, no prerequisite, and no mention of the obvious alternative (update_ai_settings) or related reads like list_ai_models or get_training_overview. The agent must infer the call context entirely from the 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that results include the app address, per-page entries, and last-taken timestamps, which is useful context, but it says nothing about empty states (no captures yet), pagination/size of the page list, or whether image data is returned — the questions an agent would actually have.

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 compact sentence with no filler, front-loaded with the resource and followed by the fields returned. It loses a point because the colon-list construction never resolves into a complete clause, which makes the intent slightly harder to parse than a plain 'Returns …' phrasing.

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 only one parameter, full schema coverage, and complete annotations, the definition is nearly adequate. Because there is no output schema, however, the description carries the whole burden of explaining returns, and it leaves the key question unresolved: whether this yields actual screenshot assets or just metadata about them.

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

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

There is a single required parameter with 100% schema description coverage, and the schema already points to list_products as the source of productId. The description's phrase 'the product's app' is consistent with that scoping but adds no syntax, format, or lookup detail beyond the schema, so the baseline 3 applies.

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

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

The text names the resource (screenshots HelpWell captures of the product's app for articles) and enumerates indicative fields, but it is a verbless noun phrase — it never says 'returns' or 'lists', so it reads like a return-value note rather than a statement of what the tool does. It also fails to distinguish this read from the closely named siblings retake_app_screenshots and update_app_screenshots, and leaves ambiguous whether image binaries or only metadata/URLs come back.

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

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

No when-to-use guidance is given and no alternative is named. An agent must infer that this reads existing captures while retake_app_screenshots regenerates them and update_app_screenshots edits them, purely from those sibling names.

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

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

Annotations already establish read-only, idempotent, non-destructive, non-open-world behavior, so the bar is lower. The description still adds real behavior beyond them: newest-first ordering, a fixed 50-item page, and the cursor-paging contract via nextBefore.

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

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

Two tight sentences, front-loaded with what the log contains and how results are ordered, then filter and paging mechanics. Every clause earns its place with no filler.

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

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

For a read-only tool with no output schema, the ordering, page size, filter dimensions, and cursor source are all disclosed; annotations carry the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only loosely maps fields to filters ('teammate' → actor, 'action', 'dates' → from/to) and adds the minor fact that nextBefore originates from a reply, but no syntax or format detail beyond the schema.

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

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

States a specific resource and scope: 'Who changed what in the workspace' with ordering ('newest first') and page size. It's clearly the audit-log reader, distinct from the similarly named get_activity, though it never names a sibling to explicitly delimit the boundary.

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?

Tells the agent how to narrow results ('filter by teammate, action or dates') and the exact way to page backwards ('pass nextBefore from a reply'). It gives clear operational context but no when-not-to-use or alternative-tool guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful operational context that billing changes happen outside this tool via settings_link. Beyond that it discloses no rate limits, auth requirements, or freshness behavior, and 'Read only' restates the annotation.

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

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

Two sentences: the first front-loads the returnable data, the second carries the read-only/routing constraint. It is dense but every clause earns its place, with no filler or redundant restatement of the title. Slightly list-heavy, which keeps it from a 5.

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

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

There is no output schema, so the description correctly enumerates the key returned fields (plan, state, trial end, seat/contact counts, usage), which an agent needs. With rich annotations, zero params, and a routing note for mutations, the definition is nearly complete; only edge behaviors (e.g., what happens with no active plan) are unaddressed.

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

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

The tool takes zero parameters (empty schema, 100% coverage), so there is nothing for the description to disambiguate. Per the baseline for a 0-parameter tool, a 4 is appropriate; no parameter-level gaps exist.

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 specifies the resource and the exact contents returned: plan and state (trial, active, past due), trial end, seats and marketing contacts used/included, and usage. Combined with the title's 'Get billing status', the purpose is unmistakable and distinct from near-neighbors like get_setup_status or get_reports. It stops short of an explicit verb-led scope statement, but the content list pins it down well.

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

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

It gives a clear use context ('Read only') and routes the agent away from mutation by naming settings_link page "billing" as where billing is managed. That is an explicit when-not-to-use signal with an alternative. It does not, however, say when to reach for this vs. other status/summary tools, so it falls short of a full 5.

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