Vision6 MCP by usefulapi

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

Beyond the annotations, the description discloses that Vision6 returns no contact data (HTTP 204), that contacts need an email and/or mobile, and that automations may be triggered. These are meaningful behavioral details for a write operation.

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

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

The description is front-loaded with the write action, then gives the batch limit, required contact fields, return behavior, read-back alternative, and side effect. Every sentence carries useful 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?

The description covers the important return behavior and automation side effect, which are especially valuable with no output schema. It is still missing guidance on duplicate handling or partial batch failures, which would matter for this non-idempotent write.

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

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

Schema description coverage is only 33%, so the description must compensate. It adds the batch limit and the key email/mobile requirement, but it does not explain the top-level remove_unsubscribers behavior or duplicate/partial-failure handling.

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

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

The description states a specific verb and resource: add up to 200 contacts to a list in one request. It also distinguishes this batch operation from the one-by-one alternative and names the sibling used to read results back.

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

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

It explains that this is faster than adding one by one and points to vision6_list_contacts for reading contacts back. It does not explicitly say when to choose vision6_create_contact instead, but the batch-vs-single contrast is clear enough for an 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely non-obvious behavior: creating a contact may fire the list's 'contact created' automations and send notification emails, plus it states the return value. It stops short of noting permission requirements or duplicate-handling behavior beyond what the schema's remove_unsubscribers enum says.

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

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

Three tight sentences with the operation class front-loaded, then the precondition, then side effects and return value. Nothing is redundant with the annotations or schema.

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

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

For a 9-parameter write tool with a nested 'fields' object and no output schema, the description covers side effects, precondition, and return shape ('Returns the new contact'). A brief pointer to vision6_list_list_fields for field keys would close the remaining gap, though the fields schema already mentions it.

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 89%, so the baseline is 3, but the description adds a cross-parameter constraint not visible in the required list (only list_id is formally required yet an email and/or mobile matching a list field is effectively mandatory). That is real semantic value beyond the schema; the POST path also anchors the list_id parameter.

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 a list') and the 'one' explicitly contrasts with the bulk sibling vision6_add_contacts, while 'WRITE:' flags the operation class up front. An agent can distinguish this from add_contacts and update_contact without opening any schema.

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

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

Gives a clear precondition for use: the contact needs an email and/or mobile that matches a field configured on the list. It does not name the alternative (vision6_add_contacts for bulk inserts) or the vision6_list_list_fields prerequisite step explicitly, so routing is implied rather than 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only two behavioral facts beyond that: the list is created empty, and the created list object is returned. It says nothing about duplicate creation risk from retries, required permissions, or rate limits, so this is modest added value rather than rich disclosure.

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 fragments, each carrying distinct information: operation class first, creation semantics and scoping second, return value and endpoint last. No filler, and the most decision-relevant token ('WRITE:') 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 7-parameter write tool with no output schema, the description covers what the tool makes, where it goes, and that the new object is returned, while the schema documents most optional settings. The remaining gap is that the optional compliance/notification configuration surface is never characterized in prose, but nothing essential to a correct call 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 71% — the three notification address arrays, allow_send_to_duplicates and folder_id are documented in the schema, leaving mainly is_gdpr_compliant undocumented. The description adds no parameter-level detail beyond steering the agent to vision6_list_folders for folder_id, which is the correct baseline for mid-to-high coverage.

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

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

States a specific verb and resource ('create a new, empty contact list') plus its required container scope ('inside a list folder'), which is enough to distinguish it from vision6_list_lists, vision6_get_list and vision6_create_contact without opening a schema. The 'WRITE:' prefix makes the operation class immediately legible.

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

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

Provides a concrete prerequisite route: the agent must obtain folder_id, and is pointed to vision6_list_folders with type list to do so. However, it states no exclusions (e.g., that a folder must exist first, or that this creates no contacts) and does not contrast with alternatives beyond that single pointer.

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=false and idempotentHint=false, so the mutation profile is known. The description goes further by clarifying the side effect is storage-only (no send), which is the key behavioral fact for this tool, plus the builder limitation. It stops short of stating that repeated calls create duplicate messages (non-idempotent consequence), which would be the final piece.

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

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

