iContact MCP by usefulapi

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the description's real contribution is the concrete consequence: a duplicate email is reported by iContact as a warning rather than a failure. It also names the underlying endpoint POST /contacts, which helps an agent reason about behavior. It does not say whether the warning still creates a duplicate record, which is the one ambiguity that matters most.

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: the WRITE marker leads, the list caveat follows, and the idempotency note plus endpoint close it out. Nothing is redundant and the highest-risk information 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 14-parameter mutation with no output schema, the description covers purpose, list scoping, and duplicate behavior but omits the parameter surface entirely and says nothing about what comes back. Since a caller almost certainly needs the new contact's ID to subsequently call icontact_set_subscription, that return-value gap is meaningful despite the otherwise solid framing.

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

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

The description mentions no parameters at all, while schema description coverage is only 29% — the 13 non-required fields (fax, street, status, business, name parts, etc.) are essentially undocumented anywhere, and even the required email is only implied. Given the schema does little of the work here, the description should have compensated and does not.

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

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

States a specific verb and resource ('add one contact to the account') and immediately narrows scope by noting it does not attach the contact to a list, naming the sibling that does. An agent can distinguish it from icontact_update_contact and icontact_set_subscription without opening any schema.

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

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

Explicitly routes list-assignment to icontact_set_subscription and warns that duplicates surface as warnings rather than errors. It stops short of full routing guidance, though — it never says to use icontact_update_contact when the email already exists, which is the natural next question given the duplicate behavior it describes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the exact backing endpoints (GET /a/ and GET /a/{accountId}/c/) and the fact that results are scoped to the caller's credentials and include the server's active folder.

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 with the payload description front-loaded ahead of the endpoint reference. The raw endpoint list is slightly cryptic but earns its place by telling the agent the response spans two API calls.

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

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

For a zero-parameter read tool with full annotation coverage and no output schema, the description supplies enough: what entity is returned, which fields, and the folder scoping. Only pagination/error behavior is unaddressed, which is minor here.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no inputs are needed since the account is derived from the credentials.

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 (the iContact account belonging to the credentials) and enumerates the returned fields (company name, address, plan) plus client folders, so the agent knows exactly what it retrieves. It doesn't explicitly contrast itself with siblings, though no sibling is account-scoped, so the distinction 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?

There is no explicit when-to-use statement or named alternative. The phrase 'with the folder this server uses' implies a discovery use case (call this to learn account/folder context), but the agent must infer that calling it first is the intended pattern.

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 REST path, saying nothing about behavior on a missing/invalid id or any auth/rate-limit constraints.

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

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

Two short fragments with zero padding and the resource identity front-loaded. It is slightly telegraphic rather than a complete sentence, but every token 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 simple single-parameter read with annotations and no output schema, this is close to adequate. It omits what a caller should expect when the id doesn't exist and what the response contains, which are the remaining gaps.

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

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

Only one parameter, and schema description coverage is 100%, so the schema carries full semantics and the 0-parameter baseline of 4 applies. The description adds nothing beyond "by id," but nothing is needed.

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

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

"One campaign by id" names a specific resource and retrieval scope, and the endpoint GET /campaigns/{campaignId} confirms the verb is a single-resource read. It implicitly contrasts with the sibling icontact_list_campaigns, though it never names it.

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

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

No when-to-use guidance, no exclusions, and no mention of the list_campaigns sibling. The only hint is "by id," which merely restates what the required parameter already tells the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds only the raw endpoint mapping, not meaningful behavioral context such as not-found handling, rate limits, or response shape.

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

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

The definition is extremely short and front-loaded. The endpoint reference is somewhat redundant with the tool name, but it is not harmful and the description contains no filler.

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

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

For a simple one-parameter read tool with full schema coverage and safety annotations, the description is adequate. It does not explain return values, but no output schema exists and the operation is straightforward.

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 sole parameter is well described in the schema, including a pointer to icontact_list_contacts. The description itself adds no parameter detail, so 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 states a specific resource and access mode: retrieving one contact by id. It distinguishes the tool from list-style siblings such as icontact_list_contacts, though it does not spell out the contrast explicitly.

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

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

