Benchmark Email MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=false and a write operation, so the description adds rather than repeats: it discloses that the call may silently UPDATE an existing contact and that the vendor decides which path is taken. That is meaningful behavioral context for a non-idempotent, destructive write. It stops short of stating permission requirements for the API key or any 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?

Three compact sentences, front-loaded with the WRITE marker and the core action, then constraints. The trailing endpoint string is mildly redundant for an agent but does not dilute the message.

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

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

For a mutation tool with no output schema, the description covers the critical unknowns: that it is a write, that it can mutate an existing contact, that no email is dispatched, and the consent precondition. Missing only return shape (e.g., resulting contact id) and how duplicates/errors surface.

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 reinforces the consent semantics behind the permission flag but adds no syntax or format detail beyond what the schema already documents for the 7 parameters, including the nested custom_fields object.

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

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

States a specific verb+resource ("add one contact to a list") with the WRITE marker and even the underlying endpoint. It also discloses the upsert twist, which helps separate it from pure-create tools, though it never names benchmark_update_contact as the sibling an agent might confuse it with.

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

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

Gives a real eligibility condition ("Only add people who agreed to get email") and rules out a side effect ("does not send any email"), but provides no when-to-use vs. benchmark_update_contact/unsubscribe_contact routing guidance. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the 'WRITE:' tag merely restates structured data. The description adds no auth requirements, rate limits, duplicate-name behavior, or effects beyond the annotation profile.

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

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

Two compact fragments, front-loaded with the WRITE signal and the resource. The 'POST /Contact/' endpoint is slightly developer-facing but is legitimate API context, so there is very little 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 two-param create tool whose annotations cover the write/destructive profile and which has no output schema, the description is minimally adequate. It omits what happens with a duplicate name and what the call returns, which a caller would benefit from knowing.

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

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

Schema description coverage is 100% with only two simple string params, so the schema already documents both fields fully. The description adds no syntax, format, or constraint detail beyond it, 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?

States a specific verb and resource ('create an empty contact list'), which clearly separates it from the read-oriented siblings (benchmark_get_list, benchmark_list_lists) and from benchmark_add_contact. It does not name any sibling explicitly, so it stops 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?

The 'WRITE:' prefix implies this is the mutation counterpart to the get/list tools, but there is no explicit when-to-use guidance, no named alternative (e.g., use benchmark_add_contact to populate it), and no mention of prerequisites or duplicate-handling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered and the bar is low. The description adds the returned field set and the underlying endpoint (GET /Client/ProfileDetails), which is useful context, but discloses nothing about rate limits, caching, or token-scope 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?

Two sentences, resource and scope front-loaded, followed by the endpoint and a compact field list. Every element carries information and there is no filler, though the field enumeration is slightly dense.

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 compensates by naming the fields returned, and there are no parameters or complex nesting to document. It is essentially complete for a token-scoped read, though it could note what happens when the token is invalid or unauthorized.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's field enumeration concerns the response body, not inputs, and correctly doesn't pretend otherwise.

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 ('The Benchmark Email account this token belongs to') and enumerates the fields returned (client id, name, company, email, status, plan products, contact count, emails sent). It does not explicitly differentiate from siblings like benchmark_get_plan or benchmark_get_settings, which overlap on plan/account data, so it stops 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 text, and no alternative sibling is named. Usage is only implied by the zero-parameter account-profile framing, which makes it clear enough to call but offers no routing help against get_plan/get_settings.

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

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

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real value beyond that by disclosing the return shape: all fields with Field1...Field24 holding custom columns, which tells the agent how to interpret results rather than just that the call is safe.

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

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

Two short sentences with the resource and scope front-loaded, no filler. The raw GET path is somewhat redundant with the tool name but cheaply conveys the list/contact hierarchy.

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

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

There is no output schema, and the description compensates by explaining what comes back (all fields, with Field1...Field24 as the custom columns). For a simple two-parameter read, that is nearly complete; only auth or error 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%, so both list_id and contact_id are fully documented in the schema as digit-only IDs. The description adds no new parameter semantics beyond the endpoint path, so the baseline 3 applies.

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

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

The description names a specific verb+resource: fetch a single contact from a list, and the singular 'One contact' distinguishes it from the plural list/search siblings. However, it never names those alternatives (benchmark_list_contacts, benchmark_search_contacts) explicitly, so the differentiation is implicit rather than stated.

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

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

