Emailchef MCP by usefulapi

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

Annotations declare destructiveHint=true and idempotentHint=true; the description adds the crucial nuance that the operation is reversible and preserves statistics, which softens and clarifies the 'destructive' label with information not in the annotations. It also gives the underlying HTTP endpoint, though it omits auth/error behavior.

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

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

Three compact clauses with zero waste, front-loaded with the WRITE marker and the action before the reversal note. Every sentence carries distinct information.

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

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

For a one-parameter mutation with no output schema, the description covers effect, visibility change, data retention, reversibility, and the endpoint. Missing only permission/error semantics, which is minor at this complexity.

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

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

Schema coverage is 100% for the single campaign_id parameter, and the schema already documents it as the numeric id returned by list tools. The description adds nothing beyond the endpoint path implying {id}, 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 ('archive a campaign') and immediately differentiates it from the sibling inverse by naming emailchef_unarchive_campaign. The parenthetical clarifies the semantic meaning of archiving (hidden from default list, statistics kept), so an agent can distinguish it from delete-like 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?

Implies the use case (remove a campaign from the default listing without losing data) and explicitly routes to the reversal tool. It does not spell out exclusions such as when to prefer unarchive or whether send_campaign must be avoided first, but the context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds meaningful context beyond them: account-wide blast radius ('any list'), the 100-address cap, reversibility via emailchef_unblock_email, and the underlying POST /blockings?type=MANUAL endpoint. It does not cover failure modes or partial-success behavior for batch input.

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 plus an endpoint fragment, all front-loaded — operation type first, effect and reversibility next, endpoint last. No sentence is redundant.

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

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

For a single-parameter mutation with rich annotations and no output schema, this covers operation, scope, limit, and reversal path. The only unaddressed elements are the response shape and what happens when some addresses in the batch are already blocked, which are minor here.

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 already documents the email format, per-item maxLength, minItems, and maxItems=100. The description echoes the 100-address limit and clarifies the blocklist is account-level rather than list-specific, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (add/block) and resource (account blocklist), with explicit effect scope ('never receive email from any list'). The 'WRITE:' prefix and the pointer to emailchef_unblock_email distinguish it from read-oriented siblings like emailchef_list_blocked.

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 use context (suppress delivery across every list) and names the reversal tool, so the agent knows the counterpart operation. It stops short of stating when NOT to use it (e.g. per-list suppression vs unsubscribe), so it is not 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 a non-readonly, non-destructive, non-idempotent write; the description adds context annotations cannot carry: output is a DRAFT, nothing is sent, the failure mode for SENT campaigns, the returned id, and the underlying endpoint. This is exactly the value-add expected of a description on top of annotations.

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

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

One dense sentence plus return-value and endpoint notes, front-loaded with the WRITE and DRAFT framing. Every clause carries information; 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?

For a single-parameter write tool with no output schema, the description covers action, result (new campaign id), safety (draft only), and the main error condition. 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 coverage and a single required parameter, the schema already documents campaign_id ('The campaign to copy.') so the baseline is 3. The description earns an extra point by adding a validity constraint on that id — SENT campaigns will fail — which the schema does not express.

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 ('copy an existing campaign into a new DRAFT') and immediately disambiguates from sibling create_campaign and send_campaign by clarifying that nothing is sent. An agent can distinguish this from update_campaign or create_campaign 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?

Explicitly states the preclusion: a SENT campaign cannot be cloned (HTTP 500). That is real when-not-to-use guidance. It stops short of naming the alternative tool (e.g., create_campaign) for the blocked case, so it lands at 4 rather than 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 only declare readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that — creation is draft-only and non-dispatching, and the campaign will silently become unsendable ('send ends FAILED') unless the HTML body contains specific CAN-SPAM placeholders and an unsubscribe link. That is a real behavioral constraint an agent could not 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?

Front-loaded with the write/draft distinction, then prerequisites, then the validation gate, then next steps — a sensible priority order. It is a dense run-on sentence and the placeholder list is bulky, but every clause carries information.

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

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

Covers purpose, dependencies, failure mode, and follow-up for an 8-parameter mutation tool with no output schema. Minor gap: it doesn't say whether text_body is optional or that the response returns a campaign id needed to schedule later, though the schema fills in the optionality.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by enumerating the exact required placeholder tokens ([[account:business]], [[account:address_1]], etc.) that the schema only alludes to vaguely as 'the CAN-SPAM placeholders,' and by tying sender_id to a verification source.

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

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

Opens with an explicit verb and resource plus a scope qualifier — 'WRITE: create a new campaign as a DRAFT (nothing is sent)' — which immediately separates it from emailchef_send_campaign and emailchef_schedule_campaign in the sibling list.

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

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

States prerequisites (verified sender via emailchef_list_senders, at least one list) and explicitly routes follow-up work: 'Schedule or send it afterwards,' naming the two downstream siblings by function. An agent knows both when to call this and what to call next.

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 write, openWorld, and non-idempotent, but the description adds real substance: what ACTIVE means downstream (campaigns and automations), the return payload (contact id and status), and the underlying endpoint. It still omits duplicate-email behavior, which matters for a non-idempotent create.

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 a 'WRITE:' marker so the operation type is impossible to miss. Every sentence carries distinct information—payload, precondition, return 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?

With no output schema, the description helpfully names the return values, and the nested custom_fields schema points to emailchef_list_custom_fields. But for a non-idempotent create it never addresses duplicate handling or failure modes, leaving a gap an agent would want covered.

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

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

The description names email, name, and custom fields, and the schema documents status and custom_fields in detail (50% coverage overall). It adds little beyond the schema for list_id or the status enum values, so the schema still carries most of the load.

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

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

States a specific verb and resource ('add a contact ... to a list') and enumerates the payload fields (email, name, custom fields). It does not explicitly distinguish itself from siblings like emailchef_import_contacts or emailchef_update_contact, so the agent must infer that this is the single-contact create path.

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?

'Only add people who agreed to receive email' gives a consent precondition, which is useful guidance. However, there is no explicit routing to alternatives such as bulk import or update for existing contacts, nor what to do when the email already exists.

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

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

Annotations already declare the write/non-destructive/non-idempotent/open-world profile, and the description adds two pieces of value beyond them: the return value ('Returns the new list id') despite there being no output schema, and the underlying endpoint. It stops short of noting that duplicate list names are not deduplicated, which the non-idempotent hint implies matters.

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 clauses, front-loaded with the operation class ('WRITE:') and the core action, then the return value, then the endpoint. No filler and nothing that could be trimmed without losing information.

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

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

