MentionAgent

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: 'Sends nothing' clarifies no outward side effects, and 'Ones nobody has searched yet go first on the next run' discloses queue-ordering behavior not visible in annotations or schema.

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

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

Four short sentences, front-loaded with the verb and examples, then limits, then scheduling behavior, then no-send clarification. Every sentence carries information; only minor stylistic trimming would be possible.

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-destructive write tool with no output schema, the description covers purpose, limits, side-effect-free behavior, and queue semantics. What it omits (how the added keywords are confirmed back, whether duplicates are rejected) is minor given idempotentHint=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 baseline is 3, but the description adds constraints the schema lacks: the 25-per-call cap and the 2-9 word length bound. That materially constrains how the agent populates both parameters.

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

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

States a specific verb (Add) and resource (Google search keywords for discovery), with two concrete examples that make the intent unmistakable. An agent can distinguish it from list_keywords and remove_keywords 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?

Explains the context clearly ('search that should turn up sites that could link to this one') and gives hard limits (25 per call, 2-9 words). It stops short of naming alternatives like remove_keywords or list_keywords, so there is clear context but no explicit when-not guidance.

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

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

The description discloses the real consequences of each input value: live:true closes the thread as a won deal and live:false drops the question. This adds meaningful state-change context beyond the annotations, which only flag destructiveHint=true and readOnlyHint=false without saying what is destroyed or changed.

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 action, then the consequence of the flag, then the precondition. Every sentence earns its place with no waste.

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

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

For a mutation tool with annotations and no output schema, the description covers purpose, input sourcing, side effects, and a usage precondition. It omits permissions/auth requirements, but the core information an agent needs to call it correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value: it explains what each value of live actually does (won deal vs. dropped question) and where conversationId comes from, going beyond the schema's terse 'true if the link is on the page' and 'From list_links.'

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: answering a checker's question about a page it could not read, and names the sibling list_links as the source of the input. This is far clearer than a generic 'answer' tool, though it relies on domain jargon ('checker') that an agent must infer from context.

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

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

It gives explicit routing ('using a conversationId from the could not read section of list_links') and a precondition ('Only answer after the person has looked at the page, not from a guess'). It doesn't name an alternative tool to use instead, but the sourcing and precondition guidance is strong.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one useful behavioral fact, that every value is re-validated before writing, but says nothing about what is destroyed, reversibility, or failure handling.

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 the source of the input. Each sentence carries weight, though the re-check sentence is somewhat tangential to invocation.

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 gives no indication of what applying returns, whether partial failures are possible, or how to recover from a rejected change set. For a destructive mutation this leaves a noticeable gap.

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

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

Schema coverage is 100% with descriptions for both parameters, so the schema does the heavy lifting. 'Pass the changes back exactly as they came' reinforces the schema's 'unmodified' wording but adds no new syntax or format detail, matching the baseline 3.

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

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

States a specific verb+resource ('Makes the changes') and immediately ties it to the sibling plan_campaign_change, making the plan/apply relationship explicit. An agent can tell it apart from plan_campaign_change 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?

Strongly implies the prerequisite flow ('the changes that plan_campaign_change worked out' and 'Pass the changes back exactly as they came'), so the agent knows this must follow a plan call with unmodified output. It lacks an explicit when-not or fallback alternative beyond that single workflow.

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 destructive, non-idempotent, open-world behavior, and the description reinforces this with high-value context the annotations cannot convey: 'SENDS REAL EMAIL', delivery to real people, staggering over time, and 'It cannot be undone.' This is exactly the behavioral weight a destructive tool 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?

Four short sentences, front-loaded with the most important fact ('SENDS REAL EMAIL') and the irreversible warning trailing. No filler; every clause either warns, instructs, or constrains.

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

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

For a two-parameter destructive send tool with full annotation coverage, the description supplies the consequence, the preparatory workflow, and the irreversibility note. No output schema is needed or expected here, and nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema itself (batchId provenance from list_pending_drafts, workspaceId via get_status). The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('approves every draft still pending in the batch and starts delivering them') with scope made unambiguous. It clearly differentiates from siblings like list_pending_drafts, discard_draft, and skip_batch without requiring the schema.

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

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

Explicit prerequisites are given: show drafts via list_pending_drafts, obtain the person's agreement, and discard unwanted items before calling. The when-not path (discard first) and the alternative surface (list_pending_drafts) are both named.

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

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

Annotations already declare non-destructive and idempotent behavior, so the bar is lower, yet the description still adds genuine value: 'Nothing is deleted and no email is sent' confirms the non-effect, and it discloses the observable side effect on list_inbox results. It omits any auth/permission requirements or confirmation that the change 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?

Three short sentences with zero filler, and the primary effect (inbox visibility) is front-loaded before the usage guidance. 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 a two-parameter, non-destructive mutation with no output schema, the description covers effect, safety, and usage context adequately. It could be richer about reversibility and whether unarchiving restores prior inbox position, but nothing critical to 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%, so the schema already documents both conversationId and the archived boolean including its default. The description only implies the bidirectional archive/unarchive behavior ('or brings it back') without adding format or sourcing 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?

