mailchimp

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

The description adds the behavior of the 'pending' status triggering a double-opt-in email, which is beyond the destructiveHint annotation. This provides useful context about side effects. However, it does not disclose duplicate-member 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?

The description is two sentences, front-loading the main purpose ('Add a new member to an audience') and including only a behavioral note and REST endpoint. Every sentence contributes 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?

Despite the destructiveHint annotation, the description doesn't mention what happens on success, return values, or handling of existing members. Given no output schema and nested parameters, the description is somewhat thin for a mutation tool, but full schema coverage and a simple operation keep it 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?

The input schema already provides 100% parameter descriptions, so the baseline is 3. The tool description adds no additional parameter semantics beyond what's in the schema; even the pending status note is duplicated in the schema's status field description.

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

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

The description uses a specific verb ('Add') with a clear resource ('new member (subscriber)') and target ('audience (list)'), distinguishing it from sibling tools like mailchimp_update_member and mailchimp_archive_member.

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 clearly establishes the tool's context (adding a new member) but does not explicitly name alternatives or exclusions. The 'new' keyword implicitly differentiates from update/archive, but there's no direct 'when not to use' 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?

Beyond the destructiveHint annotation, the description adds behavioral details: returns HTTP 204 with no body, uses REST POST endpoint, and explains email-to-subscriber_hash MD5 conversion. These are useful operational insights that are not present in annotations, though it does not mention required permissions 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?

The description is two concise sentences that front-load the primary purpose and immediately add the key behavioral notes (status mapping, HTTP 204, hashing). No filler or redundant text; every sentence contributes 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?

Given the tool's moderate complexity (5 params, no output schema), the description is complete: it explains the HTTP 204 no-body outcome, the endpoint, and the email/subscriber_hash distinction. The existing schema covers params, and the description fills the behavioral gaps without overspecifying.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it restates the active/inactive mapping and email hashing that the schema already documents. It adds no extra param details or relationships, so the score remains at 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 clearly states the tool's action: 'Add and/or remove tags on an audience member'. It specifies the resource (tags) and the target (audience member), and distinguishes from sibling tools like mailchimp_list_member_tags by focusing on modification. The verb+resource+scope is specific and unambiguous.

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

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

The description provides clear context: use this tool to add or remove tags, with tags/removeTags mapped to active/inactive statuses. However, it does not explicitly name alternatives or specify when not to use this tool. Since siblings like list_member_tags exist for reading, the context is clear but no exclusions 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 only indicate destructiveHint=true, but the description adds crucial context: the action is reversible/soft-remove, the HTTP method (DELETE), and the return status (204 no body). This goes beyond the annotation without contradiction.

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 concise sentences front-load the purpose, then provide the REST endpoint and response details. Every sentence earns its place with no fluff.

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 tool with no output schema, the description covers the return (204 no body), the hash mechanism, and the reversibility. It is complete for the tool's 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%, so the baseline is 3. The description adds value by explaining the email-to-MD5 hash transformation and the relationship between email and subscriberHash, which the schema does not fully convey.

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

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

The description uses a specific verb+resource: 'Archive (soft-remove) an audience member' and clearly distinguishes from the permanent-delete action, making its purpose unmistakable and differentiating it from sibling tools.

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

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

It explicitly states this is NOT the permanent-delete action, providing a when-not guideline. It also implies when to use it (reversible removal), but does not name specific alternative tools.

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, so the safety profile is covered. The description adds value by specifying exactly what data is returned (account name, subscribers, contact info, plan, industry stats) and the REST endpoint, which is useful behavioral context beyond the annotation.

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

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

The description is a single, information-dense sentence followed by a REST path. It is front-loaded and every part earns its place, with no redundancy or filler.

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

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

For a parameterless read-only account retrieval tool, the description fully covers what it does and what it returns. It is complete enough for an agent to select and invoke it correctly, especially with the sibling list providing contrast.

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 description doesn't need to explain parameter semantics. The baseline for 0 params is 4, and the description appropriately omits any parameter details.

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 the tool's purpose: getting the API Root for the authenticated Mailchimp account, and lists specific data returned (account name, total subscribers, contact info, plan, industry stats). This distinguishes it from sibling tools that target members, campaigns, or audiences.

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 context is clear: this tool is for retrieving the authenticated account's information, as opposed to the many resource-specific sibling tools. However, it doesn't explicitly mention when to use it over alternatives, though the sibling list makes this obvious. Slight deduction for not stating exclusions.

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

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