For a two-parameter create tool with annotations covering the safety profile, the description supplies the essential missing piece—the returned id—so the agent can chain into get_list or import_contacts. It omits error behavior and whether the name must be unique, which are minor for this complexity level.

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

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

Schema description coverage is 100% with clear min/max length constraints on both fields, so the schema carries parameter semantics fully. The description adds no extra meaning (e.g., uniqueness or naming conventions) beyond that, which is the baseline-3 case.

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 ('create a new, empty contact list') plus the transport endpoint (POST /lists). The 'empty' qualifier distinguishes it from import_contacts and the sibling create_* tools, so an agent can pick it without opening schemas.

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

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

The 'WRITE:' prefix and 'new, empty' wording imply this is for provisioning a container before adding contacts, but it never names an alternative (e.g., use emailchef_import_contacts to populate it, or emailchef_list_lists to check for an existing list first). 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the account is implicitly resolved from the API key credential (no account identifier is passed), and it names the underlying endpoint GET /accounts/current. It doesn't discuss caching, rate limits, or error behavior when the key is invalid.

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

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

One compact sentence plus the endpoint path, with the returned fields listed up front and nothing redundant. Every clause carries information.

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

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

With no output schema, the description must convey the return shape, and it does so by enumerating the main fields. For a parameterless read-only lookup this is close to complete; only secondary details like response nesting or failure modes 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?

There are zero parameters, so the baseline is 4. The description usefully explains why: the target account is determined by the API key itself, which is the key semantic an agent needs to understand about this call.

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

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

The description identifies a specific resource — the account the current API key belongs to — and enumerates the returned fields (id, email, language, status, subscriber total, bounces, complaints). That clearly separates it from the other get_* siblings (get_contact, get_list, get_campaign). The only shortfall against a 5 is that the retrieval verb is implied rather than stated 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?

Usage is only implied: an agent can infer this is the tool for account-level metadata rather than contacts, lists, or campaigns. There is no explicit statement of when to call it (e.g. to resolve the active account before other operations) and no named alternatives, though for a zero-parameter account endpoint there are few plausible alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered by structured data. The description's contribution is disclosing the return payload composition (bodies, schedule, cached sent/open/click counts), which is genuinely useful. It adds nothing about error behavior for an unknown id or the fact that counts are cached and possibly stale, so it does not exceed a moderate score.

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 return contents, followed by a short endpoint reference. Efficient with no filler, though the endpoint notation is partially redundant with the tool name.

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

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

With no output schema, the description carries the burden of describing the return shape and does so thoroughly for a one-parameter read tool. Missing only ancillary details such as behavior on a nonexistent or archived campaign id.

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 fully documented with accepted string/integer forms and the note that it comes from the list tools. The description only echoes the parameter as a path segment ({id}), adding no syntax or edge-case 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 description enumerates the exact fields returned from a single campaign (name, subject, bodies, sender, state, schedule, lists/segments, cached counts) and names the endpoint GET /campaigns/{id}, which unambiguously identifies a single-resource fetch. It stops short of explicitly contrasting itself with siblings like emailchef_get_campaign_counts, emailchef_get_campaign_links, or emailchef_list_campaigns, though the field list implicitly distinguishes 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?

There is no statement of when to use this tool versus the many campaign siblings. An agent must infer that get_campaign_counts is a narrower fetch and list_campaigns is the bulk variant; the description never routes it. No prerequisites or conditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the aggregation dimension (counts grouped by state) but says nothing about return format, auth requirements, or scope (whole account vs filtered), which is a modest 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?

A single front-loaded sentence carries all the semantic content, with the state list attached as a compact enumeration. The trailing 'GET /campaigns/count' is near-redundant with the name and title but is harmless.

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 zero params and no output schema, the description carries the burden of describing the return shape, and it does so by naming the five state buckets. It stops short of stating the response structure (e.g., a counts object keyed by state), which would fully close the 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, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% on an empty object.

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 ('How many campaigns the account has by state') and enumerates the states returned, which separates it from the sibling emailchef_list_campaigns. It does not explicitly name the alternative, but the aggregate-vs-list distinction is evident.

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

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

Usage is only implied: an agent can infer this is for summary/dashboard counts rather than fetching campaign records. There is no explicit when-to-use, when-not-to-use, or reference to emailchef_list_campaigns as the 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /newsletters/{id}/links) and the shape of each returned link, but says nothing about pagination, result limits, or behavior for archived/unsent campaigns.

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 fragments with zero waste; the returned fields are front-loaded and the endpoint follows. Slightly telegraphic, but every element carries information.

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

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

For a one-parameter read tool with full schema coverage and no output schema, the description covers what is returned (id, name, URL) and the endpoint used. Only pagination/limit behavior and edge cases for campaigns without links are unaddressed.

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

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

Single parameter with 100% schema coverage, including a description telling the agent it is the numeric id returned by list tools. The prose only reinforces that the id is a campaign id; it adds no 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 the resource precisely — the links contained in a campaign — and even enumerates the returned fields (id, name, URL), which distinguishes it from emailchef_get_campaign and emailchef_list_campaigns. It is a noun phrase rather than a verb+resource, but the operation 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?

There is no explicit when-to-use guidance and no mention of alternatives such as emailchef_get_campaign or emailchef_list_campaign_engagement. The agent must infer that this is the tool for enumerating tracked links of a single campaign.

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=true, destructiveHint=false, openWorldHint=true), so the description's job is to add context — which it does by disclosing the exact payload an agent will receive, valuable since there is no output schema. It omits error behavior for unknown contacts and any auth/rate-limit notes, 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 tight sentences with the payload description front-loaded and the endpoint form last. The 'GET /contacts/{contact_id}?list_id=...' fragment is mildly redundant with the schema, but it reinforces the id-scoping relationship cheaply.

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 read with no output schema, the field enumeration is exactly the missing piece an agent needs to decide whether to call this versus a list tool. Only the not-found / cross-list-mismatch behavior is unaddressed, which is a minor gap for a simple getter.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds the non-obvious semantic that a contact is list-scoped — contact_id alone is insufficient and list_id constrains which record is returned. That is a real clarification beyond 'Numeric id (as returned by the list tools)'.

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

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