Usage is only implied by 'by id'; there is no explicit when-to-use guidance, no mention of prerequisites, and no reference to alternatives like icontact_list_contacts for finding an id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the bare API route and says nothing about error behavior for an unknown id, pagination, or what a returned list contains — no value beyond structured fields.

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

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

Two terse fragments, front-loaded with the resource identification and then the route. Nothing is wasted, though the extreme terseness sits close to under-specification rather than optimal concision.

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 trivial one-parameter read with full schema coverage and clear read-only annotations, the description is minimally sufficient. However, with no output schema present, the description should say something about the returned list object and error case for a missing id, and it does not.

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

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

There is a single parameter with 100% schema description coverage ('iContact list id.'), so the schema carries the semantics. The description's 'by id' merely restates the required list_id without adding format, range, or sourcing guidance; 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-and-scope: a single mailing list fetched by id, plus the underlying endpoint GET /lists/{listId}. The singular framing implicitly contrasts with the sibling icontact_list_lists, though it never names that alternative 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?

No statement of when to use this versus icontact_list_lists or other get_* siblings, and no prerequisites (e.g. needing a known list id first). Usage is left entirely to inference from the name and the 'by id' phrasing.

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 value the annotations don't: it names the payload contents (subject, HTML and text bodies), which matters because there is no output schema, and it maps the call to GET /messages/{messageId}.

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

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

Two sentences, zero filler. The return content is front-loaded ahead of the endpoint mapping, so the agent gets the useful information first.

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

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

For a one-parameter read tool with full annotation coverage and full schema coverage, this is nearly complete: it says what it returns and how it maps to the API. Only edge behavior such as not-found handling is unaddressed, which is minor here.

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

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

Schema coverage is 100% with a single documented integer message_id, so the schema carries parameter meaning. The description only reinforces that lookup is by id and supplies the path template; it adds no format or validation detail beyond the schema.

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

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

States a specific verb and resource ('One message by id') plus the fields returned, which distinguishes it from list_messages and get_message_statistics. It stops short of naming those siblings explicitly, but the singular-by-id framing makes the distinction clear.

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

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

Usage is only implied: the phrase 'One message by id' suggests fetching a known message rather than browsing, but the description never says when to use this versus icontact_list_messages or icontact_get_message_statistics, and states no prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety and access profile are clear. The description adds the HTTP endpoint and the list of metrics, which is useful return-value context, but does not add deeper behavioral details like auth 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 sentences, front-loaded with the purpose and metric list, with zero wasted wording. The endpoint is useful supporting detail rather than 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 read-only statistics tool with no output schema, the description adequately explains what data is returned by listing the metric categories. It could be richer about the response shape, but annotations cover the safety profile and the schema covers the only parameter.

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

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

Schema description coverage is 100% for the single message_id parameter, so the schema already provides adequate semantics. The description reinforces that messageId is used in the path but does not add meaning beyond the schema.

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

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