Front-loaded with the 'WRITE:' signal and the store-not-send constraint, then the per-type body requirements, then the limitation, then the endpoint. Every clause carries information the agent needs; nothing is padding.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the operation's effect, the conditional field requirements, and the sending alternatives. Return-value details are not required since no output schema exists. The only minor gap is no note on duplicate creation on repeat invocation.

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

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

Schema coverage is 79%, but the description encodes cross-parameter conditional requirements the schema cannot express: 'Email needs email_type, subject and matching body fields (plain: content_text; html: content_html; plain-html: both; raw_html: content_html or content_html_raw)' and 'SMS needs content_sms'. That is real added meaning beyond per-field descriptions, though a couple of params (from_name, is_responsive, reply_to) rely on the schema alone.

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 ('save a new email or SMS message') and immediately bounds the scope with 'This only stores the message; it is NOT sent'. It distinguishes itself from vision6_send_transactional by name, so an agent can route correctly without opening another 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 covers when to use this tool (draft creation), when not to (sending a campaign), and names both alternatives — the Vision6 app and vision6_send_transactional. The 'drag-and-drop builder is not supported' exclusion is an unusually useful boundary that most definitions omit.

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, but the description adds the stronger "IRREVERSIBLE / permanently" framing plus the requirement that user consent precede confirm=true, which is behavior annotations cannot express. The confirm mechanics partially repeat the schema's own parameter description, keeping it just short of a 5.

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

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

Three short sentences, front-loaded with the "WRITE, IRREVERSIBLE" risk marker, then the safer alternative, then the consent gate. No filler and the most important warning comes 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 destructive three-parameter write with no output schema, the definition covers risk level, reversibility, the safer sibling alternative, the consent prerequisite, and the underlying endpoint. Nothing an agent needs to decide whether and how to call it 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 only 33% (only confirm is documented), but the description compensates by spelling out the call shape — DELETE /lists/{list_id}/contacts?id={contact_id} — which clarifies that contact_id is a query parameter while list_id is a path segment. It also ties confirm=true to prior user agreement, adding intent semantics beyond the const constraint.

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 ("permanently delete one contact from a list"), states the scope (single contact), and names the sibling it is not — vision6_update_contact. An agent can distinguish it from all other contact tools without opening a schema.

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

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

It states the intended case (privacy erasure request), gives an explicit alternative when the goal is only to stop emailing (vision6_update_contact with email_subscribed=false), and sets a precondition for invocation (pass confirm=true only after the user agreed). That is when/when-not/alternatives in three sentences.

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 structurally. The description adds genuine value beyond that: it is scoped to the credential the server itself uses, lists the exact data returned, and identifies the diagnostic use case (permission failures). It stops short of saying whether the key's secret is ever exposed or whether the call itself requires auth.

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

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

Two sentences, front-loaded with the return payload, then the use case. Concrete scope examples communicate the kind of data better than an abstract phrase would, and 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?

With no parameters and no output schema, the description carries the full burden of explaining the response, and it does name the fields an agent will receive. Minor gaps remain (response shape, whether expiry can be null, whether the secret is masked), but an agent has enough to call and interpret it.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-argument tool applies. The description correctly signals the call takes no inputs by describing only the returned data.

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

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

States a specific resource (the API key this server uses) and enumerates exactly what is returned: granted scopes with concrete examples (list.view, contact.create, message.edit, report.view) plus creation/expiry time. The name 'get_account' is ambiguous, but the description resolves it and clearly distinguishes this credential-inspection tool from the sibling CRUD tools on lists, contacts and messages.

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 it to see why a request is refused" gives an explicit triggering scenario, which is more than most definitions offer. It does not name an alternative or state when not to call it, but given the sibling set is all resource-level CRUD, no obvious alternative exists to route away from.

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 structurally. The description adds the endpoint and list scoping, but its claim of 'all fields' is misleading given the optional fields filter in the schema, and there is no note on error behavior for unknown ids.

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 with no filler. The trailing endpoint restates schema structure somewhat redundantly, but it costs little.

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?

