Deskhand

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 contributes the write_crm scope requirement, which is real authorization context not in the annotations. It does not disclose validation behavior such as rejecting conflicting targets, which keeps it below a 5.

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

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

A single short sentence front-loads the action and targets, then appends the auth precondition. Nothing is redundant and nothing wastes space.

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

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

For a simple one-required-parameter mutation with full annotation coverage and full schema coverage, the description supplies what structured fields don't: the auth scope. The remaining gap is the target-selection rule, which is the one thing an agent could get wrong when calling it.

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

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

Schema description coverage is 100%, so every parameter including idempotency_key is already documented in the schema, setting the baseline at 3. The description only adds a parenthetical that contact can be identified by id or email, without explaining mutual exclusivity or precedence between deal_id, contact_id and contact_email.

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

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

The description gives a specific verb and resource ('Attach a note') and names the two target types (contact or deal), so an agent knows exactly what the tool does. No sibling tool writes notes, so there is no realistic confusion to dispel, though it never explicitly contrasts itself with neighbors like update_contact.

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

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

It states the applicable context (contact by id or email, or a deal) and the required scope, which is useful preconditions info. However, it never says what to do when both a contact and a deal are supplied, nor that exactly one target must be chosen, leaving the main usage decision 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?

Adds substantial context beyond the annotations: it discloses the side effect that open enrollments of matching contacts stop, the irreversibility within the tool (removal needs the operator), and the required manage_campaigns scope. These are exactly the behavioral traits an agent needs before invoking a mutation.

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 effect, followed by side effects, reversibility, and auth. Every sentence earns its place with no repetition or filler.

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

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

For a mutation tool with no output schema, the description covers the effect, side effects, irreversibility, and authorization requirements, while all parameters are fully documented in the schema. Nothing an agent needs to call it correctly is missing.

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

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

With 100% schema description coverage, the schema already documents value, reason, and idempotency_key. The description reinforces that value can be an address or domain but adds no further syntax, format, or edge-case guidance beyond what the schema provides, 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 precise effect — permanently preventing email to an address or domain across all campaigns — which is a specific verb+resource with scope. It is clearly distinguishable from list_suppressions and all other siblings.

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

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

The description gives clear context for use ('never email this address or domain again') and notes that removal requires the operator, implying this tool is one-way. It does not explicitly name an alternative (e.g., list_suppressions) or state when not to use it, keeping it 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by clarifying that sent_dry represents dry-run records where nothing was delivered and that rates identify their denominator. It does not cover authentication or rate limits, but it meaningfully supplements the annotations.

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

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

The description is a single, front-loaded sentence that immediately states the aggregation dimensions and then enumerates the metrics. Every phrase contributes to defining the report contents, and the final clause about rates clarifies denominator semantics without excess. There is no repetition or wasted text.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by enumerating all count categories and mentioning rates. The breakdown dimensions (per campaign, per step, per variant) are stated. It stops short of detailing the exact response structure or nesting, but it is sufficiently complete for an agent to understand what the tool returns.

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 only one parameter, campaign_id, and the schema description coverage is 100%, so the schema already carries the parameter burden. The description does not add any syntax, format, or constraint details beyond what the schema provides. A baseline score of 3 is appropriate when the schema fully documents 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?

The description clearly states that this is a reporting tool returning campaign metrics broken down per campaign, step, and variant. It enumerates the specific counts and rates, which distinguishes it from simple retrieval tools like get_campaign. It does not explicitly name siblings, but the resource and output are specific enough for an agent to identify the tool's purpose.

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

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

The description explains what the report contains but gives no guidance on when to use it versus alternatives such as get_campaign, list_campaigns, or simulate_campaign. There are no prerequisites, exclusions, or contextual triggers mentioned. The agent must infer that this is the analytics/reporting option from the metric list alone.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=true) by disclosing that creation only produces a draft, that delivery is a dry run until the operator enables sending, and that an approval/scope gate applies. It also explains stop-rule semantics (reply, bounce, unsubscribe, deal stage change) that materially change runtime 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?

Front-loaded with the core definition and the lifecycle guidance, with no filler sentences. The opening sentence is long and densely packed with feature nouns, but every clause carries information an agent needs.

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

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