Usage is only implied by 'One contact of a list' plus the required list_id/contact_id pair, which suggests direct ID lookup. There is no statement of when to use this versus benchmark_list_contacts or benchmark_search_contacts when the ID is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the content shape of the response (subject, sender, lists, dates, settings) but says nothing about auth, rate limits, or error behavior for a missing/invalid id.

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

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

Two compact fragments, front-loading the resource and its contents before the underlying endpoint. Nothing is padded, though the terseness borders on omitting useful routing context.

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

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

For a read-only getter with a fully documented single parameter, this is largely sufficient, and enumerating returned fields is genuinely useful given there is no output schema. The only gap is the absence of when-to-use routing against the many sibling getters.

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 email_id parameter is fully documented with its digit-only pattern and provenance from the list tools. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('One email campaign') and enumerates the returned fields, which is clearer than a bare name restatement. The singular framing implicitly distinguishes it from benchmark_list_emails, though it never names siblings such as get_email_report or get_email_opens for contrast.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The agent can infer this fetches a single campaign by id, but nothing states when to prefer this over list_emails, get_email_report, or the per-metric 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the underlying GET endpoint and the shape of the returned data (contact, address, time, bounce type), which is useful context, but says nothing about pagination, rate limits, or whether results are scoped to a single send.

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

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

Two compact sentences, front-loaded with purpose and return contents. The trailing endpoint path is mildly redundant for an agent but not wasteful enough to drop the score.

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

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

With one required parameter, no output schema, and full annotation coverage, the description compensates for the missing output schema by listing the returned fields. It is nearly complete; only scope/pagination 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 coverage is 100% and the single email_id parameter is fully documented in the schema (digits only, as returned by list tools). The description only implies the parameter via 'for an email' and adds no format or source detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (which addresses bounced) and resource (for an email), and enumerates the returned fields (contact, email address, time, bounce type), which distinguishes it from the sibling report tools like get_email_opens, get_email_clicks, and get_email_unsubscribes. It does not name any sibling explicitly, so it falls short of a 5.

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

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

Usage is implied by the resource ('bounced for an email'), but there is no statement of when to prefer this over get_email_report or the other per-email report tools, and no prerequisites or exclusions. Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety and access profile are covered. The description adds the underlying endpoint path and the returned field set, but says nothing about pagination, result caps, or auth scoping that a large click report would need.

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

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

Two terse, front-loaded sentences with no filler. The raw endpoint path in sentence two is mildly redundant with the tool name but is short enough not to hurt.

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

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

No output schema exists, so the description carries the return-shape burden and does so at a summary level (contact, email, time). For a single-parameter read tool with annotations covering safety, this is nearly complete, missing only volume/pagination expectations.

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

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

Only one parameter and schema description coverage is 100% (the email_id format and origin are documented in the schema), so the baseline is 3. The description's 'contact, email address and time' describes output, not the parameter, adding no meaning beyond the schema.

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

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

Specific verb+resource: retrieves who clicked a link in a given email, and enumerates the returned fields (contact, email address, time). It distinguishes itself from adjacent report siblings like benchmark_get_email_opens and benchmark_get_email_bounces by naming 'clicked a link' explicitly, though it never names those siblings.

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

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

No when-to-use, prerequisites, or alternative routing is given. An agent must infer that this is a per-email engagement report and that get_email_opens/get_email_bounces/get_email_report cover the other metrics, with no textual help.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that no output schema exists by listing the returned fields (contact, address, time, device), but says nothing about pagination ordering, rate limits, or prerequisites such as the email having been sent.

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

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

Two short sentences, with the return contents front-loaded and no filler. The trailing REST path 'GET /Emails/{email_id}/Report/Opens' is largely redundant given the tool name and adds little for an agent, keeping it just short of 5.

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

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

With no output schema, the field enumeration is genuinely helpful and is the main completeness contribution. However, for a report tool an agent may need to know the scope (single email id, sent campaigns only) and result ordering, neither of which is addressed; the description is adequate but not 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?

Schema description coverage is 100%, so email_id, page, and page_size are already fully documented in the schema, including the 'pass the previous reply's next_page' note. The description contributes nothing parameter-related, so the baseline of 3 applies.

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

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

The description names a specific resource ('email opens') and enumerates the returned fields (contact, email address, time, device), which makes the purpose concrete. It does not explicitly differentiate itself from adjacent report siblings like benchmark_get_email_clicks or benchmark_get_email_bounces, but the 'opens' subject is unambiguous.

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

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