The annotations already declare readOnlyHint=true, signaling a safe read-only operation. The description adds the REST method GET and the included fields, but does not disclose additional behavioral traits like auth requirements, rate limits, or error scenarios. This is adequate given the annotation coverage but not above baseline.

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 concise, front-loaded with the action, and includes the REST endpoint for additional clarity. Every sentence provides useful information without redundancy.

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

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

For a simple single-resource GET with one parameter and no output schema, the description provides sufficient context by naming key returned fields and the REST endpoint. It slightly under-specifies the full return structure, but is complete enough for this straightforward operation.

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 input schema has 100% coverage with 'list_id' described as 'The audience (list) id', and the description reiterates the use of an id. Since the schema carries the full parameter meaning, the description adds little beyond what is already structurally available, matching the baseline for high schema 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?

The description clearly states 'Get a single audience (list) by id', specifying the verb, resource, and unique selection by id. It also lists the returned content (subscriber stats, default from-name/email, settings), which distinguishes it from sibling tools like mailchimp_list_audiences that list multiple audiences.

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 makes it clear this tool is for fetching one specific audience by id, which provides clear context for when to use it. It does not explicitly mention alternatives or exclusions, but the wording 'single audience' versus the sibling 'list_audiences' implies the appropriate use case.

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, so the safety profile is covered. The description adds value by disclosing the scope of the response (settings, recipients, send status) and the REST endpoint, providing context beyond the annotation. It does not detail rate limits or auth, but those are less critical for a read-only get operation.

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

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

The description is two short sentences, front-loaded with the core action, and every word earns its place. No redundancy or fluff.

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 get-by-id tool with one parameter and no output schema, the description is complete: it states what is retrieved (the campaign with settings, recipients, send status) and the HTTP method/path. Sibling tools are not needed for disambiguation here because the purpose is crystal clear.

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%: the lone parameter 'campaign_id' is described as 'The campaign id.' The description adds minimal extra meaning by saying 'by id' and including the REST path template, but the schema already does the heavy lifting. 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?

The description clearly states a specific verb+resource: 'Get a single campaign by id'. It specifies what is included (settings, recipients, send status) and distinguishes from sibling tools like 'mailchimp_list_campaigns' (which lists) and 'mailchimp_get_campaign_report' (which gets a report).

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 when to use: when you need a specific campaign by its id. It does not explicitly mention alternatives or when not to use, but the context is clear enough given that sibling tools cover listing and reports. Lacks explicit exclusions, so not 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 provide readOnlyHint=true, covering the safety profile. The description adds the return composition (opens, clicks, etc.) and the REST endpoint, but does not disclose additional behaviors such as error handling or rate limits. Given the annotation coverage, this is adequate but not rich.

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

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

One sentence plus REST endpoint, front-loaded and zero waste.

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

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

For a simple read-only GET with one parameter and no output schema, the description provides the purpose, scope, and return contents. It is sufficient for an agent to select and invoke the tool.

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

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

Schema coverage is 100%; the description does not add any new meaning to campaign_id beyond the schema. Baseline of 3 applies.

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

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

The description uses the specific verb 'Get' with the resource 'report for one campaign', enumerating the engagement stats returned. This clearly distinguishes it from siblings like mailchimp_get_campaign (campaign details) and mailchimp_list_reports (all reports).

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

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

The phrase 'for one campaign' establishes that this tool is for a single campaign's report, contrasting with list_reports. However, it does not explicitly name alternatives or state when not to use it, so clear context but no exclusions.

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

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

Annotations already provide readOnlyHint=true, so the read-only nature is covered. The description adds valuable context beyond annotations by specifying the REST endpoint (GET /lists/{list_id}/members/{subscriber_hash}), the email-to-MD5 hashing behavior, and the response contents (status, merge fields, tags, stats).

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

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

The description is a single sentence plus a REST reference, front-loaded with the action and resource. Every clause adds value: the resource type, lookup methods, included fields, and the hashing mechanism. There is zero 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 3 parameters, no output schema, and readOnlyHint annotations, the description covers the core behavior, response contents, and hash conversion. However, it omits that subscriberHash can also accept a contact id (as noted in the schema), which is a minor completeness gap for a retrieval tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the REST path template and confirms that email is hashed to subscriber_hash, but this is duplicative of the email parameter's description. The subscriberHash parameter's ability to accept a contact id is present in the schema but not reinforced in the description.

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

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