The description clearly states it returns a single contact scoped to a single list and enumerates the fields returned (status, email, name, IP, source, timestamp, custom fields). It implicitly separates itself from emailchef_list_contacts by emphasizing 'one contact in one list', but it never names that sibling explicitly.

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

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

Usage is only implied: the 'one contact in one list' phrasing tells an agent this is the single-record lookup requiring both a list and a contact id. There is no explicit when-to-use statement, no mention of emailchef_list_contacts for browsing, and no note about what happens when the contact isn't in that list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond that by naming the returned payload (status, progress, imported/updated/failed counts, error message), though it says nothing about failure semantics or task lifecycle.

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

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

Two terse sentences, front-loaded with the resource and its payload, zero filler. Every clause carries information.

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

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

No output schema exists, and the description compensates by describing the return contents and the endpoint. Adequate for a one-param read tool; only missing lifecycle/failure nuance, which 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?

Single param with 100% schema description coverage, so the schema already documents task_id as a numeric id from list tools. The description adds nothing param-specific, matching the baseline 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 and resource (get one import task) and enumerates the returned fields, which makes it clearly distinct from the plural emailchef_list_import_tasks sibling. It omits an explicit sibling reference but the singular framing 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 only implied: fetch a single task by id. There is no statement of when to use this versus emailchef_list_import_tasks, nor any prerequisites (e.g., task must be in progress/complete).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value by disclosing the response shape (name, description, default sender, creation date), which matters because no output schema exists. It stops short of stating behavior on a missing or unauthorized list_id.

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 fragments with zero padding: the return contents come first, then the endpoint. Nothing is repeated from the title or schema, 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 single-parameter read with full annotations and no output schema, the field enumeration is the key missing piece and it is supplied. Only the failure mode (missing/invalid list_id) and whether it 404s or returns empty is left unspecified.

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 list_id description already says 'Numeric id (as returned by the list tools)', so the description adds nothing about the parameter. Baseline 3 applies when the schema carries the semantics.

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

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

It names a single resource ('One contact list') and enumerates the fields returned, plus the underlying endpoint GET /lists/{list_id}, which makes the singular-fetch intent unambiguous against emailchef_list_lists. It lacks an explicit verb like 'Get/Retrieve', so clarity comes from the endpoint rather than the prose.

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 call this instead of emailchef_list_lists, emailchef_get_list_stats, or emailchef_get_list_contact_counts — all siblings that operate on the same list_id. The agent must infer the choice from the field listing alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds that this is a GET against /lists/{list_id}/stats/count and that counts are bucketed by state, which is useful context beyond the annotations. It says nothing about cost, eventual consistency of the counts, or how totals aggregate, but for a simple read tool the bar is low.

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

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

Two compact clauses with the returned dimensions front-loaded, no filler. The endpoint path is the least valuable element but is short and harmless, so nothing needs cutting.

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-only counts call with annotations and full schema coverage, the description covers the essentials. The notable gap is the unresolved overlap with emailchef_get_list_stats, which a complete definition would explicitly differentiate; without an output schema, saying the response is a per-state breakdown is adequate.

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

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

Schema description coverage is 100% and the single list_id parameter is well documented in the schema itself ('Numeric id (as returned by the list tools)'). The description only implies the path placement via 'GET /lists/{list_id}/stats/count', adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

Names a specific resource (contacts in a list) and a specific dimension (counts broken down by state: active, unsubscribed, bounced, reported), plus the underlying endpoint. An agent can tell it returns aggregate counts rather than records. It does not, however, distinguish itself from the sibling emailchef_get_list_stats, which sounds like an overlapping per-list statistics tool.

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

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

No statement of when to call this versus emailchef_get_list_stats, emailchef_get_campaign_counts, or emailchef_list_contacts with filters. The agent must infer the boundary from names alone, which is exactly where these sibling tools are most ambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral fact — omitting dates returns the entire history — but says nothing about payload size, pagination, or gaps for days with no data, which matters for a full-history read.

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

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

Two compact sentences that lead with the return shape, then the optional-date behavior, plus a short endpoint suffix. No filler and no repetition of schema or annotation 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 does carry the burden of describing returns and it does so at a useful level of detail (per-day totals and deltas). For a simple 3-parameter read tool it is nearly complete; only the response envelope (series shape, empty days) is unspecified.

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 the schema lacks: that start_date and end_date are optional and omitting both yields whole-history results, and that the range is inclusive daily granularity. It does not clarify timezone or inclusive/exclusive end-date semantics.

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

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

States the resource (list growth), the granularity (daily), and exactly what is returned (total contacts per day plus daily delta), which distinguishes it from count-style siblings like get_list_contact_counts. It does not explicitly name an alternative sibling, keeping it just below a 5.

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

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

The only usage guidance is 'Omit the dates for the whole history,' which tells the agent how to call it but not when to prefer it over get_list_contact_counts, get_list, or segment-based stats. Nothing is misleading, but the routing between alternatives 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds that the returned object carries the segment's logic and condition groups, which is genuinely useful since there is no output schema, but it stops short of describing pagination, error behavior, or the full response shape.

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 return-content fact front-loaded and the endpoint template after it. Every element is relevant, though the raw REST path is largely redundant for an agent that already knows this is a GET-by-id tool.

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

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

For a simple two-parameter read with no output schema, the description covers what is returned (logic and condition groups) and the addressing scheme. Only minor gaps remain around failure modes and how segment ids are obtained, which the sibling list tool implies.

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

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

Schema description coverage is 100% and both required parameters are documented there, so the baseline of 3 applies. The path template in the description mildly reinforces that the ids are numeric path parameters but adds no new semantics 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?

Names a specific verb ('Get') and resource ('segment'), and the phrase 'One segment' implicitly distinguishes it from the sibling emailchef_list_segments. It does not explicitly name that sibling, so it falls short of a 5.

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

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