For a 15-parameter nested-object tool with no output schema, the description covers the lifecycle, the dry-run safety model, scope requirements and inline step/enroll semantics. It does not describe what is returned (presumably a campaign id) or the default identity/strategy approval flow in detail, 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 coverage is 93%, so the baseline is 3, and the description adds real meaning on top: 'pass steps inline', 'enroll selects contacts in the same call using the same selectors as enroll_contacts', and the stop_on values are explained as things that halt a contact's sequence rather than just enumerated.

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 and then defines what a campaign actually is (an ordered sequence of email, wait and task steps run per contact, with stop rules, send window, caps and A/B variants). That definition distinguishes it from siblings like update_campaign or launch_campaign, which operate on an already-existing campaign.

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: the campaign starts as a draft, then call simulate_campaign, then launch_campaign — that is genuine routing guidance. It also states the required manage_campaigns scope. It stops short of naming when to prefer update_campaign over creating a new one, so not quite 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?

Adds real value beyond the annotations: the write_crm scope requirement, the fact that unknown arguments are rejected with unknown_field, and the precedence rule that the deal inherits the contact's company unless company_id is given. It does not say what the call returns (no output schema exists), which keeps 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?

Three tight sentences, front-loaded with the action and linkage, followed by defaults and the failure/scope constraints. No filler and nothing repeated for its own sake.

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 10-parameter mutation tool with no output schema, the description covers defaults, error behavior, auth scope, and linkage precedence. The only gap is the shape of the success response (e.g. returned deal id), which an agent needs for follow-up calls.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds semantics the schema lacks, namely the contact/company inheritance interaction and that contact may be identified by email as an alternative to id. Stage values are repeated from the schema but the interaction rules are new.

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 ('Open a deal') plus its linkage scope (contact by id or email, company), which lets an agent distinguish it from move_deal and the create_* siblings without opening the schema.

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

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

The description gives useful context (contact can be supplied by id or email, stage values are enumerated) but never names an alternative tool or a condition for choosing this over upsert_contact / move_deal. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false. The description adds genuine value with the 'Requires the manage_tasks scope' auth prerequisite, but it does not say what happens when neither contact_id nor deal_id is supplied, whether both may be supplied, or what a successful call returns.

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

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

A single tight sentence with no filler, front-loading the action and resource, then the optional due date, target scope, and auth requirement. Nothing could be removed without losing information.

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

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

For a creation tool with no output schema, the description covers the action, target, and permission requirement but is silent on the return value (e.g., a task id) and on the contact_id/deal_id exclusivity rule. Adequate to trigger a correct call, but with notable remaining gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by establishing that the task belongs to 'a contact or a deal' — a constraint the schema itself does not enforce, since only title is required. It also flags the due date as optional.

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

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

The description gives a specific verb and resource ('Create a follow-up task or reminder') plus its attachment scope ('on a contact or a deal'), which clearly separates it from siblings like add_note or list_due_tasks. It stops short of naming a sibling explicitly as the alternative, so it is clear but not maximally differentiated.

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

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

The description implies when to use it (when a follow-up or reminder is needed on a contact or deal) and states the required manage_tasks scope. However, it never excludes alternatives such as add_note for plain notes or list_due_tasks for reading them, leaving selection between siblings 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 only declare write/idempotent/non-destructive; the description goes far beyond by disclosing the approval workflow, the 'To send' holding state, the contact_suppressed refusal condition, and the warning code vocabulary. It also names the required draft_email scope, 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?

The core action and the approval consequence are front-loaded, and nearly every sentence carries non-obvious operational detail. It is a single dense paragraph though, with warning-code enumeration mid-stream that could be structured for faster scanning.

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

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

With no output schema, the description compensates by naming the response fields (warnings codes, prior_emails) and explaining what each signals. Combined with refusal conditions, scope requirements, and argument rejection behavior, an agent has everything needed to call this correctly and interpret 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 the baseline is 3, and the description adds real semantics: contact_id and to are alternatives, one recipient only, plain-text body with platform-added footer. It loses a point because its 'accepts only contact_id (or to), subject, body' enumeration omits idempotency_key, which the schema documents and the annotations advertise as idempotent — a minor inconsistency an agent could trip over.

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

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

The opening sentence states a specific verb and resource ('Draft one email to a contact') and immediately bounds scope: one recipient, plain text, no attachments. No sibling in the list (add_note, list_email_status, campaign tools) could be confused with this operation.

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

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