There is no statement of when to use this tool versus benchmark_get_email_report, get_email_clicks, or get_email_bounces. Usage is only implied by the tool name, which leaves the agent to infer that this is the opens-specific slice of the report family.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the REST endpoint and the metric list, which is modestly useful context, but says nothing about rate limits, result freshness, or what happens for an email with no sends.

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 spend no words on preamble; the endpoint path is arguably redundant but harmless. Efficient overall.

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

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

No output schema exists, so the enumeration of returned fields (recipients, opens, clicks, bounces, unsubscribes, forwards, complaints, rates) usefully compensates for the missing return definition. For a single-parameter read tool with annotations covering safety, this is nearly 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?

Only one parameter (email_id) and the schema already documents it fully with format and origin ('as returned by the list tools'). The description adds no parameter-level meaning, so the high schema coverage makes a baseline 3 correct.

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 ('report summary of one email') and enumerates the metrics returned, so an agent knows it fetches aggregated per-email stats. It does not, however, differentiate itself from close siblings like benchmark_get_email (email details) or benchmark_list_email_reports (report listing), and the granular siblings (get_email_opens, get_email_clicks) make the aggregate-vs-single-metric distinction inferable 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?

No when-to-use guidance at all: no mention of when to prefer this aggregate report over benchmark_get_email_opens/clicks/bounces or over benchmark_list_email_reports. The agent must infer the routing from tool names alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. With no output schema, the description earns credit for disclosing the result shape (per-recipient fields plus a count per reason), which the agent cannot learn from structured fields. It omits pagination and auth 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 compact clauses with the returned data front-loaded, so an agent learns the payload before the endpoint. The trailing raw route string adds little for an agent but costs almost nothing.

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

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

For a single-parameter read tool with annotations covering the safety profile, the description is nearly sufficient, and its return-field list compensates for the missing output schema. Only pagination/result-size behavior is left unstated.

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

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

Schema description coverage is 100% and the email_id property already documents the digits-only pattern and that it comes from the list tools. The description adds nothing about the parameter, 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: retrieves who unsubscribed for a given email, and enumerates the returned fields (contact, email address, time, reason, count per reason). The metric-specific naming places it cleanly alongside the parallel siblings get_email_bounces/opens/clicks, though it never names those siblings explicitly.

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

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

There is no when-to-use statement, no exclusion, and no named alternative such as benchmark_get_email_report, which is the closest sibling and the obvious competing choice for email-level reporting. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the HTTP endpoint and enumerates return fields (name, description, active contact count, custom field names), useful context, but says nothing about errors 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?

One short, front-loaded sentence plus the endpoint reference; nothing is padded. The telegraphic fragment style is efficient, though slightly compressed at the cost of readability.

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 fields, which is the key missing structured data. A single-required-param read tool is otherwise fully covered by annotations and schema.

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

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

Schema coverage is 100% and the single list_id parameter is fully documented in the schema, including its digit pattern and provenance. The description adds no format or semantics beyond what the schema already states, 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 (one contact list) plus the exact fields returned, so an agent knows exactly what it fetches. "One contact list" implicitly contrasts with benchmark_list_lists, but the sibling is never named, leaving differentiation to inference.

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: needing one list by id selects this over benchmark_list_lists, and benchmark_get_list_fields is the sibling for field metadata. No explicit when-to-use or when-not-to-use statement is given.

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

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

The read-only annotations already cover the safety profile, so the bar is lower. The description adds useful detail about what is returned (column names including custom fields), but does not discuss authentication, rate limits, or other operational 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?

Two short sentences with no filler; the most important information (what the tool returns) is front-loaded. The endpoint path is slightly redundant but still compact and useful for mapping.

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 metadata tool with full parameter coverage and no output schema, the description adequately explains the return shape. It lacks usage context against siblings, but no critical information for invocation is missing.

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

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

With one parameter and 100% schema description coverage, the schema already explains list_id as a digits-only contact list id. The description mentions the contact list context and shows the endpoint path, but adds no semantics beyond the schema.

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

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

The description states the resource and returned data ('column names of a contact list') and gives concrete examples plus the HTTP endpoint. It is clear enough to distinguish from siblings like list_contacts or get_list, though it uses a noun phrase rather than an explicit verb.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as benchmark_get_list or benchmark_list_contacts. The purpose is implied by the resource name, but no conditions, prerequisites, or exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that the payload is usage/plan data with percentage metrics, but discloses nothing further about auth requirements, rate limits, or freshness of the usage numbers.

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 naming the resource and its returned fields, followed by the raw endpoint. No filler or redundancy.

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

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