States a specific verb (archive/unarchive) and resource (conversation/thread), and explicitly frames the effect against a named sibling: 'so list_inbox stops returning it.' An agent can distinguish this from redirect_thread or mark_deal without opening a schema.

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

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

Gives clear when-to-use guidance ('Use it once a thread is dealt with, so the inbox reflects what still needs attention'), which is strong contextual framing. It does not name the reverse alternative (unarchive) as a separate routing decision or list exclusions, so it falls just short of explicit 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 establish readOnlyHint=false and idempotentHint=true. The description adds traits beyond annotations: subdomain coverage ('each covers its subdomains'), a rate limit ('Up to 500 per call'), and an important safety reassurance ('Sends nothing'), which tells the agent no outreach is triggered. Missing detail on reversibility or return behavior, but the additions are substantive.

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

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

Four tight fragments with zero waste. The verb and object are front-loaded, and behavioral facts (subdomains, 500 limit, 'Sends nothing') follow 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 write tool with no output schema, the description covers scope, capacity, format and side effects adequately. It lacks explicit undo/reversibility guidance and any pointer to unblock_domains, but is otherwise sufficient to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema: 'Bare domains or URLs' clarifies accepted input format and 'each covers its subdomains' documents scope behavior the schema does not.

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 domains outreach must never contact.' An agent can tell it adds to a blocklist rather than removing. Sibling differentiation from unblock_domains/list_blocklist is only implicit via the opposite verb, not explicitly named.

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

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