Usage is only implied: 'One segment' plus the id-based path suggest fetching a single known segment, whereas list_segments would be used to discover ids. There is no explicit when-to-use statement, no prerequisite note, and no mention of what happens with an invalid id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that the response includes currency alongside the balance, which is modest but real added context; it says nothing about zero-balance behavior, auth requirements, or rate limits.

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 fragments with the payload front-loaded in sentence one. The trailing 'GET /sms/balance.' restates the endpoint for human developers and adds nothing for an agent, but it costs only a few tokens.

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 tool with no output schema, the description tells the agent what it will receive (credit balance and its currency), which is the essential information. Minor omissions like empty-state behavior are acceptable at this complexity.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies no inputs are needed.

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 (get) and resource (SMS credit balance) plus the returned fields (balance and currency). It is distinguishable from the closest sibling, emailchef_get_sms_status, by naming 'balance' rather than status, though it never explicitly contrasts the two.

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 statement, no prerequisite (e.g. an SMS-enabled account), and no mention of the adjacent emailchef_get_sms_status tool. The only signal is the name itself, so the agent must infer that this is a read-only check of credits.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by enumerating the response fields (recipient, text, sent/done time, parts, price, state, error) and the underlying endpoint, which matters since there is no output schema. It omits behavior on unknown ids or empty results, keeping 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?

Two compact clauses with the resource and lookup key front-loaded; every phrase (including the endpoint) carries information. No filler.

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

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

For a simple one-parameter read, it covers purpose, the input's origin, the returned fields and the endpoint. Missing only failure-mode behavior for invalid or expired ids, which would complete the picture in the absence of an 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?

The single parameter is fully documented in the schema, including that the id comes from emailchef_send_sms. The description only restates "by message id" and adds no format or constraint detail, so baseline 3 applies where 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 with scope: "Delivery status of one sent SMS by message id." This clearly separates it from siblings like emailchef_send_sms and emailchef_get_sms_balance without needing 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?

Usage is only implied – "one sent SMS" and "by message id" suggest a post-send lookup, but the description never states when to use this versus other SMS or status tools, nor any prerequisites. It stops short of naming conditions or alternatives.

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

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

Annotations already establish that this is a safe, read-only operation. The description adds useful context by listing the returned plan fields and recommending the pre-send check. It does not cover auth, rate limits, or error behavior, but those gaps are minor for a zero-parameter read endpoint.

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

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

The description is two sentences plus the endpoint path, with the returned fields and the usage recommendation front-loaded. Every sentence adds value and there is no unnecessary repetition.

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

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

For a zero-parameter, read-only tool with no output schema, the description provides enough detail: it enumerates the returned plan attributes and gives a practical reason to call it. No additional information is needed 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?

The tool takes no parameters, so there are no parameter semantics to explain. The empty schema is consistent with the description, and the baseline for zero-parameter tools is a 4.

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

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

The description clearly identifies the resource as the account's current Emailchef plan and enumerates what it returns: plan name, expiry, contact/send limits, credits, and active/expired flags. It does not explicitly distinguish this from sibling tools like emailchef_get_account or emailchef_get_sms_balance, which slightly limits clarity.

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

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

It gives a concrete usage cue: 'Check this before a big send.' This tells the agent when the tool is relevant. It does not name alternatives or exclusions, but the context is clear enough for a straightforward read 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?

Adds substantial behavior beyond the annotations: the operation is asynchronous and runs in the background requiring polling with the returned id, and matching is upsert-style on existing emails. It also flags a compliance prerequisite (only import consenting contacts) and the underlying endpoint, none of which the destructiveHint/readOnlyHint annotations 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?

Opens with the "WRITE:" marker so the mutation is front-loaded, then packs limit, upsert rule, object shape, prerequisite lookups, consent caveat, async polling, and endpoint into one tight block 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?

There is no output schema, and the description compensates by explaining that the call returns an import task id to be polled via emailchef_get_import_task. For a two-parameter, fully documented, async mutation tool, 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 already 100%, and the description still adds meaning: contacts are objects keyed by field placeholder with a concrete example, and the agent is told where list_id comes from (the list tools) and where placeholders come from (the field-listing tools). That is real guidance beyond the 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 and resource with scope: "bulk-add or update up to 500 contacts in a list in one call," plus the upsert rule "an existing email is updated." This clearly separates it from the single-record siblings emailchef_create_contact and emailchef_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?

Routes the agent to prerequisites (emailchef_list_predefined_fields, emailchef_list_custom_fields for placeholders) and to the follow-up tool (emailchef_get_import_task) for polling, plus a consent constraint. It never explicitly says when to prefer emailchef_create_contact/update_contact over bulk import, so the exclusion 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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real context: what a blocklist means operationally ('emails that never receive email'), the endpoint, and the three possible reason codes — knowledge not present in 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?

A single front-loaded sentence carries the resource, its meaning, the returned fields, and the enum values, with the endpoint appended compactly. 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 no-required-parameter read tool with full schema coverage and no output schema, the description is nearly complete — it even names the returned fields (address, reason) and the endpoint. Only the pagination/listing semantics delegated to the schema are absent, which is acceptable.

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

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

Schema description coverage is 100%, so limit, offset, and search are fully documented in the schema, making the baseline 3 appropriate. The description adds nothing about pagination or search behavior beyond what structured fields already state.

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

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