For a zero-parameter, read-only tool with no output schema, the description covers what the agent gets back (plan, add-ons, contact usage) and how it is fetched. Only minor gaps remain, such as whether account context is implicit from credentials.

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

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

The tool takes zero parameters, which is the baseline-4 case; the schema is empty and fully covered. Nothing in the description is needed to compensate for a parameter gap.

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

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

Namespace (email plan, add-ons, contact usage) is a specific resource, and the parenthetical enumerates exactly what is returned (active/account/total contacts, percent used), plus the underlying endpoint. It is clear on its own, though it never explicitly contrasts itself with neighbors like benchmark_get_account or benchmark_get_settings that an agent might confuse it with.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools for related account information. The only implicit cue is that it is a read endpoint (GET /Client/Plan).

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond the annotations: the API token is stripped from the reply, which tells the agent not to expect a full credential object.

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

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

Three short fragments, field list front-loaded, no padding. The trailing 'GET /Client/Setting' is endpoint trivia that occupies space without helping tool selection, keeping this just short of a 5.

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

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

With no output schema, the description correctly carries the burden of enumerating return fields and adds the token-removal caveat, so an agent knows what it will receive. The one gap is the unaddressed overlap with benchmark_get_account.

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

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

The tool takes zero parameters, so the baseline is 4 under the rules; there is nothing for the description to compensate for. Schema coverage is 100% and the empty object schema is self-explanatory.

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

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

The description names the resource (account/sender settings) and enumerates the concrete fields returned (from name/email, signature, footer, time zone, language, company address), so an agent knows exactly what this retrieve returns. It does not, however, distinguish itself from the very similar sibling benchmark_get_account, which is the main remaining ambiguity.

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 the sibling benchmark_get_account is a plausible alternative that is never addressed. The only steer is implicit — the field list implies reading default sender configuration — which leaves the agent to infer the boundary itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the HTTP endpoint and the shape of the returned object; it discloses nothing about auth, rate limits, or failure modes. 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?

Two short fragments, zero padding, front-loaded with the resource before the endpoint. Efficient, though the endpoint restatement adds little for an agent that already sees the 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?

For a single-record read with annotations covering the safety profile and a fully documented schema, the description is sufficient. Since there is no output schema, the phrase 'with its settings and target lists' usefully previews the return shape.

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 form_id parameter is fully documented in the schema (digits-only pattern). The description 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+resource ('get' a single signup form) and enumerates the payload ('its settings and target lists'), which distinguishes it from the sibling benchmark_list_signup_forms. It never names that sibling explicitly, so it stops short of a 5.

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

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

Usage is only implied: 'One signup form' signals singular retrieval versus the list sibling, and the GET path confirms a single-record fetch. There is no explicit when-to-use/when-not guidance or alternative routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the REST endpoint and the fact that the result is a public (externally resolvable) link, which is modest added context but no return format or auth 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?

Two short fragments, front-loaded with the resource. The endpoint line is mildly redundant with the name but harmless; nothing is padded.

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

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

A one-parameter read tool with full schema coverage, clear annotations, and no output schema — the description needs to say little, and what an agent needs to call it is present. Lacking only explicit alternative-routing guidance.

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

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

Schema coverage is 100% and the single form_id parameter is fully documented (digits only, as returned by list tools). The description 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 the resource and the specific output ('public link of a signup form'), which distinguishes it from the sibling benchmark_get_signup_form (form details). It is phrased as a noun fragment rather than a verb, but the intent is unambiguous.

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

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

No guidance on when to use this instead of benchmark_get_signup_form, benchmark_list_signup_forms, or other form tools. The agent must infer the selection condition from the title alone.

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

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

Annotations already cover readOnlyHint, destructiveHint, and openWorldHint, so safety is handled. The description adds field-level content (email, name, dates, id) and the underlying endpoint, which is mild extra context but discloses nothing about pagination behavior or result limits.

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

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

Two tight sentences with no filler, front-loading the primary action and then the filter/search options. The trailing raw endpoint is slightly superfluous but harmless.

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

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

A read-only, paginated list tool with no output schema. Safety and parameters are adequately covered by annotations and schema, but the description says nothing about return shape, pagination via next_page, or how it differs from the near-identical search sibling.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, including enum values and defaults. The description repeats status values and adds 'search a column' but contributes no syntax or meaning beyond the schema. 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 clear verb and resource: lists contacts of a specific list, with named return fields. It does not differentiate itself from the close sibling benchmark_search_contacts, which likely overlaps on the search capability.

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?