This is a simple read tool with annotations and a small schema, so the burden is low. With no output schema, though, the description carries the return-value explanation and does so inaccurately ('all fields' when filtering is possible), leaving a real gap for an agent shaping the response.

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 only 33% — list_id and contact_id are typed but undocumented there, so the description does add value by mapping them to the path template. However, 'with all fields' conflicts with the documented fields parameter, and no format or id-source detail is given.

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 contact by id within a list') plus the underlying endpoint, which makes the single-vs-many distinction against vision6_list_contacts inferable. It stops short of naming that sibling 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?

There is no explicit when-to-use/when-not-to-use guidance and no mention of where list_id and contact_id come from (e.g. vision6_list_contacts). The usage is strongly implied by 'by id within a list', but the agent must infer the lookup workflow.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the raw endpoint path, with nothing about authentication, what fields the list contains, or what happens when the id is unknown — minimal 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?

Two very short fragments with no padding, and the resource identification is front-loaded. The telegraphic style is efficient but borders on under-specification rather than tight writing.

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 should indicate what a returned contact list looks like, and it says nothing. For a simple one-parameter read tool this is a modest gap, but the description leaves the return shape and field contents entirely unknown.

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 0%, so the description must carry the burden for the single list_id parameter. It does so only weakly: 'by id' and the {list_id} path fragment confirm the parameter identifies the list, but no format, range, or source for obtaining a valid id is given.

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 scope: a single contact list fetched by id, backed by the endpoint GET /lists/{list_id}. The singular 'One contact list by id' implicitly distinguishes it from the sibling vision6_list_lists, though it never names that sibling or uses an explicit verb like 'retrieve'.

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 vision6_list_lists or vision6_list_list_fields, and no mention of prerequisites or error cases (e.g. invalid id). The agent must infer the choice from the singular phrasing 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 note that including content yields HTML and plain text; it says nothing about what is returned by default or error behavior for a missing 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?

Three short sentences, front-loaded with the core purpose and then the content flag. Nothing is padded, though the raw endpoint reference is marginally redundant for an agent that already has 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 two-parameter read with no output schema, the description omits the shape of the returned message object (fields beyond body_html/body_text) and any not-found behavior. Adequate but leaves the agent guessing about return structure.

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

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

Schema coverage is 50%: include_content is already fully documented in the schema, and message_id, while undocumented, is self-evident from its name and required status. The description restates the include_content effect (HTML plus plain-text body) but adds no format, size, or default-value 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?

The description states a single resource retrieval scoped by id and names the underlying endpoint (GET /messages/{message_id}), which distinguishes it from list_messages and get_message_sender_defaults. The verb is implicit ("One message by id") rather than explicit, 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?

Usage is only implied: the agent must already have a message_id to call it, and the mention of include_content=true hints at when to request bodies. No alternatives (e.g. list_messages for discovery, get_message_sender_defaults) or when-not conditions are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without prose. The description adds useful semantics about these being fallback values applied on omission, but says nothing about return shape, what happens if no defaults are configured, or authentication 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 short clauses and an endpoint reference, with the substantive content (which fields) front-loaded. Nothing is padded and nothing needed for correct invocation is stripped out.

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

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

For a parameterless read with no output schema, the description usefully enumerates the returned fields, which compensates for the absent output schema. Minor gap: it does not indicate behavior when defaults are unset or whether the response is a flat object.

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 schema baseline of 4 applies; there is no parameter meaning the description could clarify. The sentence does implicitly scope the result to the account level, which is consistent with the parameterless signature.

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

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

Names the specific resource and enumerates exactly which fields are returned (from name, from address, reply-to), plus the endpoint GET /message-sender-defaults, which makes the retrieval verb unambiguous. It distinguishes itself from the generic vision6_get_account by scope, though it never names that sibling explicitly.

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

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

