Manage lists, contacts and campaigns, and read campaign performance reports on EmailOctopus.
Scored across 13 tools
Nearly every tool targets a distinct resource+action (list vs contact vs campaign), and the create/get/update/delete verb distinguishes operations clearly. The only minor overlap is between get_campaign_report and get_campaign_links_report, but the descriptions differentiate aggregate vs per-link metrics adequately.
All 13 tools follow a uniform `emailoctopus_verb_noun` pattern (create_contact, list_contacts, get_campaign_report, etc.). Verb style and casing are entirely consistent throughout, so the pattern is fully predictable.
13 tools sit comfortably in the well-scoped range and each earns its place: full CRUD for lists and contacts plus read/reporting for campaigns. No redundant or filler tools inflate the surface.
Contacts have complete CRUD, but lists lack a delete operation and campaigns are read-only (no create/send/update), which are notable gaps for an email-marketing domain. Get/list/report coverage for campaigns is useful but leaves the core campaign lifecycle unaddressable.
CREATES a new contact in a list — this MODIFIES live data (adds a subscriber). email_address is required; optionally set fields (keyed by field tag), tags, and status. EmailOctopus: POST /lists/{list_id}/contacts. Returns the created contact.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to apply to the contact, e.g. ["vip", "beta"]. | |
| fields | No | Custom field values, keyed by the list's field tag (e.g. {"FirstName": "Ada"}). | |
| status | No | Subscription status: subscribed, pending, or unsubscribed. | |
| list_id | Yes | The list's id to add the contact to. | |
| email_address | Yes | The contact's email address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry destructiveHint=true, and the description reinforces this by flagging that it MODIFIES live data and adds a subscriber. It also discloses the return ('Returns the created contact'), which matters because there is no output schema. It stops short of stating idempotency/duplicate handling or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences with the mutation warning front-loaded before the parameter summary and the endpoint. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter mutation tool with full schema coverage and no output schema, the description covers the mutation semantics plus the return value. The remaining gap is duplicate/already-subscribed behavior and any auth or rate-limit constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates that email_address is required and names the optional fields (fields, tags, status) with the key-by-field-tag convention, but adds little syntax or format detail beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('CREATES a new contact in a list') and immediately scopes it as a live-data mutation that adds a subscriber. The word 'new' plus the resource 'contact in a list' lets an agent separate it from update_contact and delete_contact without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the verb: use it when you need to add a new contact to a list. There is no explicit when-to-use/when-not guidance, no mention of what happens if the email already exists, and no routing to sibling tools such as update_contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CREATES a new list — this MODIFIES live data. Provide a name. EmailOctopus: POST /lists. Returns the created list.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the new list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this with 'this MODIFIES live data', which is consistent and useful emphasis. It adds the endpoint and return shape, but omits behavior an agent would want for a mutation: duplicate-name handling, required auth/scopes, and 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?
One short sentence with the mutation warning front-loaded, followed by the endpoint and return value. Every clause carries information, with only minor redundancy against the title 'Create list'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool whose annotations cover the safety profile, the description covers action, mutating nature, endpoint, and return value. No output schema exists, and return behavior is briefly noted, so little is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is already documented as 'Human-readable name for the new list.' The description's 'Provide a `name`' adds no syntax, constraint, or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('CREATES a new list') and the backing API call (POST /lists), so the action is unambiguous. It doesn't explicitly distinguish itself from siblings like emailoctopus_create_contact or emailoctopus_update_list, though the resource name makes the distinction largely self-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?
Says only 'Provide a `name`' with no when-to-use context, no prerequisites, and no comparison to alternatives such as update_list. An agent gets no guidance on when this is the right tool versus a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PERMANENTLY REMOVES a contact from a list — this MODIFIES live data and cannot be undone. contact_id is the MD5 hash of the lowercased email address, or the id from list_contacts. EmailOctopus: DELETE /lists/{list_id}/contacts/{contact_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list's id. | |
| contact_id | Yes | The contact's id to delete — the MD5 hash of the lowercased email address, or the id from list_contacts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds genuine value beyond that by spelling out irreversibility ('cannot be undone') and that it modifies live data. It does not cover auth requirements, rate limits, or error behavior for nonexistent contacts, 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?
One tight sentence plus an endpoint reference; the destructive/irreversible constraint is front-loaded in capitals, and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter destructive tool with no output schema and annotations covering the safety profile, the description supplies everything needed to call it correctly, including both id formats. Minor gaps remain around error handling and required permissions.
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 contact_id description in the schema is nearly identical to the description text ('MD5 hash of the lowercased email address, or the id from list_contacts'). The description adds no meaning beyond the structured fields, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope ('PERMANENTLY REMOVES a contact from a list'), which immediately separates it from get_contact, update_contact, and create_contact. The API endpoint mapping (DELETE /lists/{list_id}/contacts/{contact_id}) removes any ambiguity about what operation is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly signals when this tool applies and warns that it 'cannot be undone,' which functions as a strong when-to-be-cautious cue. It stops short of naming alternatives (e.g., update_contact for unsubscribing instead of deleting), so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single campaign by its id. Returns the campaign's full state — name, status, subject, from, content, and created_at. EmailOctopus: GET /campaigns/{campaign_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | The campaign's id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral content by promising 'the campaign's full state' and listing the fields returned, but says nothing about failure behavior (unknown id), permissions, or rate limits, so it adds only moderate value beyond the 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?
Two short, front-loaded sentences that lead with the verb and resource and then the return payload. The trailing 'EmailOctopus: GET /campaigns/{campaign_id}' line is mildly redundant with the name and schema but harmless and short.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description usefully compensates by enumerating the returned fields, and for a one-parameter read tool the remaining needs are minimal. It loses a point only because error/edge behavior for an unknown campaign_id is 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?
With a single parameter and 100% schema description coverage, the schema already documents campaign_id fully. The phrase 'by its id' restates the schema rather than adding format, example, or sourcing guidance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get a single campaign by its id') and even enumerates the returned state (name, status, subject, from, content, created_at), which separates it from report-style siblings. It does not, however, explicitly name the sibling it differs from (e.g. emailoctopus_list_campaigns or get_campaign_report), so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies the usage context (fetch one existing campaign when its id is known), but there is no explicit when-to-use, when-not-to-use, or alternative routing (list_campaigns for enumeration, get_campaign_report for metrics). Minimum viable but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a campaign's per-link click report — for each link in the campaign, the URL and its click counts. EmailOctopus: GET /campaigns/{campaign_id}/reports/links.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | The campaign's id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the annotation carries the safety profile. The description adds useful context by describing the shape of the payload (one entry per link with URL and click counts), but says nothing about pagination, rate limits, or behavior when the campaign has no links.
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 states the resource and the return shape, followed by the underlying endpoint — front-loaded and free of filler. Slightly compact; the API path is useful orientation rather than waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully tells the agent what the return contains, and the read-only annotation covers safety. For a single-parameter read tool this is close to complete; only pagination/empty-result behavior is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single required campaign_id parameter, so the schema already documents it. The description's endpoint template (/campaigns/{campaign_id}/reports/links) corroborates the identifier's role but adds no format or sourcing detail beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Get a campaign's per-link click report') and specifies the payload ('the URL and its click counts'), which separates it conceptually from the generic get_campaign_report sibling. It never names that sibling or the other campaign tools, so sibling differentiation is left implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the narrow scope of 'per-link click report' — an agent can infer this is the drill-down after a general campaign report, but the description states no when-to-use condition, no prerequisites, and no alternatives. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a campaign's aggregate performance report — sent, opened, clicked, bounced, unsubscribed, complained, and related counts. EmailOctopus: GET /campaigns/{campaign_id}/reports/summary.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | The campaign's id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read, so the description's job is lighter. It does add useful context by enumerating the aggregate counters (sent, opened, clicked, bounced, unsubscribed, complained) that the response contains, though it says nothing about freshness, scope, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence plus the API mapping; every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned counts so the agent knows what a report contains. For a single-parameter read tool this is nearly complete, though it omits any note on scope or time window of the aggregates.
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 description adds no format or sourcing detail beyond it. Baseline 3 applies when the schema already carries parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Get a campaign's aggregate performance report') and enumerates the metrics returned, which differentiates it from the sibling links report by the word 'aggregate'. It does not name the sibling tool explicitly, so an agent must infer the distinction from context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this versus get_campaign, get_campaign_links_report, or list_campaigns. Usage is only implied by the tool name and the endpoint path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single contact in a list. Returns email_address, fields, tags, status, and created_at. contact_id is the MD5 hash of the lowercased email address, or the id returned by emailoctopus_list_contacts. EmailOctopus: GET /lists/{list_id}/contacts/{contact_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list's id. | |
| contact_id | Yes | The contact's id — the MD5 hash of the lowercased email address, or the id from list_contacts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, so the bar is lower; the description adds real value by naming the return fields and explaining the contact_id format (MD5 of lowercased email, or the id from list_contacts). It stops short of covering error behavior for a missing contact.
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: purpose, return shape, then ID derivation and endpoint. Front-loaded with zero filler and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the return fields and explains the ID format, making the tool callable without guessing. It lacks only failure-mode context (e.g., behavior when the contact does not exist).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented; the description's contact_id explanation largely restates the schema's own wording. Per the baseline rule, a 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get a single contact in a list') and enumerates the returned fields, so the agent knows exactly what this retrieves. It does not explicitly distinguish itself from the sibling list_contacts beyond the singular/plural implication, which keeps it from 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 implied by 'single contact' versus the sibling emailoctopus_list_contacts, but the description never states when to choose one over the other or any exclusion. The mention of list_contacts is about deriving contact_id, not about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single list by its id. Returns the list's full state — name, contact counts by status, and created_at. EmailOctopus: GET /lists/{list_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list's id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds meaningful value beyond that, disclosing the payload contents (name, contact counts by status, created_at) and identifying the underlying endpoint GET /lists/{list_id}. It does not mention auth or rate limits, but for a simple read that is minor.
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 core action front-loaded. The trailing API endpoint reference is slightly redundant for an agent but compact and 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 no output schema, the burden of describing returns falls on the description, and it does list the main fields an agent would receive. Combined with the readOnly annotation and a fully documented single parameter, this is nearly complete; only the exact shape of the contact-count breakdown is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, fully documented in the schema with 100% coverage. The description's 'by its id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (a single list by id), which implicitly separates it from list_lists's collection view. It never names the sibling tool outright, so the differentiation rests on the reader noticing 'single' vs. list semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: fetch one list when you already have its id. There is no explicit when-to-use statement, no condition for preferring this over emailoctopus_list_lists, and no prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all campaigns in the account. Returns {data:[...],paging:{...}} — each campaign's id, name, status, subject, and created_at. Paginate with limit (max 100) and starting_after. EmailOctopus: GET /campaigns.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max campaigns to return (1..100). | |
| starting_after | No | Pagination cursor — the id to start after (from the previous page's paging). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely useful context beyond that by describing the response envelope ({data, paging}), the per-campaign fields, the 100-item cap, and the underlying API endpoint. It does not mention rate limits or total-count behavior, so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with zero filler, front-loaded with purpose, then return shape, then pagination. Every clause carries information an agent can act on.
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 supplies the return structure and pagination contract, which is what an agent needs for a list endpoint. It is essentially complete, lacking only minor operational details such as ordering or rate-limit behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema; the description restates the same facts (max 100, cursor semantics) without adding new syntax or edge-case detail. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all campaigns in the account'), and the 'all' plus account scope distinguishes it from the single-resource sibling get_campaign. It does not name a sibling alternative explicitly, so it falls short of the 5 bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description shows how to paginate but never says when to choose this over get_campaign or the report tools. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the contacts in a list. Returns {data:[...],paging:{...}} — each contact's id, email_address, fields, tags, status, and created_at. Paginate with limit (max 100) and starting_after. EmailOctopus: GET /lists/{list_id}/contacts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max contacts to return (1..100). | |
| list_id | Yes | The list's id. | |
| starting_after | No | Pagination cursor — the id to start after (from the previous page's paging). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safe read profile, so the bar is lower. The description still adds real context by disclosing the return envelope ({data, paging}), the fields per contact, and pagination behavior — valuable since 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?
Three compact sentences with no filler: purpose first, return shape and fields second, pagination and underlying endpoint last. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full schema coverage, no nested objects, and no output schema, the description supplies the missing return format and pagination contract. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both limit and starting_after are already documented at the schema level; the description largely restates them. It adds only a hint about where the cursor comes from ('the previous page's paging'), which is marginal beyond the schema's 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?
States a specific verb (list) and resource (contacts in a list), and the scope 'in a list' makes the collection-vs-single distinction clear against emailoctopus_get_contact. It does not explicitly name a sibling alternative, so it stops short of the top band.
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?
Pagination mechanics are explained (limit max 100, starting_after), but there is no explicit when-to-use guidance or routing to alternatives such as emailoctopus_get_contact for a single record. Usage is implied by the verb and scope rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all lists in the account. Returns {data:[...],paging:{...}} — each list's id, name, contact counts by status, and created_at. Paginate with limit (max 100) and starting_after (cursor from the previous page). EmailOctopus: GET /lists.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max lists to return (1..100). | |
| starting_after | No | Pagination cursor — the id to start after (from the previous page's paging). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavioral detail by disclosing the response envelope ({data, paging}) and each record's fields (id, name, contact counts by status, created_at). It does not discuss rate limits or empty-account behavior, but for a read-only endpoint this is solid added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with purpose, then return shape, then pagination mechanics. No filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly compensates by sketching the return envelope and record fields. Combined with full parameter documentation and clear pagination instructions, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `limit` (1..100) and `starting_after` are already fully documented in the schema. The description mostly restates the max of 100 and that the cursor comes from the previous page's paging block, adding little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all lists in the account') and disambiguates from `emailoctopus_get_list` by making clear this enumerates every list rather than one. The added note 'EmailOctopus: GET /lists' pins the exact upstream operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when this tool applies (full account enumeration) and explains the pagination path via `limit`/`starting_after`. It does not explicitly name alternatives such as `get_list` for a single list or `create_list`, so it stops short of the when/when-not standard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
UPDATES an existing contact in a list — this MODIFIES live data. Send only the fields you want to change (email_address, fields, tags, status). contact_id is the MD5 hash of the lowercased email address, or the id from list_contacts. EmailOctopus: PUT /lists/{list_id}/contacts/{contact_id}. Returns the updated contact.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to apply to the contact, e.g. ["vip", "beta"]. | |
| fields | No | Custom field values, keyed by the list's field tag (e.g. {"FirstName": "Ada"}). | |
| status | No | Subscription status: subscribed, pending, or unsubscribed. | |
| list_id | Yes | The list's id. | |
| contact_id | Yes | The contact's id — the MD5 hash of the lowercased email address, or the id from list_contacts. | |
| email_address | No | The contact's email address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description reinforces that with 'this MODIFIES live data', while adding genuinely new context: partial-update semantics (only supplied fields change), the underlying PUT endpoint, and that the updated contact is returned. It does not cover auth/permission requirements or behavior when contact_id matches nothing, which keeps it at a 4.
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 warning that this modifies live data is front-loaded, and the three sentences stay tight with no filler. The contact_id MD5 explanation duplicates the schema and could be trimmed, which is the only minor waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly supplies the return contract ('Returns the updated contact'), plus the endpoint and required identifiers. For a mutation tool it is nearly complete, though it omits what happens to fields not supplied (cleared vs preserved) and error behavior for a missing contact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents contact_id as the MD5 hash of the lowercased email and enumerates status values, so the description largely restates structured data. Its only added semantic is the 'send only fields you want to change' partial-update contract, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('UPDATES an existing contact in a list') and explicitly contrasts it with creation/read siblings by noting it MODIFIES live data. It also pins the exact endpoint (PUT /lists/{list_id}/contacts/{contact_id}), so an agent can distinguish it from create_contact, get_contact and delete_contact without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operating guidance — send only the fields you want to change, listing email_address, fields, tags and status — which tells the agent this is a partial update rather than a replace. It does not explicitly name alternatives or exclusions (e.g. use create_contact when the contact does not yet exist), 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.
UPDATES an existing list by id — this MODIFIES live data. Sets the list's name. EmailOctopus: PUT /lists/{list_id}. Returns the updated list.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new name for the list. | |
| list_id | Yes | The list's id to update. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this with "this MODIFIES live data" and discloses exactly what is mutated (the list's `name`) plus the return value. It stops short of auth requirements, whether the old name is recoverable, or uniqueness constraints on the new name.
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 compact sentence front-loads the mutation warning and the resource, then names the field and the underlying endpoint. No 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?
For a two-parameter mutation with full schema coverage and an explicit destructive annotation, the description covers purpose, mutability, changed field, and return value. It lacks edge-case behavior (name collisions, failure modes), which would be needed for a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (list_id, name) are documented in the schema, so the baseline is 3. The description repeats that it "Sets the list's `name`" but adds no format, constraint, or validation detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("UPDATES an existing list by id") and narrows the scope of the mutation to setting the list's `name`, so an agent knows this is a rename, not a general-purpose update. It does not name or contrast with any sibling (e.g. create_list, get_list, update_contact), which keeps it 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?
There is no explicit when-to-use or when-not-to-use guidance and no alternative named. The only implicit signal is "existing list by id", which the agent must infer means the list must already exist rather than be created.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read audiences, members, campaigns and reports; add, update, tag and archive subscribers.
Send email and read templates, marketing contacts, lists, stats, bounces and unsubscribes.
Read Enginemailer subscribers, lists and campaigns; add subscribers, create and send campaigns.
Manage Benchmark Email lists and contacts, and read campaign reports: opens, clicks, bounces.
Add one secure layer between your agents and this server.