Mentions filtering and searching but gives no explicit when-to-use guidance or contrast with benchmark_search_contacts. Usage is implied by the single-list scoping requirement rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results are aggregated per campaign across six metrics, which is useful context, but says nothing about pagination behavior, result freshness, or typical result size.

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

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

Two short sentences, front-loaded with the resource and its returned fields. The trailing 'GET /Emails/Report' is API trivia that adds little for an agent, but the overall text is tight and waste-free.

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 carries the burden of indicating what comes back — and it does list the six metric families per campaign. Pagination and sort parameters are handled by the schema, leaving no critical gap for a read-only listing tool.

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

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

Schema description coverage is 100% — page, page_size, search, and sort_order are all documented in the schema, including the next_page chaining hint. The description adds no parameter meaning beyond that, 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?

Clear verb (report/list summaries) plus resource (sent email reports) and an explicit enumeration of the metrics returned per campaign (sends, opens, clicks, bounces, unsubscribes, complaints). It is distinguishable from the single-metric siblings (get_email_opens, get_email_clicks) by being an aggregate summary, but it never explicitly distinguishes itself from benchmark_get_email_report or benchmark_list_emails.

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

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

No when-to-use, prerequisites, or alternatives are given. With siblings like benchmark_get_email_report and the per-metric tools (get_email_opens, get_email_clicks, get_email_bounces), the agent is left to infer which to call to get campaign vs. per-recipient data.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about pagination behavior or rate limits beyond what the schema's page/next_page wording implies.

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

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

Two tight sentences, front-loading what is listed and the fields returned, with no filler. Every clause earns its place.

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

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

With no output schema, enumerating the returned fields is genuinely useful and largely sufficient for a filtered list tool whose parameters are fully documented. Only marginal gaps remain around result ordering defaults and pagination limits.

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

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

Schema description coverage is 100%, so all six parameters (page, search, status, order_by, page_size, sort_order) are fully documented in the schema. The description adds no parameter-level semantics beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('List email campaigns') and enumerates the returned fields (id, name, subject, type, status, dates, target lists), which distinguishes it from retrieval siblings like get_email. It does not explicitly contrast with list_email_reports, but the resource is unambiguous.

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

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

No guidance on when to use this tool versus alternatives such as get_email for a single campaign or list_email_reports for reporting data. The GET endpoint is noted but that is an implementation detail, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the raw endpoint (GET /Contact/) and the returned field set, but says nothing about pagination behavior or result limits beyond what the schema already conveys via page/next_page.

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

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

Two short sentences, front-loaded with the action and the payload, with no redundant filler. The trailing "GET /Contact/" is slightly low-value for an agent but does not bloat the definition.

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 five optional params, no output schema, and no required inputs, the description usefully compensates for the missing output schema by naming the returned fields. Nothing critical for a correct invocation is missing, though pagination handling could be noted.

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 page, search, order_by, page_size, and sort_order are all already documented in the schema. The description adds no parameter-level meaning; 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 contact lists") and enumerates the returned fields (id, name, description, contact count, dates), so the agent knows exactly what it gets. It does not explicitly differentiate itself from the sibling benchmark_get_list, but the plural/listing framing makes the distinction reasonably inferable.

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?

"Use the ids with the contact tools" is follow-up guidance rather than when-to-use guidance. There is no explicit statement of when to choose this over benchmark_get_list, benchmark_list_segments, or benchmark_search_contacts, leaving the agent to infer the listing intent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds that results are the saved segments with id and name (a light statement of return fields) plus the underlying REST endpoint GET /Contact/Segments. It does not disclose pagination behavior, which is the one behavior an agent would actually benefit from here.

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

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

Two short sentences, no waste, purpose front-loaded. The trailing endpoint reference is compact and informative.

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?

Low-complexity read tool with annotations covering safety and full schema coverage for the two params, so the core is adequate. Missing only pagination behavior in prose, which the schema partially covers, and no output schema exists to explain the return shape beyond 'id and name'. Acceptable but with a clear gap.

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

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

Schema description coverage is 100% and both page parameters are fully documented in the schema (defaults, ranges, next_page chaining). The description adds nothing about parameters, 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?