The description gives concrete usage context: drafts are auto-approved unless the operator enabled approval, and 'check them before drafting a second message to the same person' is an explicit precondition. It never names an alternative tool or an explicit case where you should not draft at all, 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?

Adds substantial context beyond annotations: the exact classes of contacts that get skipped (suppressed, replied, unsubscribed, bounced, address-less, blocked-domain), the fact that skip reasons are returned, the cross-campaign conflict behavior, and the required manage_campaigns scope. Annotations already flag a non-destructive idempotent write, and the description complements them with consequences and auth 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?

Three tight sentences with the targeting modes first, consequences second, and the dry_run preview plus auth requirement last. Every clause carries information; nothing is padding.

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

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

No output schema exists, and the description compensates by stating what dry_run returns and that skips come back with reasons. For an 11-param mutation with auth requirements and conflict handling, an agent has enough to invoke it correctly.

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

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

Schema coverage is 91%, so the schema already documents nearly every parameter, and the description mostly restates them as a selector list rather than adding syntax or format detail. It does add value on two params — dry_run's return semantics and on_conflict's 'skip (default) or move' behavior — but the selector params get no extra meaning.

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

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

Specific verb ('Enroll') plus resource ('contacts') and an enumeration of the selectors that define the target set. An agent can distinguish this from stop_enrollment or launch_campaign by the verb alone, though no sibling is named explicitly.

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

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

'dry_run=true returns who would be enrolled and who skipped' tells the agent to preview before committing, and the on_conflict clause explains the skip-vs-move branch. It does not point at siblings like simulate_campaign or stop_enrollment, so the routing to alternatives is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds meaningful context beyond that by enumerating what the response contains, including the dry-run vs live delivery mode and counters. It does not mention behavior for an invalid or missing campaign_id, which keeps it from 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?

One short sentence, front-loaded with the core resource ('One campaign'), with no redundant or filler text. Every clause (steps, status, delivery mode, counters) adds information.

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

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

For a simple single-parameter read tool with full annotations and no output schema, the description covers the essential return contents. Only minor gaps remain, such as error behavior for an unknown campaign_id or whether the returned steps are paginated.

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

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

There is a single parameter with 100% schema coverage ('Campaign id.'). The description adds no syntax, format, or lookup semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: fetch 'One campaign' and returns its steps, status, delivery mode and counters. The singular 'One campaign' implicitly distinguishes it from list_campaigns and the mutation siblings, but no sibling is named explicitly.

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

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

Usage is only implied: an agent infers it should call this when it has a campaign_id and needs details for a single campaign. There is no explicit when-to-use/when-not-to-use guidance or reference to alternatives like list_campaigns or campaign_report.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation, and the description adds useful context about what the policy reveals, including approval behavior and daily cap usage. It does not discuss auth, rate limits, or return formatting, but with strong annotation coverage that is a minor gap.

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

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

The description is front-loaded with the core purpose and every listed item corresponds to a policy component the agent needs. It is somewhat long and list-like in a single sentence, but not redundant.

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

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

With no output schema, the description carries the burden of explaining return content, and it enumerates the policy components thoroughly. For a zero-parameter read tool with rich annotations, it provides enough context for an agent to call it confidently before drafting.

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 are zero parameters, so there is nothing for the description to clarify beyond the empty schema. Per the zero-parameter baseline, a 4 is appropriate.

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

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

The description uses a specific verb/resource and fully explains what policy data is returned: approval setting, agent mode, daily send caps, blocked domains, and non-mailable statuses. It is clearly distinguishable from sibling tools such as draft_email or simulate_campaign because it is the policy-reading tool.

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

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

It gives a clear usage condition: "Read it before planning a batch of drafts." It does not name explicit alternatives or when-not cases, but the sibling set contains no direct policy-read alternative, so the guidance is sufficiently 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description usefully adds the required auth scope and the time-ordered result shape. However, it is silent on result size/pagination and on what happens when all three optional identifiers are omitted or conflict, which is the main behavioral ambiguity here.

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

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

Two tight sentences, front-loaded with what is returned, with the auth requirement second. Nothing is padded, though the terseness leaves gaps that could have been closed in one additional sentence.

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

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