The clause 'applied to new email messages when you omit them' implies the practical use case (fetch defaults before composing a message), but there is no explicit instruction on when to call this versus vision6_get_account or vision6_get_message. 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 real value by disclosing the report's contents (counts, per-link clicks, domain distribution) and the conditional nature of A/B and social sections, though it says nothing about auth requirements or behavior when a report_id does not exist.

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

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

Three compact clauses front-load the core purpose and then enumerate contents and optional sections; the endpoint is tacked on as a single useful token. 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?

With no output schema, the description carries the burden of describing return values, and it does so concretely: delivery and engagement counts, per-link click counts, recipient domain distribution, plus optional A/B and social stats. Minor gaps remain around error handling and the `fields` projection effect, but the essentials are present.

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 75%, so the two boolean flags and the `fields` projection are already documented in the schema. The description only restates that A/B and social statistics are optional inclusions and does not explain `fields` projection semantics or report_id format/preconditions, so it adds little beyond structured data.

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

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

States a specific verb and resource ('one send report by id') plus the payload it returns: delivery/engagement counts, per-link clicks, and recipient domain distribution. This clearly distinguishes it from vision6_list_reports, which enumerates reports rather than fetching a single one.

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 'by id' — you call it when you already have a report_id and want the detail view — but the description never says when to prefer vision6_list_reports or when to set the optional include flags. No exclusions or preconditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds genuine value beyond that by disclosing the payload contents (delivery statistics) and the underlying endpoint, but says nothing about error behavior or cost of the outbound call implied by openWorldHint.

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 outcome and backed by the endpoint mapping. Nothing is padded, though the raw REST path is of marginal value to an agent that cannot call URLs directly.

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

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

For a one-parameter read-only fetch with no output schema, the description is close to sufficient: it names the resource, the lookup key, and the non-obvious return content (delivery statistics). The remaining gap is that the shape of those statistics is unknown and there is no mention of not-found handling.

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

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

Schema coverage is 0% and the single required group_id has no schema description, so the description must carry the burden. 'By id' does confirm group_id is an identifier and that exactly one result is expected, but it does not restate the integer/positive constraint beyond the schema or explain where a group id is obtained (e.g. from list_transactional_groups).

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 and scope: a single transactional group retrieved by id, plus the payload it returns (delivery statistics). This implicitly distinguishes it from the sibling vision6_list_transactional_groups, which returns many. The verb is elided into a noun phrase ('One transactional group by id'), so the action is inferred rather than stated, but it remains unambiguous.

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

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

The phrase 'by id' implies this is the retrieval path when the caller already holds a group id, and the plural sibling makes the alternative inferrable, but the description never names vision6_list_transactional_groups or states when to prefer it. No prerequisites, no guidance on what happens with an invalid or unknown 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 safety is covered. The description usefully discloses what the response carries (status, double opt-in, custom fields) and the underlying GET endpoint, but says nothing about pagination bounds, rate limits, or result ordering.

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

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

Two dense sentences, front-loaded with the resource and the payload. The field enumeration is long but earns its place by telling the agent what comes back; the endpoint suffix is mildly redundant with the operation 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 10-parameter, nested-filter, read-only tool with no output schema, the description covers what is returned and how custom-field filtering works. Pagination (limit/offset/next_offset) is left entirely to the schema, which is a minor but real gap for a paged list operation.

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

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

Schema coverage is 80%, so most parameters are already documented in the schema. The description's filter examples ({"city":"Brisbane"}, {"source:ne":"promo"}) largely restate the schema's own filters description, adding only the point that custom fields are targetable and that arbitrary fields are filterable; no extra semantics for limit/offset/fields.

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 the contacts of one list') and enumerates the returned attributes, so it is clearly distinct from vision6_get_contact. It never names a sibling explicitly, so the boundary against vision6_list_sent_contacts or vision6_list_list_fields 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?

Usage is implied by the endpoint ('GET /lists/{list_id}/contacts') and the filter examples show how to narrow results, but there is no explicit when-to-use guidance or statement of when a different sibling (e.g. vision6_list_sent_contacts or vision6_get_contact) is the better call.

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 useful behavioral context: it is account-scoped and returns id, name, type, and size. It does not describe pagination behavior or total counts, but the schema covers limit/offset.

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

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