Clear verb+resource ('List the saved segments') with a helpful gloss defining what a segment is ('filtered subsets of lists') and stating the returned fields (id and name). It doesn't differentiate from the family of sibling list_* tools like list_contacts or list_lists, but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives despite a cluster of sibling list_* tools. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint path and the shape of returned fields; it says nothing about pagination limits or result volume beyond what the schema's page/page_size text already conveys. A 3 is appropriate given annotations carry the behavioral load.

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 no filler, leading with the resource and fields before the endpoint. Every clause earns its place.

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

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

There is no output schema, but the description compensates by listing the returned fields, and pagination is covered by the schema's next_page hint. For a simple read-only list tool this is nearly complete; only sort/search interaction nuance 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?

Schema description coverage is 100% and every parameter (page, search, order_by, page_size, sort_order) is documented in-schema, so the baseline is 3. The description adds no parameter semantics of its own.

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 signup forms') and even enumerates the returned fields (id, name, date, lists they feed), which cleanly separates it from the singular sibling get_signup_form. It does not, however, explicitly name or contrast any sibling, so it falls short of a 5.

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

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

The 'List' verb and the GET /SignupForm/ endpoint imply a read/scoping use case, but the description never states when to prefer this over get_signup_form or list_lists, and offers no exclusions or prerequisites. Usage is only inferable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new context: the result is one row per list with specific fields, which matters because there is no output schema. It does not mention rate limits or pagination, so not a 5.

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

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

Two compact sentences, front-loaded with the purpose and result shape before the raw endpoint path. Little waste, though the trailing 'GET /Contact/ContactDetails' is of marginal value to an agent.

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

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

For a one-parameter read search, the description covers purpose, scope (all lists), and return shape, which is required since there is no output schema. The only real gap is whether the email must match exactly, which affects 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?

Single parameter with 100% schema coverage, so the schema already documents 'email' fully. The description adds no matching rules (exact match, case sensitivity, normalization) beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb (Find) and resource (an email address across all lists), plus the row-level output shape (list name, contact id, master-unsubscribe flag). This is enough to tell it apart from benchmark_get_contact and benchmark_list_contacts, though it never names a sibling explicitly.

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

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

Usage is implied by 'Find an email address across all lists' – it's the lookup-by-email tool – but there is no explicit when-to-use versus benchmark_get_contact or benchmark_list_contacts, and no note on match semantics (exact vs. partial).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces this with 'no undo for this' and the irreversible master-unsubscribe scope — critical context beyond the flags, especially the permanence and the master-list effect.

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

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

Three short clauses, front-loaded with WRITE label and the destructive consequence, then the endpoint. Every sentence earns its place.

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

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

For a 2-param write tool with no output schema, the description fully conveys the irreversible effect and the endpoint. It's essentially complete; only the alternative-tool routing could be tightened.

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 parameters (list_id, contact_id) are fully documented with patterns and provenance hints. Description references the endpoint path shape, adding minor reinforcement but nothing 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+resource (move a contact to the Do Not Contact list) with precise scope ('master unsubscribe'), which clearly distinguishes it from siblings like benchmark_update_contact and benchmark_add_contact.

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

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

Context clarifies when this applies — preventing any future campaign from reaching the contact. However, it doesn't explicitly compare against the sibling benchmark_update_contact (which might also set contact status), so the alternative selection isn't spelled out.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value with 'Only the fields you pass are sent,' clarifying partial-update semantics, but the leading 'WRITE:' label largely restates readOnlyHint=false and nothing is said about permissions or what happens to fields omitted from the request.

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

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

Three short sentences with zero filler; the write semantics and scope lead, followed by the partial-update rule and the endpoint. Every sentence carries information the 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 7 parameters, a nested object, and rich annotations, the description supplies the two things the schema cannot: write semantics and partial-update behavior. The only gap is that no output schema exists and the description says nothing about what the call returns or how failures surface, which is a minor omission for a PATCH tool.

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

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

Schema description coverage is 100%; every parameter including the nested custom_fields slot mapping is documented in the schema itself. The description adds no per-parameter meaning beyond that, 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 ('change fields of one contact in one list') plus the exact endpoint, so it is distinguishable from benchmark_add_contact by the change-vs-create verb. It stops short of explicitly naming or contrasting a sibling, which keeps it at 4 rather than 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?

Implicit use case (modify an existing contact) is inferable, but there is no explicit when-to-use guidance, no statement of when to prefer it over benchmark_add_contact or benchmark_unsubscribe_contact, and no prerequisites. Nothing routes the agent among alternatives.

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