The description clearly identifies the resource (a message's delivery statistics) and enumerates the specific metrics returned. It distinguishes itself from general message retrieval by focusing on statistics, though it does not explicitly name sibling alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as icontact_get_message or icontact_list_message_activity. The implied use is obvious from the name, but the description offers no explicit context or 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds nothing beyond restating the endpoint: no mention of what a segment contains, whether a missing id errors, or auth/scope requirements. There is no output schema, so this silence leaves the return shape entirely undocumented.

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, purpose front-loaded, zero filler. The raw endpoint restatement is mildly redundant but cheap and gives useful orientation for an agent familiar with the API.

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 retrieval tool with no output schema and no annotations describing results, the description should say at least what fields a segment record includes or how to source a valid segment_id. As written it leaves both questions unanswered.

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 (segment_id) and schema description coverage is 100%, so the schema already documents its type and positivity constraint. The description adds no extra meaning such as where an id can be obtained. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb+resource: fetch a single segment by id, and gives the underlying endpoint for orientation. It implicitly distinguishes itself from icontact_list_segments (singular vs. plural), though the differentiation is left to inference 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?

"One segment by id" implies this is the lookup-by-id path versus the list path, but the description never names icontact_list_segments as the alternative or says when to use which. Usage is implied, not guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description only adds the underlying REST path (GET /sends/{sendId}), which is minor context; it says nothing about not-found behavior or the response shape.

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

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

Two short fragments with no wasted words, and the resource/scope is front-loaded. It is terse to the point of terseness rather than being verbose, so no penalty for padding.

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

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

For a simple one-parameter read with full annotation coverage and no output schema, an agent has everything needed to invoke it correctly. The only omission is what the returned send object looks like and error behavior.

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

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

Schema coverage is 100% and the single send_id parameter is documented in the schema itself. The description contributes no additional meaning about the id (format, origin, valid range) beyond what the schema provides, so baseline 3 applies.

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

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

States a specific resource (a send) and scope (by id), which lets an agent distinguish it from icontact_list_sends without opening the schema. However, it relies on the tool name for the verb and never names the sibling it contrasts 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?

No guidance on when to use this versus icontact_list_sends or the other get_* siblings. The single-vs-list distinction is only implied by the word 'One' and must be inferred by the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds the endpoint (GET /campaigns) and the domain meaning of a campaign, but says nothing about pagination behavior, ordering defaults, or the shape of the result list — context that would matter for a list endpoint.

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

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

Two short sentences, front-loaded with the action and resource; nothing is padded. The trailing 'GET /campaigns' is mildly redundant implementation detail but is small and does orient the agent to the REST semantics.

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 list tool with full schema coverage and annotations, the core is present. However, with no output schema the description omits any indication of what a campaign record contains or how the page cursor is used, leaving the agent to infer 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 coverage is 100%: limit, offset, and order_by each carry descriptions including the next_offset pagination hint. The description adds no parameter detail at all, so the baseline 3 for full schema coverage applies.

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

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

States a specific verb+resource ('List campaigns') and adds a parenthetical defining what a campaign is (sender identity and settings that messages belong to), which separates it conceptually from list_messages/list_sends. It stops short of naming those siblings explicitly, so differentiation is only implied.

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 alternatives such as icontact_get_campaign (single) or icontact_list_messages (related resource). The only cue is the verb 'List', which the agent must interpret on its own.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the HTTP endpoint and the shape of returned fields, but says nothing about pagination behavior, result caps, or empty-result handling beyond what the schema states.

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: the first front-loads what the tool returns, the second covers filtering, with the endpoint as a trailing tag. Nothing is redundant or buried.

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

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

For an 8-parameter read-only list tool with full schema coverage and annotations, the description supplies the essential missing pieces: what fields come back and which filters exist. Only the pagination workflow (limit/offset/next_offset) is left entirely to the schema, which is acceptable but slightly incomplete.

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

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

Schema description coverage is 100%, so every parameter is already documented, including limit/offset semantics and the status enum. The description only restates filter dimensions and adds the nuance of 'exact email', which is marginal added value over the schema.

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

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

States a specific verb and resource ('List contacts') and enumerates the returned fields and the filterable dimensions, plus the underlying endpoint GET /contacts. It is clearly distinguishable from icontact_get_contact, though it never names 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?

The filter sentence implies usage scenarios (by status, exact email, name, list membership), but there is no explicit when-to-use/when-not guidance or routing to alternatives such as icontact_get_contact for single-record lookup. Usage is inferable 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 the underlying endpoint (GET /customfields) and the shape of returned fields, but says nothing about account scoping, empty results, or rate limits.

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

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

Two short clauses with the purpose front-loaded and zero redundancy. Nothing here can be trimmed without losing information.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage and no output schema, the description is nearly sufficient; mentioning the returned fields compensates for the absent output schema. Minor gap: no indication of result volume or that the list is small/stable.

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% — limit and offset are fully documented including the next_offset paging pattern. The description adds no parameter meaning 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 ('List the account's custom contact fields') and parenthetically names the returned attributes (name, type). The resource is unambiguous against siblings such as icontact_list_contacts or icontact_list_segments, though it does not explicitly contrast itself with them.

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

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

No guidance on when to use this versus alternatives, no prerequisites (e.g. auth), and no note that the field IDs returned are what other tools consume. 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 clear. The description adds useful context by naming returned fields and the GET endpoint, but it does not mention pagination behavior, rate limits, or authorization requirements beyond what the schema already covers.

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 plus the endpoint, with no redundant or filler text. Every element earns its place for a simple list operation.

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

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

For a low-complexity list tool with full schema coverage and clear annotations, the description is largely complete. It names the returned fields even though there is no output schema. It could say slightly more about pagination or response shape, but 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 description coverage is 100%, so limit, offset, and order_by are already fully documented in the schema. The description adds no parameter-specific detail, which is acceptable given the high coverage 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 gives a specific verb and resource: list the account's mailing lists. It also names the fields returned and the endpoint, making the purpose unambiguous. It does not explicitly differentiate itself from the sibling get_list, though the list-vs-get distinction is clear from the name.

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 states what the tool does but provides no guidance on when to use it instead of get_list, list_segments, or other sibling tools. Usage is only implied by the verb 'list', with no alternatives or exclusions called out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results are a single page of events and maps to four REST endpoints, which is useful context, but it does not mention rate limits or what an event record contains.

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

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

Two sentences, zero filler. The subject ('Who opened, clicked...') and the scoping constraint ('one page ... for one message') are front-loaded before the endpoint list.

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

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

With no output schema, the description correctly signals that the return is a paginated page of event records, and the schema supplies the offset/next_offset paging contract. Minor gap: nothing about ordering or event record fields, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters including the kind enum, limit, offset and message_id are documented in the schema. The description restates the four kind values but adds no format or syntax detail beyond that, 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?

Specific verb plus resource ('Who opened, clicked, bounced from or unsubscribed after a message') and it enumerates the four event kinds, which separates event-level listing from the aggregate sibling icontact_get_message_statistics without naming it. Slightly short of 5 because the contrast with that sibling is left implicit.

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

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

'one page of events for one message' implies the use case (drilling into a single message's recipients) but never states when to choose this over icontact_get_message_statistics or icontact_list_sends. Usage must be inferred from the enumerated event kinds.

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 the returned payload shape, but says nothing about pagination behavior, result caps, or auth/scope requirements — modest added value beyond the annotations.

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

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

Three short, front-loaded fragments with zero filler: purpose, return fields, filters, and endpoint. Nothing redundant and nothing buried.

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

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

For a zero-required-parameter list tool with full schema coverage and a safety-carrying annotation set, the description covers purpose, filters and returned fields adequately. Since there is no output schema, marginally more detail on the response envelope (e.g. next_offset) would fully close the gap.

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

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

Schema description coverage is 100%, so limit/offset/order_by/campaign_id/message_type are all documented in the schema itself. The description only gestures at type and campaign filtering and adds no format or interaction detail 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?

Specific verb+resource ('List messages') with the returned fields enumerated (subject, type, campaign, create date, bodies) and the underlying endpoint (GET /messages). It does not explicitly distinguish itself from the sibling icontact_get_message, but the list/get contrast is strongly implied.

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?

'Filter by type or campaign' tells the agent the two narrowing dimensions, which is useful usage context. It never says when to prefer this over icontact_get_message or icontact_list_message_activity, so routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds the endpoint mapping (GET /segments) and the segment concept, but says nothing about return shape, ordering, or rate limits.

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

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

Two short sentences, with the resource definition front-loaded where it helps most. The trailing 'GET /segments.' is cheap but offers little to an agent that already knows the tool name.

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

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

For a simple, annotation-covered, zero-required-parameter list tool with fully documented parameters and no output schema, the description supplies enough to call it correctly. Only the lack of guidance on paging through results vs. using related endpoints is a real 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?

With 100% schema description coverage, both limit and offset are already documented in the schema, including the useful 'pass the previous reply's next_offset' 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?

States a specific verb and resource ('List saved segments') and adds a parenthetical that defines what a segment actually is (rule-based groups of contacts), which an agent cannot infer from the name alone. It does not explicitly contrast with the singular sibling icontact_get_segment, 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 statement of when to use this versus icontact_get_segment or other list endpoints, and no mention of prerequisites or pagination workflow. Usage is only implied by the verb 'List'; the agent must infer the rest.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and the meaning/fields of a send, but does not disclose auth requirements, rate limits, or pagination behavior beyond what the schema provides.

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

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

The definition is a compact single sentence plus endpoint, front-loading the core action and clarifying the resource in parentheses. There is no wasted text.

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

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

For a simple read-only list tool with rich annotations and full schema descriptions, the description is largely complete. It helpfully defines what a send contains, though it does not mention return pagination details such as next_offset, which are only implied by the offset parameter description.

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 limit, offset, and order_by fully documented in the input schema. The description adds no parameter-specific meaning beyond the schema, so the baseline of 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 gives a clear verb and resource ('List sends') and defines what a send represents, including key fields. It does not explicitly distinguish this from sibling tools such as get_send or list_messages, relying on the list/get naming convention instead.

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 states the endpoint but gives no guidance on when to use this tool versus alternatives like get_send, list_messages, or list_message_activity. Usage is only implied by the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /subscriptions), but says nothing about pagination behavior, defaults, or result ordering, which is the kind of context annotations cannot supply.

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 terse sentences, front-loaded with the resource and its fields, then filters, then endpoint. No filler; the parenthetical field list is dense but each element 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?

No output schema exists, and the description compensates by naming the returned fields (subscriptionId, contactId, listId, status) and the filterable dimensions. Pagination is left entirely to the schema, which is acceptable given its 100% coverage, so only minor gaps remain.

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

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

Schema description coverage is 100%, so all five parameters including limit/offset are fully documented in the schema. The description only echoes the three filter dimensions (list, contact, status) and adds no syntax or semantic detail beyond that, so it sits at the baseline.

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

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

States a specific verb ('List') and resource ('list memberships / subscriptions') and enumerates the returned fields, which separates it from sibling list tools like icontact_list_lists and icontact_list_contacts. It stops short of explicitly naming the mutation counterpart icontact_set_subscription, so 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?

'Filter by list, contact or status' tells the agent how to narrow results but gives no guidance on when to prefer this over sibling lookups (e.g., icontact_get_list for list metadata) or when filtering is unnecessary. Usage is implied by the available filters rather than prescribed.

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, idempotentHint and openWorldHint, so safety framing is covered. The description adds value beyond them by explaining that 'pending' triggers a double opt-in confirmation flow and that the operation is gated on prior consent — real behavioral context an agent needs.

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

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

Two short sentences, front-loaded with the WRITE marker and the subscribe-vs-unsubscribe split, then the precondition, then the endpoint. No filler and nothing needing reordering.

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 still covers the mutation, both directions of the operation, the consent precondition and the status semantics. It could have said what happens when a contact is already subscribed (relying on the idempotent annotation instead) or what the response returns, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, making baseline 3 appropriate. The description adds a little ('pending to start double opt-in') over the schema's 'pending = awaiting confirmation', but says nothing about contact_id or list_id beyond what the schema states.

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

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

States a specific verb and resource — 'put a contact on a list' or 'unsubscribe it' — with the endpoint POST /subscriptions, plus a 'WRITE:' prefix that immediately signals mutation. The set-vs-list distinction is clear enough to separate it from sibling icontact_list_subscriptions without opening either schema.

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

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

'Only for contacts who agreed to receive mail' gives an explicit eligibility constraint/exclusion that guides when to call it. It does not name a sibling alternative or say what to do for contacts who have not consented, so it falls short of full routing guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description's real added value is the warning that setting status to donotcontact or deleted stops mail, plus the partial-update semantics. This is meaningful behavioral context beyond the annotations, though return shape and permission needs are not addressed.

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

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

Front-loaded with 'WRITE' and tight, no wasted sentences. The endpoint POST /contacts/{contactId} is mildly redundant but grounds the operation; overall efficient.

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

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

For a 15-parameter mutation tool with annotations covering safety and no output schema, the description covers the key gotcha (donotcontact/deleted suppression) and partial-send behavior. Minor gaps on return values and full parameter guidance remain but are acceptable given annotation coverage.

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 only 33% schema description coverage across 15 params, the description compensates partially by explaining partial-update behavior and the consequence of the status enum values. It does not add meaning for the other 10+ undocumented fields, but the schema does carry types and constraints.

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 (change fields of one contact) and clarifies it is a WRITE operation. Clearly distinguishable from icontact_create_contact and the get/list siblings.

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

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

The 'only the fields you pass are sent' note implies partial-update usage, but there is no explicit when-to-use-vs-alternatives guidance (e.g., when to use this vs create_contact or set_subscription). Usage is inferred rather than stated.

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