Three compact sentences with no filler; the purpose, returned fields, and downstream use case are front-loaded. Every sentence earns its place.

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

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

With no output schema, the description compensates by listing the returned fields and citing the endpoint. Pagination details live in the schema, so the definition is nearly complete. The only minor gap is that it does not state whether results are ordered or whether folders can be nested.

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 75%, so the schema already documents limit, offset, and type. The description adds meaning by clarifying that both 'list' and 'message' folder types exist, but it does not explain the 'name' filter or characterize pagination behavior. Baseline 3 is appropriate when the schema does most of 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?

The description states a specific verb and resource ('List the account's folders'), names the folder subtypes, and enumerates the returned fields (id, name, type, size). It also cites the underlying endpoint, making it unambiguous against creation-oriented siblings like vision6_create_list or vision6_create_message.

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

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

It explicitly says when the tool is needed: to obtain the folder id before creating a list or message. That is a clear usage context. It does not discuss alternatives or edge cases (e.g., when no folders exist), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value by describing the returned fields, the label-to-key naming convention, and the underlying GET endpoint. Pagination behavior is left to the schema rather than the description.

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

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

Three short sentences, front-loaded with the content of the response and followed by the key-format tip and endpoint. The endpoint line is mildly redundant with the tool name but not wasteful.

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

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

With no output schema, the description carries the burden of explaining return values and does so concretely (label, type, allowed values, mandatory). Only the pagination/response envelope isn't described, which is a minor gap for a simple read tool.

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

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

Schema coverage is 67%: limit and offset are well documented in the schema, while list_id has no schema description and is only illuminated by the 'GET /lists/{list_id}/fields' template. That is adequate but adds little beyond the structured fields, which fits the baseline for moderate coverage.

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

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

It states the resource precisely — the fields (columns) of a contact list — and enumerates what a field record contains (label, type, allowed values, mandatory), so an agent knows exactly what comes back. It doesn't explicitly contrast itself with siblings like vision6_list_lists, though the name and description make the distinction 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?

Usage is only implied: the note that the lowercase-underscore label is the key used for contact values and filters hints that this tool is a prerequisite for filtering or creating contacts. There is no explicit when-to-use, when-not, or named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value by disclosing the response shape (id, name, timestamps, notification settings), which matters because there is no output schema. It says nothing about auth requirements or result caps.

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

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

Two short sentences plus the endpoint, all front-loaded: resource first, returned fields second, filter third. Nothing is redundant or 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 three-parameter, non-destructive read with no output schema, the description covers what the tool does and what comes back, and pagination is handled in the schema. Only auth/permission expectations and any list-count limits are absent.

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

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

Schema description coverage is 100%, so name, limit and offset are already fully documented, including that offset should use the previous reply's next_offset. The description only echoes the exact-name filter, adding no syntax or behavior beyond the schema.

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

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

States a specific verb and resource ('List the account's contact lists') and enumerates the fields returned, plus the underlying endpoint GET /lists. It is clearly distinct from the singular vision6_get_list and from vision6_create_list, 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?

The only usage signal is 'Filter by exact name', which implies how to narrow results but not when to choose this over vision6_get_list or how to page through large accounts. There are no explicit when-to-use or when-not-to-use statements.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's added value is the return-field list and the explicit statement that name/subject filters are EXACT matches — a meaningful caveat that prevents an agent from assuming substring search. It stops short of saying whether drafts, archived or deleted messages are included, which 'saved' leaves ambiguous.

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

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

Two tight sentences plus a short endpoint tag, with the resource and returned fields front-loaded before the filter options. Nothing is padded and no sentence is wasted.

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

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

With no output schema, listing the returned fields (id, type, name, subject, sender) is exactly the compensation needed, and pagination is carried by the schema. Minor residual gap: no statement about default ordering or whether inactive/deleted messages appear in results.

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 80%, so name, limit and offset are already documented in the schema (offset even explains next_offset paging). The description only adds the 'exact' qualifier for name/subject and the type filter, the latter being the only enum in the schema and left undescribed there. 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?

Specific verb + resource: 'List saved email and SMS messages (templates and campaigns)' plus the fields returned and the filters available. The verb 'List' separates it from the sibling vision6_get_message or vision6_create_message, but the description never names those siblings to make the boundary explicit.

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

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

'Filter by type or exact name/subject' implies when the filters apply, but there is no explicit when-to-use vs when-not guidance and no routing to alternatives such as vision6_get_message for a single record or vision6_list_folders for organising them. Usage is inferable from the name, not 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, openWorldHint=true and destructiveHint=false, so safety is covered by structured data. The description adds real behavioral context beyond that: fixed newest-first ordering and, importantly, that click and domain breakdowns cost extra and only appear when named in `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?

Three dense sentences, front-loaded with the output shape and followed by filtering and endpoint. The metric enumeration is long but earns its place since there is no output schema; only slight trimming would improve it.

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 seven optional parameters and no output schema, the description compensates well by listing return fields and the fields-gated breakdowns. Pagination mechanics (limit/offset, next_offset) are left entirely to the schema, so it is strong but not fully self-contained.

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 71%, yet the description supplies meaning for nearly every filter: message→message_id, type→message_type, test sends→is_test, creation time→created_since. It also explains a non-obvious `fields` consequence (breakdown fields omitted unless requested), which the schema does not convey.

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

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

Specific verb+resource: lists send reports, states ordering (newest first) and enumerates the returned metrics, so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling vision6_get_report (single report), leaving that boundary 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?

The description says what can be filtered (message, type, test sends, creation time) which implies the retrieval use case, but it never states when to use this versus vision6_get_report or vision6_list_sent_contacts. No exclusions or prerequisites are given.

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

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 useful return-field context (send time, first/last open, open type enum), but says nothing about pagination behavior or volume limits beyond the schema.

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

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

Two tight sentences, front-loaded with what is returned, then the use case and raw endpoint. The endpoint path is arguably redundant but cheap and aids traceability.

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

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

A read-only paginated list tool with no output schema, so the description carries the burden of describing results and filtering. Results are sketched, but the four optional filters and pagination semantics are left entirely to the partially documented 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?

With 7 parameters and only 43% schema coverage, the description should compensate, but it explains none of the filters (list_id, contact_id, report_id) or that open_type is a filter. It only indirectly references open-type values through the return-field list.

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: contacts a single message was sent to, plus the fields returned (send time, open times, open type). That distinguishes it from vision6_list_contacts, though the description never names that sibling explicitly.

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

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

"Use it to see who opened a campaign" gives one positive use case, but there is no when-not guidance and no pointer to alternatives such as vision6_list_contacts or vision6_get_report for aggregate stats.

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 readOnly=true and destructive=false, so the safety profile is covered. The description adds genuinely new context by naming the exact response metrics (sent, failed, bounced, delivered, opened, clicked, unsubscribed) — valuable since no output schema exists. It stops short of describing pagination or ordering 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 compact fragments: the resource/return summary first, then the endpoint. Every clause carries information, and nothing needs to be read to the end to act.

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 enumeration of returned counts is the right compensating detail, and the schema fully carries the parameters. Only the relationship to the singular get tool and pagination guidance are 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%, so name, type, limit and offset are all documented in the schema, including the next_offset pagination hint. The description adds no parameter syntax or semantics beyond what is already structured, 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 the specific resource (transactional send groups) and enumerates the metrics each group carries, plus the underlying GET endpoint. It implicitly distinguishes itself from the singular vision6_get_transactional_group by describing a collection, though it never names that sibling explicitly.

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

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

Usage is only implied: the parenthetical ties group names to vision6_send_transactional, suggesting these are the groups you create sends under. There is no explicit statement of when to call this versus vision6_get_transactional_group, nor any exclusion or prerequisite.

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

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

Annotations already declare destructive/non-idempotent, but the description adds substantial context they cannot convey: credits are consumed, sends cannot be recalled, execution is asynchronous, unsubscribed addresses are skipped, and the account owner's email must be confirmed first. These are exactly the operational risks an agent needs before invoking.

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

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

Front-loads the critical destructive warning and keeps every clause factual with no filler, though it is a single dense paragraph — the confirmation rule and the mode selection would read better as distinct lines rather than buried mid-block.

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, irreversible tool with no output schema it covers prerequisites, limits, mode selection, and where results land. The gap is the return shape: it says results appear in the transactional group but never states what the call hands back (send IDs, per-recipient statuses), so an agent must infer success handling.

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 64% schema coverage the description earns its keep by explaining the recipient identity rule (exactly one of contact_id/email/mobile), the 100-recipient cap, positive wildcard syntax (%%key%%) tied to the data object, and the message_id-versus-custom-content exclusivity. Secondary fields such as from_name, reply_to, unsubscribe_type and group_id are left entirely to the schema.

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

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

Opens with an explicit verb and resource ('SENDS REAL EMAIL OR SMS') and immediately marks it as a write with immediate, irreversible effect. That distinguishes it cleanly from the message-creation siblings (vision6_create_message) and the read-side tools in the list.

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

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

It lays out the decision branches explicitly: saved message via message_id versus custom content, email requiring list_id, SMS requiring body_text plus from_address. It also states the confirm_send precondition ('only after the user approved these recipients and this content') and points to vision6_get_transactional_group for follow-up.

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=false; the description goes further by disclosing side effects ("May trigger 'contact updated' automations"), the irreversibility of double_opt_in (cannot be reset to false), and the return value. It also clarifies which values get overwritten, which is exactly the context a destructive, non-idempotent PATCH needs beyond the annotation flags.

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:", then capabilities, then semantics, then side effect and return value in four tight sentences with zero filler. Every sentence carries distinct information an agent needs.

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

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

For a 9-parameter mutation with a nested free-form fields object and no output schema, the description covers scope, partial-update behavior, side effects, irreversibility, and the return value. The remaining gap is error behavior for invalid custom field keys or mismatched list field types, which the description leaves 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 78%, so most parameters are already documented, but the description adds aggregate meaning by naming the changeable categories and the specific unsubscribe semantics of the two *_subscribed booleans. It does not add detail for list_id/contact_id (only implied by the endpoint path), keeping it short of a 5.

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 ("WRITE: change one contact's ...") and enumerates exactly what can be changed, plus the underlying endpoint PATCH /lists/{list_id}/contacts/{contact_id}. This distinguishes it cleanly from vision6_create_contact, vision6_add_contacts, and vision6_delete_contact without opening any schema.

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

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

"Only the fields you pass change" establishes partial-update semantics and "email_subscribed/mobile_subscribed=false unsubscribes" gives a concrete usage pattern, while pointing to vision6_list_list_fields for discovering custom field keys. There is no explicit when-not-to-use or a direct comparison to create_contact, so routing guidance is strong but not complete.

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

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

Annotations already declare write, idempotent, destructive, and open-world behavior. The description adds useful partial-update semantics ('Only the fields you pass change'), confirms no sending occurs, and identifies the PATCH endpoint, but it does not elaborate on destructive implications or authorization 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?

It is short and front-loaded with 'WRITE', then immediately states the editable fields and the key behavioral constraints. Every sentence adds signal without repetition.

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

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

For a 13-parameter write tool with rich annotations and mostly described schema fields, the description is nearly complete: it explains partial updates, non-sending behavior, and the endpoint. It could say more about destructive risk or permissions, but those are partly covered by annotations.

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

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

The schema has 77% description coverage across 13 parameters, so baseline is near 3. The description groups editable fields and notes partial-update behavior, but it does not add detail beyond the schema for most parameters, such as reply_to, from_name, or the content variants.

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

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

The description states a specific verb (change) and resource (a saved message) and names the editable fields (name, subject, sender, folder, body). It also clarifies that it does not send anything and gives the PATCH endpoint, making it easy to distinguish from create/send 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?

It clearly establishes the editing context with 'Only the fields you pass change' and 'It does not send anything.' However, it does not explicitly name when to use this versus create_message or get_message, nor does it list prerequisites or exclusions.

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