The description starts with 'Get a single audience member (subscriber)', using a specific verb and resource that clearly distinguishes this tool from siblings like list_members or search_members. It also specifies the lookup modes (by email or subscriber_hash) and the included data fields, making the purpose unmistakable.

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

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

The description implies the tool is for retrieving a specific member by identifier but does not explicitly mention when to use this versus alternatives like list_members or search_members. There is no when-not-to-use guidance or named alternatives, which is a missed opportunity for clarity.

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

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

With readOnlyHint=true already provided, the description adds valuable behavior context: pagination, optional sort, and the REST GET /lists mapping. No contradictions with annotations, and no destructive behavior implied.

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, efficiently structured sentence that front-loads the core action, then adds clarifying details (resource mapping, pagination, sort) without any redundancy or filler.

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

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

For a simple read-only list operation with fully documented parameters and no output schema, the description is adequate. It conveys the essential behavior (list, pagination, sort) and the resource identity, though it could optionally mention the return type (array of audiences) but that is strongly implied.

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?

All four parameters have full descriptions in the schema (100% coverage), so the description does not need to compensate. It mentions pagination and sort but adds no extra semantic value 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?

The description uses a specific verb+resource ('List the account's audiences') and clarifies the Mailchimp /lists resource, clearly distinguishing it from sibling tools like mailchimp_get_audience. The REST endpoint reference further reinforces the exact 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: it lists all audiences for the account, is paginated, and supports optional sorting. It does not explicitly name alternatives or when-not-to-use, but the scope is unambiguous for a list operation.

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

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

The annotations already declare readOnlyHint=true, and the description adds the paginated behavior and provides the REST endpoint, which is beyond what annotations convey. It also clarifies the scope ('account's classic automations'), giving useful context about what is retrieved. This exceeds the minimal bar for a safe read operation.

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

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

The description is extremely concise, consisting of a single clear verb phrase plus a terse note on pagination and the REST endpoint. Every word contributes to understanding, and no filler or redundant information exists. The key action 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 simple list tool with good annotations and schema, the description is nearly complete. It states the resource type, scope, pagination behavior, and the REST reference. There's no output schema, but the return type (a list of automations) is implicit. It doesn't discuss edge cases like empty results or error handling, but that's not expected for such a straightforward list operation.

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 input schema covers 100% of the parameters (count and offset) with descriptive text, so the baseline is 3. The description adds no extra parameter meaning beyond noting 'Paginated,' which is already implied by the offset parameter. It does not elaborate on default values or constraints that the schema doesn't already provide.

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 the tool lists the account's classic automations (automated email workflows). The phrasing 'classic automations' with parenthetical clarification distinguishes it from potential sibling tools for campaigns or other resources. It leaves no ambiguity about the target resource.

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 provides clear context: it operates at the account level and returns classic automations in a paginated manner. While it does not explicitly name alternatives or exclusions, the sibling tools serve different resource types (campaigns, audiences, etc.), making the intended use obvious from the resource name. The pagination hint also indicates it is the go-to tool for browsing automations.

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

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

The readOnlyHint annotation already indicates a read-safe operation. The description adds useful behavioral context by stating the operation is paginated and supports optional filters and sorting, plus the REST endpoint for reference. No contradictions with 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?

Two concise sentences with no fluff. The first sentence states the purpose, the second adds pagination/filter/sort behavior and the REST endpoint. Every word earns its place.

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

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

For a list tool with 7 parameters and no output schema, the description covers the essential behavior (pagination, filters, sort) and clarifies what campaigns are. It does not explain return values, but that is less critical given the tool type. Minor gap: no explicit mention of default count or max, but these are in the schema, so the description is sufficiently complete.

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

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

The input schema has 100% coverage with each parameter described. The description mentions 'type/status/audience filters and sort' which maps to the schema but adds no new detail beyond it. Per the rubric, high schema coverage yields a baseline of 3, and the description doesn't elevate beyond that.

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 the verb 'List' and the resource 'the account's campaigns', with clarification that campaigns are 'email sends'. It distinguishes from sibling tools like get_campaign (single campaign) and list_reports (reports), and mentions optional filters and sorting, making its purpose unambiguous.

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

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

The description provides clear usage context: it is for listing campaigns with pagination and optional type/status/audience filters and sorting. While it doesn't explicitly name alternatives or state when not to use it, the context is sufficient given the sibling tools and the description's clarity.

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

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

The description adds behavioral details beyond the readOnlyHint annotation by disclosing pagination, optional status filtering, and sorting. It also provides the REST endpoint, which gives insight into the underlying operation. However, it does not describe return formats or potential rate limits, which are not covered by annotations.

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

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

The description is a single, front-loaded sentence that names the purpose, then adds the key behaviors (paginated, optional status filter, sort) and the REST endpoint. Every word earns its place, with no redundancy or filler.

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

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

For a list tool with 6 parameters and no output schema, the description covers the essential aspects: purpose, pagination, filtering, sorting, and the REST method. It does not explain return value structure or pagination specifics beyond what the schema provides, but given the schema's richness and annotations, it is adequately complete.

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

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

The input schema already provides 100% coverage of parameter descriptions, including defaults and enums. The description adds no new semantic meaning for parameters beyond mentioning 'optional status filter and sort', which is already stated in the schema. The REST endpoint is a minor addition but does not significantly enhance parameter understanding.

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 the tool lists members of an audience, using a specific verb and resource. It distinguishes itself from siblings like mailchimp_get_member (single member) and mailchimp_search_members (search) by explicitly focusing on listing all members with pagination, status filter, and sort options.

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 provides clear context for when to use the tool: when you need to list members of a specific audience, with support for pagination, filtering by status, and sorting. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to differentiate it from sibling tools.

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. The description adds behavioral context about pagination and the email-to-MD5-hash conversion, which is useful beyond the annotation. It does not describe response shape, but this is acceptable for a simple read 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?

Two sentences, front-loaded with the action, includes the REST endpoint and key constraints. Every word earns its place; there is no redundancy or fluff.

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 operation, the description covers what the tool does, how to identify the member, pagination, and the REST path. Combined with a fully described schema and readOnly annotation, no critical information is missing.

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

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

Schema coverage is 100% with thorough parameter descriptions, so the baseline is 3. The description's 'email → MD5 hash' line repeats information already in the schema's email parameter description, adding no significant semantic value 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 uses a specific verb ('List') and resource ('tags applied to a single audience member') and includes the REST endpoint, clearly distinguishing it from sibling tools like mailchimp_add_member_tags or mailchimp_list_members.

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 clearly states the scope (single member) and the two identification methods (email or subscriber_hash), providing clear context for when to use this tool. It does not explicitly name alternatives or exclusions, 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?

The description adds behavioral context beyond the readOnlyHint annotation by specifying that results are paginated, filterable by type, and limited to sent campaigns. It does not contradict the annotation and provides useful details for a read operation.

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

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

The description is two concise sentences that front-load the core purpose, followed by pagination/filter details and the REST endpoint. Every word earns its place, with no redundancy.

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

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

The description covers the essential aspects: what is listed, that it is paginated, the optional type filter, and the scope (sent campaigns). Although no output schema exists, the phrase 'aggregate performance' gives a useful hint about the contents. Minor gap: no explicit mention of the return structure, but adequate for a list tool.

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

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

The input schema provides complete descriptions for all three parameters (type, count, offset), so with 100% schema coverage the baseline is 3. The description only mentions 'Paginated' and 'optional type filter', which adds minimal value 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 clearly states 'List campaign reports' with a specific verb and resource, and the parenthetical 'aggregate performance for sent campaigns' clarifies exact scope. This distinguishes it from sibling tools like list_campaigns (which lists campaigns) and get_campaign_report (which retrieves a single report).

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 provides clear context that this is the tool to use when you need aggregate performance for sent campaigns, and notes pagination and optional type filtering. However, it does not explicitly name alternatives or exclusions, such as pointing to get_campaign_report for individual campaign details.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it states the result is paginated and clarifies that saved segments include static tags, which affects the data returned. The REST endpoint also gives implementation detail.

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

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

The description is a single sentence plus the REST endpoint, front-loaded with the action and resource. Every clause adds value with no waste or redundancy.

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

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

For a simple list operation with full parameter schema, a read-only annotation, and no output schema, the description covers purpose, pagination, and REST method. The note about static tags adds useful domain detail, making the tool self-sufficient for an agent.

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?

All three parameters have schema descriptions (100% coverage), so the schema fully handles parameter semantics. The description adds no parameter-specific meaning beyond mentioning pagination, which is already reflected in the count/offset parameters.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'an audience's segments and tags', including the nuance that saved segments include static tags. This unambiguously distinguishes it from sibling list tools for members, campaigns, and reports.

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

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

The description implies the tool should be used to retrieve segments and tags for an audience and notes that it is paginated, but it does not explicitly state when to use it over alternatives or mention any exclusions. No sibling alternatives are referenced.

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, so the agent knows it's safe. The description adds behavioral context about pagination, type filtering, and sorting, plus the REST method (GET) which reinforces the read-only nature. However, it does not disclose details like rate limits, authentication specifics, or return format, which are not covered by annotations. This is comparable to the calibration example where a 3 was given.

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

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

The description is extremely concise, with only three short sentences: the core action, the pagination/filter/sort features, and the REST endpoint. It is front-loaded with the verb and resource, and every sentence adds value. No fluff or repetition.

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

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

The tool is simple, has a readOnlyHint, and a fully described schema. The description covers the resource, pagination, and filtering. It does not explain the return shape, but no output schema exists, and for a list endpoint this is often predictable. The description is complete enough for most use cases.

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 all five parameters already have descriptions. The description adds a high-level mention of 'optional type filter and sort' but does not provide any new semantic details beyond the schema. Baseline 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?

The description clearly states the action ('List') and the resource ('the account's email templates'), with a parenthetical clarifying 'saved and pre-built layouts'. This is specific and distinguishes it from sibling list tools that target different resources (audiences, campaigns, members).

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 provides clear context for when to use the tool: to list email templates. It mentions pagination and optional type filter and sort, which indicates how to customize the request. It does not explicitly name alternatives or when-not-to-use scenarios, but given the unique resource (templates), the usage context is clear enough.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds behavioral context by stating 'Returns exact + full-text matches' and clarifying the search scope. It does not contradict annotations and offers useful extra information about match behavior, going beyond what annotations provide.

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 concise, with three short sentences that each add key information: purpose, match behavior, and REST endpoint. No fluff or repetition, and it is front-loaded with the primary action.

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?

Although no output schema exists, the description gives a hint about return behavior ('Returns exact + full-text matches'), implying a list of matching members. For a simple search tool with well-documented parameters and annotations, this is adequate, but a more explicit description of the return structure would elevate it to 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 coverage is 100% with both parameters described. The description adds value by specifying what the query can contain ('email, name or other fields') and clarifying that list_id restricts to 'one audience'. This enriches the schema descriptions, earning 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 states a specific verb ('Search') and resource ('members'), with scope ('across the account or one audience') and searchable fields ('email, name or other fields'). This distinguishes it from sibling tools like mailchimp_list_members (listing all) and mailchimp_get_member (fetching by ID).

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: searching members by arbitrary fields across the entire account or a specific audience. It does not explicitly name alternatives or exclusions, but the context of searching by email/name/other fields clearly differentiates it from listing or getting members. The lack of explicit alternative naming prevents 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?

The annotation already provides destructiveHint=true, and the description adds valuable behavioral details: partial update semantics ('Only the fields you supply change') and the email-to-MD5-hash transformation. This goes beyond the annotation without contradicting it.

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

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

The description is extremely concise, with three short sentences that front-load the action and add only relevant details: action, partial-update behavior, and REST endpoint/hash context. Every sentence earns its place with no redundancy.

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

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

The description is complete enough for this tool's complexity. It covers purpose, identification, partial-update behavior, and endpoint. While there is no output schema to explain return values, that is not essential for invoking an update tool; required parameters are already documented 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 the baseline is 3. The description adds extra meaning by clarifying the partial-update behavior, which applies to all optional parameters. This is not explicitly stated in the schema descriptions and helps the agent understand parameter 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?

The description clearly states the action ('Update'), the specific resource ('existing audience member'), and the means of identification ('by email or subscriber_hash'). It distinguishes itself from sibling tools like add_member and archive_member by explicitly targeting existing members for modification.

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 clearly implies use for updating existing members rather than adding or archiving. It provides contextual guidance that only supplied fields change, which helps the agent decide when to use this tool. However, it does not explicitly name alternative tools or state when not to use it.

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