For a read tool with zero required parameters and no output schema, the definition does not explain what the response contains (message objects? thread metadata?) or how the three alternative identifiers interact. Adequate but leaves real gaps for an agent assembling a call.

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 meaning of email, thread_id, and contact_id is already documented, including the 'or the ...' alternate phrasing. The description adds only 'one contact', which does not clarify precedence among the three mutually alternative identifiers.

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: retrieves sent mail and replies for a single contact, ordered in time. This implicitly separates it from the sibling list_replies (which is not contact-scoped), but no sibling is named explicitly, so an agent must infer the boundary.

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

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

The description gives a prerequisite (read_crm scope) and an implied use case (reconstructing a contact's conversation), but never states when to prefer this over list_replies or search_contacts, nor what to do if no identifier is supplied. Usage is inferable rather than directed.

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?

Adds substantial context beyond the annotations: the enumerated launch_blockers that cause refusal, the async 202 response with a one-time operator approval gate, and the required scope. Annotations only say idempotent/non-destructive; the description explains failure modes, auth, and async behavior the annotations do not cover.

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: action first, then blockers/precondition, then approval behavior and scope. No filler, and the primary verb is front-loaded.

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

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

No output schema exists, and the description compensates by describing the return behavior (202 with pending approval) and refusal signals. Combined with annotations and full schema coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both campaign_id and idempotency_key are already documented in the schema, including the retry semantics. The description adds nothing about parameter format or constraints, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Start a draft campaign') and implicitly scopes it to drafts, which separates it from create_campaign, simulate_campaign, pause_campaign, and resume_campaign in the sibling list. An agent reading only the first sentence knows exactly what this does.

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 operating context: it works on a draft, requires the manage_campaigns scope, and needs specific blockers resolved first. It does not explicitly name an alternative or exclusion (e.g., when to prefer simulate_campaign first), so it stops 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds a genuine behavioral fact beyond them: archived campaigns are filtered out by default unless status=archived, which an agent could not derive from the schema alone.

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, with the return contents stated first and the default-filtering caveat second. Every clause carries information an agent needs.

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

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

With one optional parameter, full schema coverage, annotations covering safety, and no output schema to explain, the description is close to complete. It could mention result ordering or result-set size, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the enum values are enumerated in the schema itself. The description supplements this only with the default-filter behavior of the status parameter, so it neither repeats nor substantially extends the schema — baseline 3 applies.

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

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

The description names the resource (campaigns in this workspace) and the fields returned (status, delivery mode, enrolled/sent/replied counters), which tells an agent exactly what it gets back. The plural, workspace-scoped framing distinguishes it from get_campaign, though the sibling is never named explicitly.

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

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

The archived-hiding rule implies when to pass status=archived, giving useful conditional guidance for the only parameter. However, there is no explicit routing against siblings like get_campaign, campaign_report, or search_contacts, so an agent must infer when this list view is the right call.

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

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

The annotations already declare this as a safe read-only, idempotent operation. The description adds useful behavioral detail beyond annotations: ordering of results, the follow_up_blocked flag, and the required manage_tasks or read_crm permission.

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

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

The description is three compact sentences with no wasted language. The most important ordering rule is front-loaded, followed by the blocked-contact warning and permission requirement.

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

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

For a zero-parameter, read-only list tool with annotations covering safety, the description supplies the key behavioral context: ordering, blocked follow-up semantics, and permissions. It does not describe pagination or return shape, but no output schema exists to clarify those details.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline score of 4 is appropriate because the description does not need to compensate for missing schema parameter documentation.

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

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

The description clearly identifies the resource and temporal scope: overdue and due-today tasks first, then the next 7 days. It is distinguishable from write-oriented siblings like create_task, though it does not explicitly contrast itself with other list tools.

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

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

It gives clear usage context and an exclusion: tasks on contacts who replied, unsubscribed, or bounced are flagged follow_up_blocked and should not be chased. It also states prerequisite permissions, but it does not name alternative tools for adjacent task-listing needs.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description still adds real behavioral context beyond them: the meaning of each status, that approved may carry a note when waiting in the manual 'To send' hand-off, and that rows include warnings (open_draft_exists, emailed_N_days_ago) and prior_emails. It stops short of describing pagination behavior or result ordering.

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

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

Dense and front-loaded: the status vocabulary and its semantics come first, then the warnings/prior_emails fields, then the filter dimensions. The parenthetical asides each carry information, though the single long status enumeration makes it slightly list-like rather than fully scannable.

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

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

For a zero-required-parameter read tool with no output schema, the description compensates well by naming the fields returned (warnings, prior_emails, reject_reason, next_cursor implied via schema). The main residual gap is pagination/ordering expectations, which the schema's cursor and limit partially cover.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by expanding the status parameter into the full enum of valid values and clarifying that multiple statuses are comma separated, which the schema only gestures at ('For example rejected,failed'). It does add a little on run_id and contact_id as filter dimensions but nothing beyond their schema text.

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

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

The description states the resource (this agent's emails) and enumerates the state model (pending_approval, approved, rejected, sent, failed, cancelled), which makes it clearly a status-listing tool distinct from siblings like list_replies or get_thread. It never uses an explicit verb such as 'list' or 'filter', so the operation is inferred rather than stated.

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

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

Usage is implied through concrete cues: 'pending_approval (only when approval is on)', 'rejected (with reject_reason to learn from)', and the three filter dimensions. However, there is no explicit when-to-use guidance, no statement of when not to use it, and no named alternative (e.g. get_thread for a single conversation) to route the agent.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds two pieces of value beyond them: result ordering (newest first) and the required read_crm scope. It says nothing about pagination behavior or result shape, so it clears the lowered bar but doesn't exceed it.

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

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

Two short sentences, resource and ordering front-loaded, auth requirement appended. Nothing is wasted or buried.

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

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

For a paginated list tool with no output schema, the description should say something about cursor-based paging and what a reply record contains. The auth scope is a helpful addition, but the pagination and result-shape gaps keep it at minimum viable.

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

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

Schema coverage is 75% and the descriptions that exist (since, cursor, contact_id) are self-explanatory; only limit is undocumented. Since the description adds no parameter meaning at all, the baseline 3 for high schema coverage applies.

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

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

The description names the resource (replies from contacts) and the ordering (newest first), which is enough to understand the operation. It falls short of a full verb+scope statement and never distinguishes this from nearby tools such as get_thread or list_email_status.

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

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

No guidance on when to use this versus siblings like get_thread or list_email_status; the only conditional statement is an auth requirement, which is not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the built-in dry_run identity, notes that connected credentials exist but 'their keys are never shown' (a security guarantee an agent would otherwise have to discover), and mentions delivery state in the response.

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

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

A single sentence with no filler, and the core subject ('the identities a campaign can send through') is front-loaded before the explanatory colon clause. Slightly dense packaging — the parenthetical about keys sits mid-sentence — but nothing is wasted.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description covers what is enumerated (dry_run plus connected identities), a key security property, and the presence of delivery state. It stops short of describing the per-identity fields an agent would receive, which with no output schema is the one remaining 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?

The tool takes no parameters and the schema is an empty object with additionalProperties=false, so there is nothing for the description to explain. Per the zero-parameter baseline this scores 4; the description correctly spends no words on inputs.

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 the resource precisely — sending identities a campaign can send through — and enumerates its two sources (built-in dry_run plus operator-connected ones), which is concrete enough for an agent to know exactly what is returned. It does not explicitly contrast with sibling list_* tools (list_campaigns, list_suppressions, list_email_status), but the resource is distinctive enough to disambiguate in practice.

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

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

Usage is only implied: the framing 'the identities a campaign can send through' hints at pre-launch/pre-send checks, but there is no explicit when-to-use, when-not-to-use, or named alternative. With zero parameters there is little risk of misuse, so the guidance gap is moderate rather than severe.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful domain context by explaining that suppression entries are addresses and domains that are never emailed, but it does not disclose pagination behavior, filtering behavior, or return structure beyond that concept.

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

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

The description is extremely short and contains no wasted words, but it is a noun phrase rather than a front-loaded action statement. It is concise to the point of under-specification for an AI agent that needs to confirm the tool's operation.

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 list tool with rich annotations and a fully described schema, the description gives enough conceptual context to understand what is being listed. However, with no output schema, it should arguably mention that the response is a paginated list of suppression entries and what kinds of values are returned.

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 three parameters (q, limit, cursor) are fully documented in the schema. The description adds no parameter-specific meaning, which sets this at the baseline for well-covered schemas.

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 identifies the resource semantically (addresses and domains never emailed), but it does not explicitly state that the tool lists or retrieves suppression entries. Combined with the name and title the purpose is inferable, but the description itself does not provide a clear verb+resource statement or distinguish this from sibling tools.

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

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

There is no guidance on when to use this tool versus alternatives such as add_suppression or list_email_status. The description only defines the concept of a suppression list, leaving the agent to infer that this is a read/list operation and when it should be preferred.

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

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

Annotations only say it is a non-read-only, idempotent, non-destructive write; the description goes well beyond that by disclosing the cascade of side effects (cancelling pending drafts and open follow-up tasks, halting future drafts) and the required write_crm scope. That is exactly the information an agent needs before committing an irreversible state transition.

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

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

A single tight sentence that front-loads the action and then the consequences; every clause carries new information (state change, cancellations, draft suppression, scope requirement). No filler or restatement of the title.

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

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

With no output schema, the description does not say what the call returns (e.g. the updated contact or counts of cancelled drafts/tasks), which would help an agent verify success. Everything else — trigger, effects, permissions, idempotency — is covered, so the gap is minor.

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

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

Schema description coverage is 100%, so all five parameters (including idempotency_key semantics) are already documented in the schema. The description adds only the framing that reply text is optional, which is already implied by the absence of required parameters — 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 ('Record that a contact replied') and immediately enumerates the concrete state changes: contact set to replied, drafts and open follow-up tasks cancelled, further drafts stopped. This distinguishes it from read-side siblings like list_replies and from add_note, which merely attaches content without changing enrollment state.

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

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

Gives a clear triggering condition (a contact replied) and a prerequisite ('Requires the write_crm scope'), plus notes the reply text is optional. It stops short of naming alternatives — e.g. when to use add_note instead, or whether list_replies must be checked first — so no exclusions are provided.

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

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

Annotations already declare non-read-only, idempotent, non-destructive; the description adds real context beyond them by naming the required write_crm scope (an auth prerequisite the annotations do not convey). It stops short of describing side effects, such as whether moving to 'won' or 'lost' triggers downstream automation.

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 compact sentences, zero filler, with the core action and valid values front-loaded ahead of the precondition.

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-required-param mutation with no output schema, the definition covers the action, the allowed values, and the auth requirement. The remaining gap is behavioral outcome (what happens on a won/lost transition and what the call returns), which is a minor omission rather than a blocking one.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning the schema lacks: the schema's stage field only says "Target stage." with no enum constraint, and the description supplies the six allowed values. It says nothing extra about deal_id or idempotency_key, though those are already well documented in the schema.

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

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

States a specific verb and resource ("Set a deal's stage") and enumerates the six valid stages, so an agent knows exactly what the tool mutates. It does not name a sibling alternative (e.g. create_deal for new deals), but the purpose is unambiguous.

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

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

Usage is implied by the verb+resource pairing and the stage list, and the required write_crm scope signals a precondition. There is no explicit when-to-use/when-not guidance or mention of alternatives such as create_deal or a campaign tool.

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

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

Beyond the annotations, the description discloses key behavior ('Nothing is lost: resuming shifts every pending step by the length of the pause') and the required auth scope ('manage_campaigns'). This is exactly the extra context an agent needs to reason about side effects and permissions.

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

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

Three short sentences, front-loaded with the core action, then the key behavioral guarantee, then the auth requirement. No filler; 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 2-parameter mutation with a fully documented schema, no output schema, and annotations covering safety, the description supplies the important extras (pending-step behavior, scope). Minor gap: it doesn't mention what happens if the campaign isn't currently running.

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

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

Schema coverage is 100%, so both parameters, including the idempotency key semantics, are already fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Freeze a running campaign'), which clearly identifies the operation among siblings like resume_campaign and launch_campaign. It doesn't explicitly name the alternatives, but the action is unambiguous.

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

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

The phrase 'a running campaign' implies the precondition for use, but there's no explicit when/when-not guidance. It doesn't contrast with stop_enrollment or resume_campaign, leaving the agent to infer the boundary.

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?

Adds genuine value beyond annotations by disclosing the required 'manage_campaigns' scope, which annotations do not cover. However it says nothing about the state transition itself — whether scheduled sends restart, whether resuming is reversible, or what happens on a non-paused campaign — leaving the mutation's side effects undisclosed despite readOnlyHint=false.

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

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

Two short sentences with the action front-loaded and the prerequisite (scope) second. Nothing is redundant and 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 simple two-parameter, single-resource mutation with no output schema and annotations covering safety and idempotency, the description supplies what the tool does and the auth requirement. It stops short of describing the resulting campaign state or failure behavior on a non-paused campaign, which is the only material gap.

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

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

Schema description coverage is 100%, so both campaign_id and idempotency_key are already documented in the schema, including the retry semantics of the idempotency key. The description adds no parameter-level meaning 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 ('resume') and resource ('paused campaign'), which cleanly separates it from pause_campaign and launch_campaign in the sibling list. It does not explicitly name those siblings, so differentiation is implied by the verb rather than stated.

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

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

'Resume a paused campaign' implies the precondition that the campaign must currently be paused, but the description never states what to do when a campaign is not paused, nor when to prefer resume over launch_campaign. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds meaningful context beyond that: capped page size, a next_cursor for pagination, and the required read_crm scope.

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

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

Two tight sentences with the capability and filters front-loaded, followed by return shape and auth requirement. Nothing is wasted.

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

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

With no output schema, the description supplies the key return contract (contacts plus next_cursor) and the auth scope. Complete for a search tool; only a note on total-count or empty-result behavior 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 every parameter is already documented including the enum-like status list and the nested custom-field object. The description restates the filter surfaces but adds no format or semantics 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 ('Find') and resource ('contacts'), then enumerates the filter dimensions (text, status, source, company, custom field). This clearly separates it from sibling mutations like update_contact and upsert_contact.

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

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

Usage is implied by the filter list and the read_crm scope note, but the description never says when to prefer this over enumerating contacts another way, nor any exclusion conditions. Adequate but with a clear gap.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds the important behavioral guarantee that it shares the same planner as the real scheduler, meaning the simulation is authoritative rather than approximate. It also discloses the enumerated status vocabulary the agent will need to interpret results, though it says nothing about cost or latency for large simulations.

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 what the simulation produces, then the safety guarantee, then the fidelity claim — a sensible ordering with no filler. The long parenthetical status list is dense but justified because there is no output schema to carry 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?

With no output schema, the description fully carries the burden of explaining return contents (times, rendered copy, statuses, problems, launch_blockers) and the read-only guarantee. Nothing an agent needs in order to call this correctly against a 4-parameter schema 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 75%; the one undocumented parameter, horizon_days, is given meaning by 'over the next N days' in the description. The remaining params (as_of, contacts, campaign_id) are already described in the schema, so the description closes the only gap.

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 (simulate) and resource (campaign send plan) and enumerates exactly what the output contains: per contact and step, send time in UTC and local, rendered subject/body, and a status enum. This is clearly distinguishable from launch_campaign or get_campaign 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?

'Nothing is written or sent' plus 'this is what the scheduler will do' makes the pre-launch dry-run use case obvious and implicitly routes the agent away from launch_campaign. However, it never explicitly names launch_campaign as the alternative or states a when-not condition, so it stops short of full routing guidance.

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

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

Adds genuinely useful context beyond the annotations by disclosing the required manage_campaigns scope, which annotations do not carry. However, it says nothing about what stopping does to an in-flight send, whether the action is reversible, or what the 'manual' reason implies downstream — notable gaps for a mutation tool whose destructiveHint is false.

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

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

Two short sentences, front-loaded with the action and scope, with zero filler. The parenthetical '(reason manual)' is terse to the point of ambiguity, which slightly undercuts the otherwise tight phrasing.

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

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

Adequate for a simple two-required-parameter mutation: annotations cover safety and idempotency, the schema covers all parameters, and the description covers the auth scope. It still leaves the agent guessing about side effects on an active send and whether the stop can be undone.

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 idempotency_key parameter is fully documented in the schema, so the description has little left to add. It contributes no meaning about campaign_id or enrollment_id beyond what the schema already states.

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

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

States a specific verb ('Stop') and a precise, scoped resource ('a single enrollment'), which contrasts with the campaign-level siblings pause_campaign/resume_campaign. It does not name those siblings explicitly, so the differentiation is implied rather than stated.

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

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

There is no guidance on when to stop an enrollment versus pausing/resuming a campaign or adding a suppression, and no stated exclusions. The only usage information is the prerequisite scope, which tells the agent it can call the tool but not when it should.

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

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

Beyond the annotations, the description discloses two non-obvious behaviors: steps are replaced wholesale rather than merged, and step edits on a running campaign may require operator approval. It also states the required manage_campaigns scope, which annotations do not cover. Minor tension worth noting: replacing steps overwrites prior step definitions while destructiveHint=false; the description does not clarify whether omitted fields are preserved (partial update) or reset.

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

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

Three compact sentences with zero filler; the primary capability leads, and the two operational constraints (approval, scope) follow. Nothing is repeated from the title or schema.

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

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

For a 15-parameter mutation tool with nested objects and no output schema, the description covers approvals and scoping but leaves out patch semantics (are omitted fields kept?), what the response returns, and any hint about the untyped parameters like window and stop_on. It is adequate but leaves real gaps for a high-complexity 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 a middling 60% — the steps parameter has a very rich schema description, but window, stop_on, send_days, skip_dates, and track_opens are undocumented anywhere. The description adds no parameter-level meaning at all, so the agent must fall back entirely on the schema for a 15-parameter tool.

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

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

States a specific verb and resource ('Change a campaign's settings and/or replace its ordered steps'), which cleanly separates it from create_campaign, get_campaign, and the pause/resume pair. The 'replace' wording additionally distinguishes a full overwrite from an incremental patch. It never names a sibling tool explicitly, so it stops just short of 5.

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

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

The approval clause gives useful situational context for editing a running campaign, but there is no explicit when-to-use vs when-not guidance against the 28 siblings — nothing tells the agent to use pause_campaign or launch_campaign instead of editing settings directly, nor when an update should be skipped. Usage is implied by the resource only.

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?

Adds two things the annotations do not: custom `fields` are MERGED with existing values (not replaced), and the write_crm scope is required. That is genuine behavioral context for a mutation. It doesn't say what happens when the contact isn't found (error vs. no-op), and idempotency is already covered by the idempotency_key schema entry plus idempotentHint.

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

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

Three short sentences, zero filler. The lookup mechanism lands before the merge semantics and the auth requirement closes it out.

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

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

For an 11-parameter mutation with no output schema, this covers lookup, merge behavior, and auth. The remaining gap is failure semantics — what an agent should expect when the id/email matches nothing, or whether omitted fields are left untouched.

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 91%, so parameters are largely self-documenting and baseline applies. The description still earns credit by clarifying merge semantics for the nested `fields` object and by explaining that id and email are alternate lookup keys rather than both being required (required count is 0).

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?

A specific verb plus resource ("Change fields of an existing contact") and a lookup mechanism ("found by id or email"). The word "existing" quietly separates it from upsert_contact, though the sibling is never named outright.

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?

Implies usage via "existing contact" suggesting it will not create records, but never states when-not, and never points to upsert_contact as the alternative. The agent has to infer which of the two write paths to use.

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

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

The description adds meaningful behavior beyond the annotations: case-insensitive dedupe by email, merging of fields and tags, company creation/reuse, and the required write_crm scope. It does not clarify whether omitted standard fields are left unchanged or cleared during an update, which is a notable behavioral gap for an upsert.

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

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

The description is short and front-loaded, starting with the create-or-update behavior and then covering merge, company handling, and scope in four efficient sentences. Every sentence adds value.

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

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

For an 11-parameter upsert tool with full schema descriptions and rich annotations, the description provides enough behavioral context to invoke it correctly. It covers the core upsert semantics, merge behavior, company side effect, and authorization requirement; return values need not be described because there is no output schema.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters and establishes a baseline of 3. The description still adds useful semantic detail for key parameters: email as the case-insensitive dedupe key, merge behavior for fields and tags, and company creation/reuse from company_domain or company_name.

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 create-or-update operation for a contact and identifies the email-based match key, merge behavior, and company handling. It is clear what the tool does, though it does not explicitly contrast itself with the sibling update_contact tool.

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

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

It clearly explains that the tool creates a contact or updates an existing one matched by email, including case-insensitive matching and merge semantics. It does not explicitly state when to prefer this over update_contact or when not to use it, so alternatives are left implicit.

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