States a specific verb ('List') and resource ('the account's blocklist'), defines it inline ('emails that never receive email'), and enumerates the concrete reason values. It is clearly distinct from the mutation siblings emailchef_block_emails and emailchef_unblock_email.

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 read-only listing intent is implied by 'List' and the semantic gloss, but there is no explicit when-to-use or when-not-to-use guidance and no reference to the block/unblock siblings that would let an agent route correctly without 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's job is to add context — and it does by disclosing the return shape ('counts and first/last event time'), which matters because there is no output schema. It stops short of mentioning pagination behavior or result size limits.

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 waste, with the scope/what-is-returned information front-loaded and the 'exactly one event' constraint immediately after. Nothing redundant beyond the necessary endpoint reference.

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

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

For a read-only listing tool with no output schema, the description covers the return fields and the single-event selection rule, so an agent has enough to call it correctly. Minor omission: no mention of pagination or expected result volume, though the schema's offset hint partially compensates.

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 is already documented and the baseline is 3. The description's prose enumeration of event values restates the enum rather than adding new syntax or format detail, so it does not lift the score above baseline.

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

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

The description states a specific verb+resource ('Per-contact engagement for a sent campaign') and enumerates the exact engagement slices returned, which implicitly separates it from aggregate siblings like get_campaign_counts and get_campaign_links. An agent can tell what it returns without opening the schema.

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

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

It gives one hard usage constraint ('Pick exactly one event') and the backing endpoint, but says nothing about when to prefer this over get_campaign_counts/get_campaign_links or what prerequisites (e.g., campaign must be sent) apply. Usage is implied rather than guided.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower; the description still contributes the non-obvious default-filter behavior that would otherwise cause an agent to wrongly conclude no drafts exist. It adds nothing about auth, rate limits, or pagination 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 tight sentences plus the endpoint; the returned-fields summary is front-loaded and the surprising default-filter caveat follows immediately. 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?

With no output schema, the description usefully enumerates the returned metrics and flags the default-state pitfall, which is enough to call the tool correctly. Pagination and sorting are fully handled by the schema, so only minor gaps (result envelope shape, ordering of the default set) remain.

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 all six parameters (limit, offset, order, order_by, search, status) are documented in-schema, including the default status set and the 'pass the previous reply's next_offset' pagination hint. The description's status guidance largely restates what the schema already declares, so it adds only marginal semantic value beyond structured data.

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

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

States a specific verb and resource ('List email campaigns') plus the exact fields returned (state, recipients, delivered, unique opens, unique clicks), and names the underlying endpoint GET /campaigns. It is distinguishable from emailchef_get_campaign by the plural/list framing, but never explicitly names or excludes near-siblings like emailchef_list_campaign_engagement, which also reports engagement 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?

Gives a genuinely actionable usage rule: without a status filter only SENT and ARCHIVED campaigns come back, so the agent must pass a status to reach DRAFT/SCHEDULED/SENDING/FAILED. That is clear conditional guidance, but it does not address when to prefer this over list_campaign_engagement or get_campaign for a single campaign.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP route and the returned field set, but says nothing about pagination behavior, result caps, or ordering defaults beyond what the schema documents — useful but modest added value.

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

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

A single front-loaded sentence with the key scope first, the return fields parenthetically, and the endpoint last. No wasted text; the trailing 'GET /contacts?list_id=...' is slightly truncated but harmless.

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 6 parameters, 100% schema coverage, and no output schema, the description does the one thing it must — enumerate the returned fields (id, email, name, added by, subscription date) — while annotations and schema cover safety and paging. Complete enough to invoke correctly.

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

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

Schema description coverage is 100% with clear enum documentation for status, order, and order_by, so the schema does the heavy lifting. The description only restates the optional state filter, adding no format or semantics beyond the schema — 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 and resource (list contacts) with a clear scope constraint ('of one list') and enumerates the returned fields, which separates it from emailchef_get_contact and emailchef_list_blocked. It stops short of naming a sibling alternative explicitly, 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?

'Of one list ... optionally by state' implies when the tool is appropriate and the state-filter option, but there is no explicit when-to-use vs. when-to-use-something-else guidance (e.g., get_contact for a single record, get_list_stats for aggregates). Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond them by disclosing the underlying GET endpoint and the shape of each returned record, which matters because there is no output 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?

A single dense sentence front-loads the resource and packs the four returned attributes economically. The appended GET path is mildly redundant with the resource name but does anchor the tool to a concrete endpoint.

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-only tool with annotations and no output schema, the description is nearly sufficient: it covers scope and return fields. The remaining gap is the missing contrast with predefined fields, which is the one thing an agent could get wrong.

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 list_id parameter is already documented as 'Numeric id (as returned by the list tools).' The description only implies list scoping ('of a list', the /lists/{list_id}/ path) without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description names the resource precisely (custom contact fields of a list) and enumerates what each field record contains — name, data type, placeholder, options — so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling emailchef_list_predefined_fields, which an agent could easily confuse with 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?

There is no explicit when-to-use or when-not-to-use guidance. The parenthetical '(the key used when writing contacts)' implies the practical purpose — fetch this before creating/updating contacts — but the agent must infer that, and no alternative tool is 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by exposing the endpoint and the status enum values (DISPATCHED, COMPLETE, FAILED) and the meaning of the counters. It omits whether results are paginated or complete, which matters for a polling-style list tool.

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

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

A single dense sentence front-loads the resource, then the return fields, then the endpoint. Nothing is redundant and the status enum is packed inline rather than given its own 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?

With no output schema, the description carries the burden of describing return values, and it does so by naming the key fields and status values. What remains missing is the shape of the collection itself — pagination, ordering, or whether historical tasks are included.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly implies that no filters (list id, status, date) are available, consistent with the empty schema.

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

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

The description gives a specific verb and resource ("List contact import tasks") and enumerates the fields returned, so an agent knows exactly what it retrieves. It does not differentiate itself from the sibling emailchef_get_import_task, which fetches a single task by id, so the sibling distinction is left implicit.

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

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

Mentioning status, progress and counts implies the polling/monitoring use case for imports, which is reasonable implied guidance. However, it never states when to use this versus emailchef_get_import_task, nor any prerequisite (e.g., that an import must have been started via emailchef_import_contacts).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing what a row contains and the default sort order, plus the underlying endpoint (GET /lists). It does not discuss pagination behavior or result limits, which the schema carries instead.

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

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

Two dense sentences with the payload description first, then the ordering default, then the endpoint. No redundancy or filler; every clause carries information 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?

With no output schema, the description correctly shoulders the burden of describing the return shape (id, name, counts, segments) and the default ordering. It is nearly complete for a paginated list tool, though it could mention that responses include paging metadata such as next_offset referenced in the 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%, so limit, offset, order, and order_by are all already documented in the schema, including the next_offset paging pattern. The description's 'newest first by default' merely restates the default that order/order_by already encode, so no meaningful semantics are added beyond the schema.

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

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

States a specific verb and resource ('List the contact lists') and enumerates the fields returned (id, name, active/unsubscribed/bounced counts, segments), which distinguishes it from a single-list fetch or a stats call. It stops short of naming siblings like get_list or get_list_stats explicitly, so the list-vs-get distinction is only implied by the verb.

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?

'Newest first by default' gives a hint about default ordering behavior but nothing about when to prefer this tool over get_list_stats or get_list_contact_counts. There are no exclusions, prerequisites, or named alternatives, leaving usage to be inferred from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results include placeholders, which hints at response content, but it says nothing about auth, rate limits, or ordering beyond the raw endpoint path.

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 fragments with zero filler, and the key identifying information ('built-in', 'placeholders') is front-loaded. 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 simple zero-parameter read tool with no output schema, the description gives enough to know what comes back (built-in fields plus placeholders). Only a slight gap remains around response shape, which is minor given the tool's simplicity and the annotations.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-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?

The description identifies a specific resource (built-in contact fields) and adds useful scope detail (they include placeholders, e.g., email, first name). The word 'built-in' implicitly distinguishes it from emailchef_list_custom_fields, though it never names that sibling or uses an explicit verb like 'list'.

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

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

Usage is only implied: an agent can infer it should call this to discover built-in merge fields and placeholders. There is no explicit when-to-use statement, no mention of the custom-fields alternative, and no prerequisites.

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

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

Annotations already establish that this is a read-only, non-destructive operation. The description adds the endpoint and says each segment is returned with a matching-contact count, but it does not describe pagination behavior or response shape beyond that.

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

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

The definition is front-loaded with the core purpose and then supplies the endpoint. There is no redundant or filler language.

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

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

For a simple read-only listing tool with fully documented parameters and safety annotations, the description covers the essential purpose and return content. It could be fuller about the response object, but the missing output schema is not a major gap here.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only reinforces that list_id is the path parameter and does not add meaning beyond the schema.

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

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

The description gives a specific verb and resource: listing the saved segments of a list, with matching contact counts. It is clear enough to separate this from list-oriented siblings, but it does not explicitly distinguish itself from get_segment.

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

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

Usage is implied by the verb and resource, but there is no explicit guidance on when to use this versus get_segment or other list-related tools. No exclusions or conditions are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds value by disclosing what comes back (including verification status, which is behaviorally important since only verified senders are usable) — a meaningful detail with no output schema to convey it. It doesn't mention result volume or pagination, keeping 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?

Three short sentences: what it returns, why it matters, and the endpoint. Nothing is repeated from the title or annotations, and the resource description is front-loaded.

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

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

For a zero-parameter read-only list tool with no output schema, the description covers everything an agent needs: the returned fields, the verification-status signal, and the use case (obtaining a sender id). Nothing material is left ambiguous.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the description correctly implies a plain unfiltered GET /senders with no filtering or paging arguments to explain.

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 (list) plus specific resource (sender identities) and an enumeration of the returned fields (name, email, verification status, postal address). No sibling tool covers senders, and the endpoint reference reinforces scope, so an agent can distinguish this from the many list_* siblings immediately.

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?

"Campaigns and emails need a verified sender id" gives a concrete reason to call this and implicitly points to send_campaign/send_email as the downstream consumers. It stops short of explicit exclusions or a named alternative, so it's clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds useful context beyond that: the shape of each returned record and the fact that values are fixed UTC offsets (not DST-dependent names), plus the underlying HTTP endpoint for traceability. Auth/rate-limit behavior remains unspecified, keeping 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?

Two short sentences plus an endpoint: identity, payload, and downstream purpose, all front-loaded with zero filler. Every clause earns its place, including the endpoint token which costs four words and adds traceability.

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 no-parameter, read-only lookup with no output schema, the description supplies what an agent needs: what comes back and why it matters. It does not state whether the list is paginated or statically ordered, though for a static meta endpoint that omission is minor.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. It spends its words usefully by documenting the response fields (id, name, fixed UTC offset) that the absent output schema would otherwise have had to carry.

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

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

States a specific verb and resource ("List Emailchef's timezones") and immediately enumerates what each entry contains (id, name, fixed UTC offset). This is unmistakable against siblings like emailchef_list_custom_fields or emailchef_list_senders, and the endpoint (GET /meta/timezones) removes any ambiguity about which resource is being read.

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

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

"The id is required to schedule a campaign" tells the agent exactly why it would call this tool and where the results feed in, which is a genuine usage cue. It stops short of explicit when-not-to-use guidance or naming emailchef_schedule_campaign directly as the counterpart, so it is clear context without full routing instruction.

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 write, destructive and idempotent behavior, so the description correctly focuses on what annotations cannot express: the draft-only precondition, the non-DST fixed-offset timezone trap and how to mitigate it, and the undo window. It does not state what the campaign's resulting state is or how the tool behaves if the campaign is already scheduled or already sending.

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 tightly packed sentences, front-loaded with the write/deferred framing before the mechanics and the undo path. The trailing HTTP route is marginal value for an agent but costs little; the capitalized lead-in is slightly shouty without being wasteful.

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 3-required-param mutation with no output schema and full annotation coverage, the description covers the two things most likely to cause a bad call: scheduling a non-draft and picking a wrong timezone id. It omits what the call returns and how repeat/already-scheduled calls behave.

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 all three parameters are documented in the schema, which sets the baseline at 3. The description does add genuine semantics for timezone_id (fixed-offset, no DST, must match the send date's offset) rather than repeating the schema, but scheduled_time's format is left entirely to 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 ('schedule a DRAFT campaign') and adds the precondition that matters (must be a draft) plus scope ('all its recipients'). The 'SENDS EMAIL TO CUSTOMERS LATER' framing separates it cleanly from emailchef_send_campaign and emailchef_send_test_campaign without needing their schemas.

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

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

Gives explicit when-to-use context (deferred send of a draft), names the prerequisite lookup tool emailchef_list_timezones, and names the reversal path emailchef_unschedule_campaign before the send starts. It stops short of explicitly contrasting with emailchef_send_campaign, leaving the send-now vs send-later choice to be inferred from 'LATER'.

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, but the description adds substantive context beyond them: cannot be undone, consumes plan sends, is queued asynchronously, and requires polling emailchef_get_campaign for final state. That async behavior is not derivable from 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-loads the irreversible warning in caps before any procedural detail, which is the right ordering, and every clause carries information. It is a dense, comma-chained single paragraph, so readability suffers slightly even though 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?

No output schema exists, and the description covers the return-side behavior (async queue, poll get_campaign) as well as preconditions, side effects, and the approval gate. An agent has everything needed to invoke it safely.

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

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

Schema coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds real meaning about which campaign_id values are valid (DRAFT or FAILED only) and reinforces confirm=true as the explicit-approval gate, though it gives no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('start sending a DRAFT (or FAILED) campaign immediately to ALL its recipients') plus the endpoint, and implicitly distinguishes itself from schedule_campaign and send_test_campaign by emphasizing immediate, irreversible delivery to all recipients.

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 prerequisites and the alternative path: check recipients via emailchef_get_campaign, verify sender and subscription, ideally run emailchef_send_test_campaign first, and only proceed with explicit user approval. The 'when' and the guard conditions are spelled out rather than inferred.

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

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

Annotations already declare destructive/non-idempotent/open-world, and the description adds real value on top: the action cannot be undone, it consumes plan sends (quota impact), a verified sender is required, and the backing endpoint is POST /sendmail. These are exactly the traits an agent needs before committing an irreversible write.

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 irreversible-write warning, then prerequisites, then the endpoint. Dense and mostly waste-free, though 'WRITE, SENDS AN EMAIL NOW AND CANNOT BE UNDONE' partially duplicates the later 'send a single email' 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?

For an irreversible, quota-consuming mutation with no output schema, the description covers safety, quota cost, sender verification, and the confirmation gate. It omits what a successful call returns (message id, send status) and any failure modes such as unverified sender or exhausted plan quota.

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

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

Schema description coverage is only 25%, so the description must carry weight. It explains the two highest-risk parameters well (confirm must be true, text_body and/or html_body at least one) and points sender_id at verified senders, but leaves to_name, reply_to, and subject undocumented beyond their obvious names.

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

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

States a specific verb and resource with tight scope: send a single email to one recipient from a verified sender. The single-recipient, non-contact framing implicitly separates it from the campaign-oriented siblings (send_campaign, send_test_campaign), so an agent can route correctly 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 an explicit precondition for use: only with the user's explicit go-ahead and confirm must be true. It also clarifies the recipient need not be a contact, removing a common gating assumption. It does not, however, name the alternative tools to use when the intent is a bulk or test send.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds real context beyond them: it consumes SMS credit, cannot be undone, and returns a message id per recipient plus the remaining balance. The confirmation requirement and balance-check prerequisite are behavioral facts the 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?

Single dense sentence with the destructive/cost warning front-loaded ahead of the mechanics, so nothing important is buried. The all-caps opening clause is effective for a dangerous write but slightly noisy; every clause still carries information.

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

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

For a destructive write with no output schema, the description covers cost, irreversibility, recipient limits, phone format, the confirmation gate, the prerequisite balance check, and what the response contains. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the international format with a concrete example (+393331234567) and restates the confirm gate in operational terms. It does not document the optional `from` sender parameter or the 1600-character text limit, leaving those to 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 ("send an SMS to 1-50 phone numbers") plus the endpoint POST /sms/send, which cleanly separates it from siblings like emailchef_send_email and emailchef_send_campaign. The recipient count and format constraint are stated up front, so an agent knows exactly what the call does without opening the schema.

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

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

Explicitly routes the agent to a prerequisite sibling ("Check emailchef_get_sms_balance first") and imposes a hard human-in-the-loop gate ("send only with the user's explicit go-ahead (confirm must be true)"). It also flags the cost and irreversibility condition that should drive the decision to call at all.

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, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds genuinely new context on top: campaign state is unaffected despite the WRITE label, and the sender must be verified. It omits what happens on an unverified sender (error vs silent fail) and any rate limits, 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?

Four short sentences with zero filler; the WRITE marker and the core action are front-loaded, followed by the two behavioral constraints. Every sentence carries distinct information.

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

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

For a two-parameter, non-destructive-per-annotations write tool with no output schema, the description covers action, scope, state impact, and the sender prerequisite. The only gap is what the call returns or how a test email is distinguished (e.g., subject prefix), which is minor here.

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 email are already documented in the schema. The description only reinforces 'single address' and 'a campaign', adding no format, id-source, or validation detail beyond what the schema provides; 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 ('email ONE test copy of a campaign to a single address') with the key scoping constraint that it is a single test recipient. The phrase 'test copy' plus 'campaign state does not change' distinguishes it from emailchef_send_campaign and emailchef_send_email without needing 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?

'ONE test copy' and 'The campaign state does not change' clearly frame the tool as a pre-send verification step rather than a real send, which implicitly routes the agent away from send_campaign. It stops short of explicitly naming the alternative tool or stating exclusions, so it is clear context rather than a full when/when-not 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 already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the "WRITE:" prefix and PUT method add no new behavioral information. The description says nothing about what happens if the campaign is not archived, whether membership/statistics survive, or what error states occur.

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

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

Two short sentences, mutation flag front-loaded, no filler. Size is appropriate; it is simply thin on content rather than padded.

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

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

For a single-parameter mutation with rich annotations this is marginally adequate, but an agent gets no guidance on preconditions or side effects of restoring a campaign, which is the main thing missing given there is no output schema.

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

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

Only one parameter and schema description coverage is 100%, with the schema explaining the numeric id format and origin. The description adds nothing about the id, so the baseline 3 applies.

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

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

States a specific verb and resource ("restore an archived campaign") and the HTTP endpoint, which is enough to distinguish it from the sibling emailchef_archive_campaign by direction. It does not name the sibling explicitly, so it stops short of top marks.

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 statement of when to call this versus emailchef_archive_campaign, no prerequisite that the campaign must currently be archived, and no note about what to do if it is not. Usage is only inferable from the word "restore".

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

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

Annotations already declare the write/destructive/idempotent profile, so the remaining value is the disclosure of the concrete effect (the address becomes able to receive mail again) and the consent precondition, plus the DELETE /blockings/{email} operation. That adds real context beyond the structured fields, though it does not cover rate limits 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, each earning its place: the operation, the safety precondition, the endpoint. The action type is front-loaded so the agent sees it is a write immediately.

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

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

For a one-parameter mutation with rich annotations and no output schema, the description covers purpose, effect, precondition, and endpoint. Idempotency and destructiveness are already handled by annotations, so nothing an agent needs 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 0% for the single 'email' parameter, but the schema itself enforces the email format with a strict pattern. The description compensates where it matters by clarifying it operates on exactly one address, distinguishing this from any bulk variant.

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 ('remove') and resource ('one address from the account blocklist') plus the resulting effect ('so it can receive email again'). The singular 'one address' cleanly separates it from the sibling bulk tool emailchef_block_emails and from the read-only emailchef_list_blocked.

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 precondition: 'Only do this for an address whose owner asked for it,' which tells the agent when the call is appropriate. It does not name a sibling alternative or exclusion cases (e.g., blocked-by-system addresses), 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 and idempotentHint=true, so the safety profile is covered. The description adds genuine context beyond them: the 'WRITE:' marker, the exact state transition (SCHEDULED → DRAFT), and the HTTP method/path. It omits error behavior when the campaign is not in SCHEDULED state and any permission requirements.

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

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

Two terse sentences, front-loaded with the WRITE marker and the state transition, then the endpoint. Nothing is redundant or padded.

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

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

For a single-parameter mutation with no output schema and rich annotations, this covers purpose, precondition, effect, and endpoint. The only meaningful gap is failure behavior when the campaign isn't SCHEDULED, which an agent would likely need to handle.

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 campaign_id parameter is fully documented in the schema (numeric id, regex/integer constraint), so the baseline is 3. The description only echoes the path variable as {id}, adding no format or sourcing detail beyond what the schema already provides.

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

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

States a specific verb (cancel the schedule), a specific resource (a SCHEDULED campaign), and the resulting state (back to DRAFT), plus the underlying endpoint. The 'SCHEDULED' precondition and DRAFT outcome distinguish it cleanly from the inverse sibling emailchef_schedule_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?

The 'of a SCHEDULED campaign' precondition tells the agent exactly when this tool is applicable, and 'cancel the schedule' implies it is the inverse of scheduling. It stops short of naming emailchef_schedule_campaign as the alternative or saying what to do if the campaign is not currently scheduled.

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 openWorldHint=true, so the safety profile is covered. The description adds useful semantics the annotations don't carry — the concrete effect ('stops receiving that list's email') and the write verb — but says nothing about reversibility, whether a confirmation is needed, or what happens if the contact is not subscribed.

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

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

One sentence, front-loaded with the 'WRITE:' classification and the effect in parentheses before the endpoint. Nothing wasted, though the trailing path fragment is somewhat redundant with 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?

A two-parameter write tool with full annotation coverage and full schema coverage needs little more, and the effect statement helps. Still, the absence of any note on unsubscribing being reversible (e.g. via a resubscribe path) or on the relationship to block_emails leaves a gap for an agent choosing between the two.

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 as numeric ids as returned by the list tools. The description's URL template only restates that list_id is a path segment and contact_id a query value, adding no meaning beyond the schema.

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

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

States a specific verb and resource ('unsubscribe one contact from one list') and even the side effect in parentheses, plus the HTTP route. It is clear what the tool does, though it never distinguishes itself from the sibling emailchef_block_emails, which is the natural source of confusion.

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

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

The scope words 'one contact from one list' imply the per-list nature of the operation, but there is no explicit guidance on when to use this versus emailchef_block_emails or emailchef_update_contact, nor any prerequisite such as the contact needing an active subscription.

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

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

Discloses a genuinely non-obvious implementation behavior: the tool performs read-modify-write because 'Emailchef blanks any omitted field', so partial updates are safe despite the destructiveHint=true annotation. It also states the DRAFT-only refusal condition, which annotations cannot express. This is exactly the kind of context that changes how an agent calls the tool.

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

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

Three tight sentences, front-loaded with the write action and field scope, then the critical blanking/read-modify-write caveat, then the endpoint. No filler and nothing 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 9-parameter mutation with no output schema, the description covers the mutation model, the partial-update safety mechanism, and the draft constraint. The only modest gap is that it doesn't say what comes back (updated campaign object vs. error payload), which matters given there is no output schema.

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

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

Schema coverage is 56%, and the description compensates by enumerating the updatable fields (name, subject, body, sender, reply-to, recipient lists) and by asserting 'Only the fields you pass change', which clarifies the partial-update semantics of all eight optional params. It does not add detail on the id-typed params or the list_ids/segment_id interaction, which the schema partly covers.

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

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

Opens with an explicit verb and mode ('WRITE: change a DRAFT campaign') followed by the exact field set it can modify. An agent can distinguish it from create_campaign, clone_campaign, or schedule_campaign 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?

States the hard precondition clearly: the campaign must be a DRAFT, and the tool 'Refuses a campaign that is not a DRAFT' — which steers the agent away from using it on scheduled/sent campaigns. It does not name the specific alternative sibling (e.g. clone or create) when the campaign is not a draft, so it stops short of explicit routing.

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

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

Annotations already declare destructive=true, idempotent=true and write access; the description adds genuinely new behavior: partial-update semantics ("Only the fields you pass change") and the consent requirement for re-activation. It stops short of saying whether the custom_fields object is merged key-by-key or replaced wholesale, which matters for a destructive write.

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 waste: the write/scope statement comes first, then the partial-update rule, then the risky-value warning. Every sentence carries distinct information.

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

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

For a 6-parameter destructive write with no output schema, the description covers mutation scope, partial-update semantics and the main hazard. The one remaining ambiguity is merge-vs-replace behavior for the nested custom_fields object, which an agent would have to guess.

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

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

Schema coverage is 50%, and the description compensates by naming the mutable surface (name, state, custom fields) and giving the ACTIVE enum value real-world meaning. list_id and contact_id are left to the schema, which already documents them as numeric ids, so the description adds value where the schema is thin.

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 contact's name, state or custom fields"), scopes it to a single list, and prefixes WRITE to separate it from the many read tools. The PUT endpoint confirms the exact resource path, so an agent can distinguish this from create_contact and unsubscribe_contact 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 a concrete when-not-to-act rule ("Setting the status to ACTIVE re-subscribes someone: only do so with their consent"), which is real operational guidance. It does not, however, route the agent between this tool and the sibling emailchef_unsubscribe_contact for the UNSUBSCRIBED case, so the alternative-selection gap keeps it below 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=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds genuinely non-obvious context by clarifying that this is a partial update ('Only the fields you pass change') and naming the endpoint (PUT /lists/{list_id}), which prevents an agent from assuming a full-replace PUT. It stops short of explaining what is destructive or whether renaming affects segments/campaigns that reference the list.

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

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

One sentence plus an endpoint reference, with the operation class ('WRITE') and the key mutation semantics front-loaded. Nothing is padded or redundant.

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

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

For a 3-parameter mutation tool with rich annotations and no output schema, the description covers what is being changed and how (partial update). The remaining gap is that it doesn't warn about side effects of renaming (references from segments/campaigns) that motivate the destructiveHint flag.

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 list_id, name and description are already documented in the schema. The description only restates the two mutable fields and adds no format, constraint, or partial-update nuance beyond what the schema provides; 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 ('rename a contact list and/or change its description'), which clearly separates it from siblings like emailchef_create_list, emailchef_get_list and emailchef_list_lists. The 'WRITE:' prefix reinforces that this is a mutation, though no sibling is named as an alternative.

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 (to rename or change a list description) but never states preconditions, when-not-to-use, or which sibling to choose instead (e.g., create_list for new lists, get_list for reading). Usage must be inferred from the purpose statement.

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