Gives concrete usage context via examples (competitor, partner, client), which implies when to use it. However it never names the alternative unblock_domains or states when NOT to use this tool, 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 and idempotentHint=true, so the safety profile is covered. The description still adds value beyond them by stating the action is irreversible ('cannot be undone') and by naming the blast radius ('the rest of the batch is unaffected').

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, each earning its place: what happens, what is not affected, and the irreversibility warning. Front-loaded with the core action and 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 one-parameter mutation with no output schema and full annotation coverage, the description covers action, scope, and permanence. Only minor omissions remain, such as behavior when the draft has already been sent or the id, but nothing essential to 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%; the single parameter is documented in the schema and points to list_pending_drafts as the source. The description adds no further parameter 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 specific verb and resource ('throw away one draft') and immediately scopes it to a single item whose removal does not affect the batch. This clearly distinguishes it from sibling batch-level tools like approve_batch, skip_batch, and edit_draft.

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 — discard a draft you don't want sent — and the batch note hints at the batch-vs-single distinction, but no alternative is named explicitly (e.g. when to prefer edit_draft or skip_batch instead). Adequate but leaves the reader 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds a great deal beyond them: it spends credits, sends nothing, is asynchronous with a 1-4 minute runtime, follows the workspace's standing negotiation rules, and writes a placement record that other tools consume.

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 two highest-value facts (spends credits, sends nothing) and tightly packed, though the aside about the placement record and the negotiation rules adds length that is useful but not essential.

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 async, credit-spending, open-world tool with no output schema, the description covers cost, side effects, async contract, polling target, timing, and rule inheritance. Nothing an agent needs before invoking it 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 mode, pageUrl, guidance, skipPageUrls, avoidAfterTexts, and conversationId are already fully documented in the schema. The description only adds light usage framing ('Pass guidance to steer what it offers'), which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb and resource ('starts MentionAgent's own reply writer on one thread'), the immediate return ('returns a jobId'), and the follow-up tool to poll. It is clearly distinguishable from siblings like edit_draft, send_reply, and answer_link.

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

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

Explicitly says to use this rather than writing the reply yourself when a placement should be proposed, and warns 'do not write your own replacement while it runs'. It also cites the reason (site crawling and paragraph selection) that rules out the manual alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the 'not been sent' applicability constraint and the text-handling behavior ('Plain text is fine; line breaks are kept'), though it says nothing about 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?

Three short sentences, all front-loaded with the action and scope first, then the ID source, then formatting notes. 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?

There is no output schema and no nested parameters, so the description carries the remaining burden; it covers what is overwritten, where the ID comes from, and body formatting. It is slightly thin on error behavior (invalid ID, already-sent draft) for a destructive mutation, but adequate overall.

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 real meaning beyond the schema's terse 'The new body.': it clarifies that plain text is acceptable and that line breaks are preserved, which directly affects how the caller should format the body parameter.

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 ('Replace the subject and body of one draft') and constrains scope to a draft 'that has not been sent', which cleanly separates it from sent-mail tools and from draft creation tools like draft_reply. An agent can distinguish it from discard_draft, get_draft_reply, and draft_reply 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?

Gives the key prerequisite and routing hint: 'Get the draftId from list_pending_drafts,' and restricts applicability to unsent drafts. It does not explicitly contrast with discard_draft or state what to do if the draft was already sent, 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?

Goes well beyond the annotations by disclosing per-type return behavior (image→image, PDF/docx→extracted text, text/CSV→verbatim) and, crucially, which types are named but unreadable (spreadsheets, archives, old .doc). It also adds a prompt-injection warning that returned content is data, never instructions, which annotations cannot express.

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

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

Front-loads the core purpose and packs return formats, unsupported types, identifier sourcing, and a safety note into a tight block with no filler. It is dense but each clause earns its place; only the run-on length 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?

With no output schema, the description carries return-value explanation itself, enumerating what comes back for each file type and warning about untrusted content. Given the readOnly/idempotent annotations already cover the safety profile, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters and their sources are already documented in the schema. The description restates the get_thread provenance of messageId and index but adds no syntax or format detail beyond the structured fields, 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 (read) and resource (a file attached to a message) and defines scope as 'one file attached to a message in a thread'. It cleanly distinguishes itself from the sibling get_thread, which lists attachments rather than returning their contents.

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 establishes the workflow: 'get_thread lists each message's attachments with the messageId and index this takes', which tells the agent the prerequisite and the identifier source. It stops short of explicitly framing when to reach for this versus other read tools, but the routing context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds domain context about what the campaign holds but says nothing about scoping, caching, or auth beyond the workspace parameter. With annotations carrying the behavioral burden, this is adequate but not rich.

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

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

A single dense sentence front-loads the purpose ('what this site is currently saying and to whom') and then lists the concrete fields, ending with the actionable read-before-write cue. It is efficient, though the colon-list is somewhat packed.

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

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

For a one-parameter read tool with no output schema, the description does the job of enumerating what comes back (page, pitch, drafts per run, quiet hours, send days) and how to use it. Nothing critical for correct invocation is missing, though return shape details are 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?

Only one parameter exists and schema description coverage is 100%; the schema itself explains workspaceId and points to get_status for listing. The description adds no parameter guidance, which is acceptable given the schema does the work, so the baseline 3 applies.

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

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

The description enumerates the concrete contents of the campaign (linked page, pitch, drafts per run, quiet hours, sending days), which makes clear this is a read of the site's campaign configuration. It does not name a sibling tool it differs from, though 'read this before changing anything' implicitly positions it against the mutation tools like apply_campaign_change.

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

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

'Read this before changing anything' gives a clear read-before-write usage pattern that fits alongside set_run_settings, set_link_target, and apply_campaign_change. It stops short of naming those alternatives or stating exclusions, so it is strong context rather than a full routing rule.

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 non-idempotent/destructive, and the description explains exactly why: the result is handed over ONCE and re-asking after collection 'reads as expired'. It also discloses the 25-second blocking wait and the cancel semantics, which the annotations alone cannot convey.

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

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

Four tight sentences, front-loaded with the core action, then timing, then the one-time-consumption caveat, then the cancel escape hatch. No filler; every sentence changes how an agent would call it.

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

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

Despite no output schema, the description explains what comes back ('returns it or says it is still writing and for how long') and the full lifecycle including expiry. An agent has everything needed to drive the polling loop correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: jobId is the value returned by draft_reply, and cancel:true stops a run rather than collecting it. This goes beyond the terse schema text.

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

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

States a specific verb+resource ('Picks up the result of draft_reply') and immediately ties it to the sibling that produces the draft. An agent can distinguish this collector from draft_reply itself 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?

Explicitly describes the polling pattern ('Keep calling until it returns'), gives the timing envelope ('runs take 1 to 4 minutes', 25s per call wait), and provides an alternative path ('Pass cancel:true to stop a run'). When-to-use, how-long, and how-to-abort are all 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 readOnly=true, idempotent=true and destructive=false, so safety is covered structurally. The description adds real behavioral context beyond that by defining the aggregate contents of the diagnostic (pause reason, warmup stage, cap consumption, bounce rate, next run time), which matters because there is no output schema. It stops short of 5 by omitting auth/permission or rate-limit notes.

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 contents of the response and finished with the triggering question. The long enumeration is dense but every clause maps to a distinct returned field, so nothing is filler.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so field-by-field. Combined with the read-only annotations and full param coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the single workspaceId param is fully documented in the schema, including how to enumerate values via get_status. The description's phrase 'for one site' corroborates the scope but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource and scope ('for one site') and enumerates exactly what the tool reports: sending on/off, pause reason, warmup progress, daily cap and usage, bounce rate, next run. An agent can tell this apart from sibling setters like set_sending and resume_sending, which change state rather than report 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?

Gives an explicit use case with quoted user questions ('why are so few emails going out', 'why did it stop'), which is stronger than a generic usage statement. It does not name an alternative tool or a when-not condition, so it falls short of the 5 bar.

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, and non-destructive behavior, so the safety profile is covered. The description adds useful context that this doubles as a discovery call returning workspaceIds, but says nothing about auth requirements, rate limits, or freshness/staleness of the status 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?

Two sentences, front-loaded with what the tool reports and followed by the invocation tip; no filler. The first sentence is a dense enumeration but each item earns its place by describing returned content.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by listing the five categories of account state. For a read-only, single-optional-param tool this is nearly complete, missing only return format or pagination behavior.

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 workspaceId parameter, and the schema description already explains how to obtain it. The description only echoes that same instruction, adding no syntax, format, or behavioral 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 names a specific resource ('the account') and enumerates the exact contents returned: sites, drafts awaiting approval, threads needing a reply, sent emails, and remaining credits. This aggregation distinguishes it implicitly from the narrow siblings like list_pending_drafts and list_sent, 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?

It gives concrete, actionable invocation guidance: call with no arguments first to enumerate sites and obtain their workspaceId. That tells the agent how to bootstrap, but it doesn't state when to prefer this overview over the individual list_* / get_* 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: ordering (oldest first), the thread's starting point, and the presence of attachments. It stops short of stating pagination or size limits on long threads.

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 what is returned, followed by cross-references to get_attachment and send_reply. No filler or restated name/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 carries the burden of describing the return value, and it does so well (messages, sender, timestamp, attachments, ordering). It omits any note on thread length limits or truncation, which is the only material gap for a full-thread read.

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

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

Schema coverage is 100% and the single parameter is documented there ('From list_inbox.'). The description adds no syntax, format, or sourcing 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 and resource ('Every message in one thread') plus ordering, content, and the fact it begins with the cold outreach email. It is clearly distinguishable from list_inbox, get_attachment, and get_draft_reply 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 prescribes when to use it ('Use this before send_reply so the reply answers what they actually asked') and routes the agent elsewhere for a sub-task ('read one with get_attachment'). Both the trigger and the alternative are named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is semantic: blocking is suffix-wide (example.com covers blog.example.com) and already-emailed sites are deliberately excluded from the list. That exclusion is a non-obvious behavioral trait an agent could not derive from the schema or annotations.

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

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

Three short sentences, front-loaded with what the tool returns before qualifying semantics. The parenthetical example is justified because subdomain coverage is counter-intuitive; the 'never emailed again anyway' clause is slightly chatty but carries real information about list contents.

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

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

For a single-parameter read tool with full schema coverage and no output schema, the description explains what is and is not in the list, which is the main thing an agent could mis-infer. It omits any mention of ordering, volume, or pagination, which is a minor gap for a list tool.

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

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

Schema description coverage is 100% and the single workspaceId parameter is fully documented in the schema, including how to discover it via get_status. The description adds nothing about the parameter, so the baseline 3 for schema-covered parameters 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 exactly what the tool returns — the domains blocked for the current site — which is a clear resource and scope even though it uses a noun phrase rather than an explicit verb. It does not, however, name or contrast itself with the sibling block_domains/unblock_domains tools that operate on the same data.

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

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

There is no when-to-use or when-not-to-use guidance, and no routing to alternatives such as block_domains or unblock_domains. The agent must infer from the name and the readOnlyHint that this is the read counterpart, which is the whole of the guidance available.

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. The description adds real behavioral context the annotations do not: result ordering (newest first) and that each row carries only a short extract rather than the full thread. It stops short of describing batching/paging 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?

Three tight sentences with no filler: what it returns first, then filter semantics, then the sibling handoff. Every clause carries information an agent needs to choose the right tool and filter.

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 must sketch the return value, and it does (short extract of the last message). Paging is left entirely to the limit/offset schema fields and no mention is made of how many results come back by default, but for a read-only list tool the essentials are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining filter values the schema leaves unexplained: 'hot' (interested), 'paid' (they quoted a price), 'warm', 'cold' and 'deals'. That meaningfully disambiguates the enum beyond the structured field.

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

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

States a specific resource (threads where somebody replied) plus ordering (newest first) and payload shape (short extract of the last message), so the agent knows exactly what comes back. The closing sentence routes the agent away from this tool toward get_thread for full conversations, which cleanly separates it from the closest sibling.

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

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

Explicitly names the alternative (get_thread for the whole conversation) and gives an operational cue for the most common filter ('needs_reply' is the answer to 'what is waiting on me'). It does not state when NOT to use this tool beyond that single handoff, so it falls short of full when/when-not coverage.

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 safety is covered. The description adds genuinely useful domain context by explaining what 'active' vs 'retired' mean in this system, but it does not cover ordering, default limits, or what a result row contains.

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, but the first is an awkwardly phrased clause ('The Google searches discovery runs to find sites...') that does not front-load the actual action. The reader has to work to extract that this is a listing tool; the most important information is neither first nor clearly stated.

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 full schema coverage, read-only annotations, and no output schema, the definition is minimally sufficient: an agent knows how to filter and that the operation is safe. It is thin on return shape, ordering, and paging expectations, but those gaps are partly absorbed by the rich 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?

Schema description coverage is 100% — limit, offset, status, contains, and workspaceId all have descriptions including the default ('Default active'). The description's reference to 'contains' adds a workflow reason to use it but no syntax or semantic 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 name/title establish the verb+resource (list/search keywords), and the description explains that these are Google-search discovery keywords for a campaign, so the domain is clear. However, the opening sentence is a definition of what keywords are rather than a statement of what the tool returns, and the description never actually says it lists/fetches 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?

It gives one concrete usage hint ('Use contains to find the exact text before remove_keywords'), routing the agent toward the remove flow, and clarifies the active/retired filter semantics. But there is no explicit when-to-use vs. sibling guidance beyond that single callout, and no mention of paging through results.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds genuine context beyond them: the data is a nightly-checker snapshot (not a live check), some entries are live with follow status, and some pages failed to read and require human attention. It stops short of describing ordering, staleness windows, or result size.

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 actionable routing instruction is placed last after the scope. The first sentence is a dense four-item enumeration but every item earns its place by defining what 'links' 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 describing return content, and it does so by naming the four result categories an agent will see. Combined with annotations covering the safety profile and the schema covering the sole parameter, nothing needed to call or interpret this tool is missing.

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

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

There is a single workspaceId parameter with 100% schema description coverage — the schema already explains it and points to get_status for discovery. The description adds no further meaning about the parameter, so the baseline of 3 for fully documented params 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 resource (every link placement the nightly checker has seen for this site) and enumerates its scope precisely: live links with follow status, unreadable pages needing human review, removed links, and won deals lacking a link. This disambiguates it from siblings like list_blocklist or list_keywords without requiring the agent to open 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 explicitly routes one outcome subset: 'Answer the pages it could not read with answer_link' — a concrete when-to-use-this-alternative instruction. However, it gives no general guidance on when to call list_links versus other listing 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered structurally. The description adds real context beyond that: 'Nothing here has been sent' pins down the state of the returned records, and 'with the full text of each one' discloses payload richness. It omits pagination/volume behavior, keeping it short of a 5.

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

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

Two sentences, zero filler, and the core scope plus the unsent-state constraint are front-loaded ahead of the routing guidance. 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 single-parameter read-only list with no output schema, the description supplies what an agent needs: what is returned (full text), the record state (unsent), and the branch points to sibling actions. Nothing material is missing.

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

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

One required parameter at 100% schema coverage, so the schema already documents workspaceId fully, including how to discover valid values via get_status. The description adds nothing about the parameter, which is the expected baseline 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+resource+scope: drafts of outreach emails awaiting a decision, and explicitly says the full text of each is returned. It is distinguishable from siblings like list_sent, list_inbox, and get_draft_reply 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?

Names the exact alternatives and the condition for each: edit_draft to change one, discard_draft to drop one, approve_batch to send the rest. This routes the agent's next action precisely rather than leaving follow-up 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 read-only, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds useful context beyond that: the result ordering (newest first) and that this is scoped to a single site. It does not discuss pagination feel or return size caps, but those are partially schema-handled.

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 core resource and scope are front-loaded, followed by one clause of use cases and one routing clause. 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?

No output schema exists, and the description compensates by naming the returned data (recipient and timestamp, newest first). For a simple filtered-list tool with full schema coverage and annotations, this is nearly complete; only edge behavior like empty-result handling is unstated.

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 limit, offset and workspaceId are already documented, including a pointer to get_status for discovering ids. The description only implicitly maps 'one site' to workspaceId and adds no format or syntax detail, so baseline 3 applies.

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

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

States a specific resource (emails actually sent), its scope (one site), ordering (newest first), and returned fields (who and when). It is immediately distinguishable from list_inbox, which handles replies.

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

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

Gives explicit use cases ('what did we send', confirming a site was contacted) and names the alternative for a different need ('For replies received, use list_inbox instead'). Nothing is left to inference.

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

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

Annotations declare it is a mutating, destructive, idempotent operation; the description adds genuinely new context: it sends no email, it closes the agreed placement, and the action is reversible via done:false. This clarifies the reversibility of a destructive-hinted tool, which annotations alone do not convey.

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

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

Three short sentences, front-loaded with the core action and scope, followed by the email caveat and the reopen option. No sentence is filler.

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

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

For a simple two-parameter, no-output-schema mutation, the description covers what changes, that no email is sent, and how to undo. Adequate and complete; the only minor gap is not naming the sibling closer it overlaps with.

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 meaning beyond the schema by explaining the practical intent of done:false ('reopen one marked by mistake') rather than merely restating the boolean.

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 outcome: 'Records that the placement is done: the link is live, or the deal is agreed.' It separates itself from send_reply by noting it sends no email, though it does not explicitly contrast with the closer sibling archive_thread, leaving some ambiguity about which closing tool to pick.

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

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

Gives an explicit workflow rule ('say so to the other party with send_reply first') and a recovery path ('Pass done:false to reopen one marked by mistake'). Clear when-to-use context, but no statement of when not to use it versus archive_thread or redirect_thread.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so safety is covered; the description reinforces this with 'Writes nothing' and adds the preview-then-apply workflow context, which annotations cannot express. It does not mention failure modes or the 500-character input limit (that lives in the schema), so it is strong but not exhaustive.

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

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

Three tight sentences with no filler; the plain-English instruction and the 'Writes nothing' reassurance are front-loaded, and the follow-up call to apply_campaign_change comes last where it belongs.

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 return-value burden and does so ('get back exactly what would change'). Combined with the workflow instruction and the schema's parameter docs, an agent has everything needed to call it correctly and act on the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning by giving four concrete example values ('only send on weekdays', 'cut it to 10 a day', etc.) that illustrate the expected plain-English input format for 'change'. It says nothing further about workspaceId, which the schema already routes via get_status.

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 ('Describe a change ... and get back exactly what would change') and immediately pins the scope with 'Writes nothing.' It also names the sibling apply_campaign_change as the counterpart, so the agent can distinguish preview from commit without opening a schema.

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

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

Gives explicit sequencing: 'Show the result to the person, then call apply_campaign_change with the same changes to make it real.' That is both the when-to-use condition and the named alternative, with no inference required.

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=false, and the description goes well beyond them: it discloses that nothing is sent, that the original is closed as redirected, the refusal conditions (loop, repeat, opted-out or bounced address), and a referral-chain depth cap of three. That is exactly the operational context annotations cannot convey.

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

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

Front-loads the surprising fact ('Sends nothing') before the workflow, and every following sentence carries distinct information (new thread, close original, reply routing, refusal rules). Four sentences is slightly dense but there is 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 destructive, non-idempotent mutation with no output schema, the description covers the side effects (thread opened, original closed), reply-routing behavior, and all documented failure/refusal modes. Nothing an agent needs before calling it appears to be 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 explains all three parameters with their roles (name optional, email = named address, conversationId from list_inbox/get_thread). The description reinforces the referral semantics but adds no syntax, format, or constraint 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 and resource – opens a NEW thread to the referred address, carries the referral, and closes the original as redirected. It also explicitly distinguishes itself from send_reply and draft_reply, so an agent can tell what it does and does not do without opening either schema.

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

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

Gives an explicit trigger condition ('when somebody replies I am not the right person, talk to X') and an explicit routing exclusion ('it does not change where replies on the old thread go: send_reply still answers the person who referred you'). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare destructive=true, idempotent=true, so the safety profile is known; the description goes further and discloses non-obvious consequences: removed keywords are retained as history and won't be regenerated, and the pool never falls below the minimum a run needs. These are behavioral facts an agent cannot infer from structured fields.

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

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

Four short, front-loaded sentences with no filler, leading with the action and the text-matching rule before the alternative and constraints. A few fragments ('Up to 25 per call.') are terse but each 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 destructive, no-output-schema mutation tool, the description covers the action, matching semantics, the alternative route, history/pool side effects, and volume limits. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema documents both workspaceId and keywords; the description still adds value with the 'exact text as list_keywords shows it' matching rule and the 25-per-call limit, which is not encoded in the schema. Baseline 3 is exceeded by that extra constraint.

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 ('Stop discovery running these searches') rather than restating the name. It distinguishes itself from the sibling add_keywords by its inverse action and explicitly names plan_campaign_change as the tool for the adjacent case, so an agent can route 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?

Gives concrete selection guidance: exact text as list_keywords shows it, and a clear alternative (plan_campaign_change) for the case of removing a whole kind of site. It also caps the call at 25 keywords, which tells the agent how to batch.

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 safety (idempotent, non-destructive), but the description goes well beyond them: it explains that volume stays reduced while the rate is high and that a single additional bounce re-pauses the site. This post-call behavioral context is exactly what the schema and annotations cannot convey.

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

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

Front-loaded with the action and condition, then the disambiguation from set_sending, then the behavioral caveat, then the caller instruction. Every sentence carries distinct, non-redundant information with no padding.

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

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

For a single-parameter action tool with no output schema, the description supplies the trigger condition, the alternative tool, side effects, and a pre-call obligation. 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 with 100% schema coverage, and the schema already explains workspaceId plus how to enumerate sites via get_status. The description adds no further 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 (restart sending) applied to a specific resource (a site that paused itself over bounce/complaint rate), and explicitly distinguishes itself from the sibling set_sending. An agent can tell exactly what this does and what it is not.

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 the precise triggering condition (get_sending_health reports PAUSED automatically), names the alternative to use instead for the on/off switch (set_sending), and adds a caller obligation to explain the pause reason first. When-to-use and when-not are both explicit.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, but the description adds the concrete consequence: a real email leaves the building, the recipient and subject are inherited from the thread and cannot be changed, so the blast radius is exactly one existing counterpart. It also imposes a human-confirmation step, which is meaningful operational guidance beyond the annotation flags.

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

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

Three short sentences, all front-loaded with the highest-stakes information (real send) first, then the scope constraint, then the workflow. No filler and nothing repeated from the schema.

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

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

Covers the safety-critical context, the prerequisite, and the confirmation workflow, and no output schema exists so return values need not be described. It does not mention failure modes (e.g., replying to an archived or redirected thread), which would round it out for a high-consequence send 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 schema documents both parameters (body formatting, conversationId source), so the baseline is 3. The description adds the non-obvious fact that recipient and subject are deliberately absent parameters because they come from the thread, which explains why the parameter list is only two items.

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 (reply) on a specific resource (one conversation) and front-loads "SENDS REAL EMAIL" in capitals, which immediately separates it from draft_reply/edit_draft in the sibling set. The scope limitation (one conversation, recipient fixed) is spelled out, so an agent can tell what this tool can and cannot do 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 explicit prerequisite sequencing: read the thread with get_thread first, then confirm with the user before sending. It does not name draft_reply as the non-sending alternative, so the when-not-to-use routing is left partly implicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that: it reassures that the tool 'Sends nothing', and discloses validation behavior ('Offer terms with a dash or a word the emails may not use are refused'). It does not describe what is returned or whether changes are 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?

The purpose is front-loaded in the first clause and each following sentence adds real information (validation, no-send guarantee). The middle enumeration is a long run-on sentence that is dense but every element maps to a distinct parameter, so little is wasted.

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

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

For a 7-parameter mutation tool with no output schema, the description covers all fields, validation rules, and the side-effect profile. The only gap is that it says nothing about the result/confirmation returned after a change, though with no output schema that burden is reduced.

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

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

Although schema coverage is 100%, the description materially enriches it: character limits (400 for offerTerms, 200 for pricingDetails), the semantics of each enum value ('link' asks for a link, 'mention' asks for a brand mention only; 'default' is one-sided vs 'exchange' mutual), and the constraint that pricingDetails is the only figure the emails may quote. This is well 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?

The description states a specific verb ('Change') and resource ('how first emails are framed'), then enumerates the exact settings touched (offerTerms, offerInFirstTouch, outreachGoal, emailStyle, pricingDetails, fromName). This makes it clearly distinguishable from sibling setters like set_profile, set_run_settings, and set_sending, which govern different domains.

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 concrete invocation rule ('Pass only the fields to change') and clarifies per-field behavior (whether the offer goes in the first email or is held for the reply). It does not name alternative tools or state when this tool should not be used, 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 declare destructiveHint=true and idempotentHint=true, and the description adds genuinely non-obvious behavior: the page is fetched once and an erroring page is refused, [] clears phrases, and nothing is sent (no email dispatch). It stops short of explicitly saying the previously configured target page is replaced.

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 primary action and then the per-parameter rules. Every clause carries distinct information; nothing is repeated from the title or schema verbatim.

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

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

For a mutation tool with no output schema, the description covers the important call-time behavior (validation, clearing semantics, no send side effect) and the schema covers workspaceId resolution. Only minor gaps remain, such as success/failure reporting and any 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?

Schema description coverage is 100%, so the baseline is 3. The description does add a real constraint absent from the schema ('up to 3 phrases of up to 3 words') and clarifies path vs same-site URL vs empty string, but the schema already carries the core meaning of each field.

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

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

States a specific verb+resource: choosing the page outreach asks for links to, plus optional anchor phrases. It is clearly separable from siblings like list_links, add_keywords, or set_profile, which operate on different resources.

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

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

Gives clear context for when each input applies: omit 'phrases' to keep current ones, pass [] to clear them, use an empty string on 'page' for the homepage. It does not name an explicit alternative tool for related tasks, but the operating context is unambiguous.

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

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

Annotations already carry destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds real behavioral context beyond them: the REPLACE semantics for competitors/audiences (what actually gets overwritten), size caps (20 items / 120 chars), the temporal scope ('Applies to drafts written from now on'), and 'Sends nothing' (consistent with openWorldHint=false). Nothing here contradicts the annotations.

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

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

Front-loaded with the core effect and zero filler; the destructive REPLACE warning is placed prominently. The opening sentence is dense with a mid-sentence parenthetical that makes it slightly harder to parse than the ideal, but every sentence 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?

Complete for a mutation tool with no output schema. It closes the gaps an agent would otherwise have: what replaces vs. merges, required preparation (get_campaign), what is immutable (the website), and when changes take effect (future 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 coverage is 100% so the baseline is 3, but the description adds constraints absent from the schema: array cardinality limits of 20 competitors and 20 audiences. The explicit callout of REPLACE-list behavior is partly redundant with the schema's 'Replaces the list' text, which keeps this from a 5.

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

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

States a specific verb ('Change') and resource ('the profile every outreach email is written from') and enumerates exactly which fields are editable (niche, competitors, differentiator, audiences), each with an inline gloss. An agent can distinguish this from siblings like set_email_settings or set_link_target without opening a schema.

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

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

Gives explicit operating instructions: 'Pass only the fields to change', 'read get_campaign first and pass the full list with your edits' (naming the sibling to consult), and an exclusion ('The website itself cannot be changed here'). When-to-use and constraints are stated rather than inferred.

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

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

With annotations declaring destructiveHint=true and idempotentHint=true, the description still adds non-obvious behavior: autoSend sends batches without review and requires human confirmation, and ineligible sites queue the request until warmup completes. It does not explain reversibility of a schedule change or how queued requests appear 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?

Front-loads the purpose in the first clause, then handles parameter semantics, the autoSend danger, and the eligibility edge case in tight sentences with no filler. The opening sentence is slightly redundant but everything else 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 partial-update mutation tool with annotations covering the safety profile and no output schema, the description covers the remaining gaps: which fields change, the destructive autoSend effect, the human-confirmation requirement, and deferred application for ineligible sites.

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 meaning beyond it: preferredHour of -1 explicitly 'clears' the setting, frequency is tied to 'discovery and drafting' runs, and autoFollowup targets 'sites that went quiet.' These are semantic clarifications, not just restatements of the enum.

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

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

Opens with a specific verb+resource: 'Change the run schedule and automation,' which frames exactly the fields in the schema (frequency, preferredHour, autoFollowup, autoSend). It is distinguishable from siblings like set_sending or trigger_run, though it never names those alternatives to sharpen 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?

Gives real usage rules: 'Pass only the fields to change' (partial-update semantics), 'confirm with the person before turning it on' for autoSend, and 'Turning it off is always allowed.' It lacks an explicit when-to-use-this-vs-sibling statement, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and non-readOnly, so the safety profile is covered. The description adds valuable grain beyond that: what actually gets suppressed (new drafts and cold emails), what is deliberately left alone (existing conversations), and that an in-flight batch is not canceled — all non-obvious side-effect scoping.

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 primary effect is front-loaded before the exception clauses. Every clause carries information about behavior an agent would otherwise have to guess.

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 boolean toggle with no output schema, the description plus annotations are nearly sufficient. The remaining gap is the unaddressed relationship to resume_sending, which an agent would need before choosing between 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?

Schema description coverage is 100%, so both parameters are fully documented in structured form (enabled: true to send/false to stop; workspaceId points at get_status). The prose adds no additional parameter meaning, 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 action (stops or restarts) on a specific resource (new outreach for one site), which is genuinely clearer than the title alone. It does not, however, distinguish itself from the sibling resume_sending, which appears to cover the same 'turn it back on' half of this tool's job.

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 defines the operational scope of the off state (no new drafts, no new cold emails) and explicitly what it does not affect, which helps an agent reason about when toggling is appropriate. But it never routes the agent between this tool and the obvious alternative resume_sending, nor states prerequisites beyond the schema-level hint to call get_status for a workspaceId.

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 behavioral facts those annotations cannot convey: paying accounts get draft credits back, the batch matches what the user saw in list_pending_drafts, and the action cannot be undone. This is exactly the extra context the safety profile alone lacks.

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

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

Four short sentences, front-loaded with the destructive intent, then the credit-refund consequence, then the sibling alternative, then the batchId source. Every clause carries distinct operational information 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?

No output schema exists and the description needn't describe returns; for a 2-required-param destructive tool it covers scope, irreversibility, credit refund, alternative tool, and parameter sourcing. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description restates the batchId provenance from list_pending_drafts but adds no new syntax, format, or constraint 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 (discard) and resource (every draft still pending in the batch) with the scope spelled out as 'every ... so none of them go out'. It explicitly contrasts with the sibling discard_draft, so an agent can differentiate 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?

Names the alternative tool (discard_draft) and the condition that selects it ('to drop just some'), and directs the agent to list_pending_drafts as the source of batchId. Both when-to-use and the alternative route are 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?

Goes well beyond the annotations: discloses credit consumption ('SPENDS CREDITS'), scope of side effects ('sends nothing'), latency and return semantics ('takes several minutes; this returns as soon as it starts'), where results surface (get_status), and a hard precondition that blocks invocation. The annotations only give generic mutation/open-world hints; the description supplies the operational detail that actually governs correct use.

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

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

Front-loads the core action, then layers cost, side-effect scope, async behavior, and the blocking precondition in dense, non-redundant sentences. Every sentence changes how an agent would call the tool; nothing is 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?

No output schema, yet the description compensates by telling the agent the call returns immediately and that get_status is where drafts appear. Combined with the cost and refusal preconditions, an agent has everything needed to invoke this correctly and interpret the empty-looking immediate return.

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?

Single required parameter with 100% schema description coverage, so the schema already carries the workspaceId semantics ('Which site to act on... call get_status to list them'). The description's 'for one site' adds framing but no new parameter-level detail. Baseline 3 for high coverage.

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

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

States a specific verb+resource ('Starts a discovery and drafting run for one site') and immediately distinguishes it from the scheduled equivalent ('instead of waiting for the next scheduled one'). An agent can tell this apart from sibling tools like approve_batch or plan_campaign_change 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 frames when to use it (immediate run vs. waiting for the schedule) and when it will fail ('Refused while a batch is already waiting for approval, so deal with those first'). It stops short of naming the specific sibling to invoke for that pending batch, leaving the agent to infer approve_batch/skip_batch/list_pending_drafts.

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, so safety is covered. The description adds genuinely non-obvious behavior: a domain already emailed by the site stays uncontactable and only its subdomains are unblocked. That is high-value context beyond annotations, though reversibility of the operation itself is not spelled out.

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 no filler, and the core action is front-loaded before the caveat and the limit.

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

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

For a destructive, idempotent mutation with no output schema, the description covers the action, sourcing rule, partial-effect caveat, and batch limit. Return behavior is unspecified, but that is a minor gap 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 description coverage is 100%, so the baseline is 3, but the description adds the batch ceiling of 100 domains per call, which is not present in the schema, plus the sourcing rule for the domains array.

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

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

States a specific verb and resource ('Remove domains from the blocklist') and immediately scopes it against the sibling list_blocklist by requiring its exact text. An agent can distinguish this from block_domains and list_blocklist 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?

Clearly signals the workflow (use the exact domain text that list_blocklist returns) and states a per-call cap of 100. It does not explicitly name block_domains as the inverse or describe preconditions, but the context is clear.

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