SlickText MCP by usefulapi

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

Goes well beyond the annotations by warning that SlickText workflows (Contact Created / Contact Field Changed / Contact Added to List) can fire on this event and send REAL texts or take other configured actions. It also discloses the return value (membership count) and the underlying endpoint, which matters since there is no output schema.

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

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

A single dense paragraph with the operation type and action front-loaded, followed by the consequence warning, return value, and endpoint. Every clause carries weight, though the parenthetical about opt-in and audiences could be tightened slightly.

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

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

For a two-parameter mutation tool with no output schema, the description covers all the gaps: what is mutated, what is NOT mutated, the side-effect risk of workflows, what is returned, and the REST path. Nothing an agent needs in order to invoke it safely 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% and both parameters are documented in-schema (list_ids points at slicktext_list_lists, contact_id is a positive integer). The description's 'one contact to one or more lists' merely restates the schema cardinality, adding no new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb and resource ('add one contact to one or more contact lists') and immediately scopes it: it does not change opt-in status, and lists are campaign audiences. The 'WRITE:' prefix and the POST endpoint make it unmistakable against read siblings like slicktext_list_list_contacts or slicktext_create_contact.

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

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

Clearly frames when this applies (attaching an existing contact to audience lists) and implicitly contrasts with opt-in changes, which belong to slicktext_update_contact. It does not name alternatives or state exclusions explicitly, so it stops 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?

Goes well beyond annotations: default 'not subscribed' with no text sent, double opt-in triggers a REAL SMS, and the workflow-trigger warning (Contact Created / Field Changed / Added to List) that may immediately send real texts. Annotations already cover destructiveHint/openWorldHint, and the description adds substantive side-effect context, though it doesn't mention 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?

Front-loads the write nature and core behavior, then adds warnings. Dense and mostly waste-free, though the length (opt_in and workflow warnings) makes it heavier than a typical definition, with some repetition of the consent/real-text theme.

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-param, nested-object, no-output-schema mutation tool, it covers the critical behavioral facts an agent needs (defaults, consent rules, real-SMS side effects, dedup pointer). It stops short of return-value expectations and auth requirements, but those are minor gaps given the 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?

With schema description coverage at 47%, the description compensates by adding real meaning for the semantically tricky params (opt_in_status default and consent condition, force_double_opt_in = real SMS confirmation). Remaining params are largely self-explanatory standard contact fields, so the added value is meaningful but not complete across all 15 params.

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 a specific verb+resource: "WRITE: add a contact to the brand." It distinguishes itself from siblings by routing duplicate-checking to slicktext_find_contact and by stating the write/side-effect profile, so an agent can tell it apart from read tools like slicktext_get_contact or slicktext_find_contact without opening a schema.

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

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

Explicitly states the condition for the key choice (opt_in_status='subscribed' ONLY for people who gave explicit permission) and names the alternative action ("Check slicktext_find_contact first to avoid duplicates"). It also clarifies the effect of force_double_opt_in, so when-to-use and when-not are both covered.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that: lookups are exact-match only, 10-digit US numbers are normalized to +1XXXXXXXXXX as SlickText stores them, and the underlying GET endpoint is disclosed. It doesn't discuss what a match returns, but the added matching semantics are substantive.

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, each doing distinct work: what it does, how matching works, when to use it, and the endpoint. The usage guidance is front-loaded after the purpose, with no filler.

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

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

For a read-only lookup with no output schema, the description covers purpose, matching rules, usage timing and endpoint. The one gap is return shape and pagination behavior (limit/offset/next_offset are documented in the schema but the description never mentions iterating results), which is minor for a finder tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: exact-match (non-fuzzy) semantics and the +1 normalization rule for 10-digit numbers, which directly affects how an agent should format the mobile_number argument.

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 ('Find contacts') plus the lookup keys ('by mobile number or email address') and the match mode ('exact match'). This cleanly distinguishes it from slicktext_list_contacts and slicktext_get_contact, which the agent can rule out without opening their schemas.

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 before creating a contact to avoid duplicates' gives an explicit usage context tied to the sibling slicktext_create_contact. It does not state when not to use it (e.g., when you already hold a contact ID, in which case slicktext_get_contact applies), so it stops short of full when/when-not/alternatives coverage.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds real behavioral color per metric (contacts = current totals, inbox_users = assignments/closures/response times), but says nothing about response size, rate limits, or default time ranges.

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 verb and scope, then metric definitions, then group rules. Dense but every clause maps to a specific enum or constraint; the long group list is necessary because the schema punts on it rather than 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?

With no output schema, the description partially compensates by saying what each metric reports, and it documents the per-metric group constraint fully. A 6-parameter analytical tool with no return-shape documentation leaves some gap, so not a 5.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes beyond the schema by enumerating the allowed group values per metric, which the schema explicitly defers to it ('see description'). This is genuinely additive meaning the schema alone does not carry.

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 ('Brand-level analytics') and enumerates the exact metric set, giving a precise sense of scope. It does not explicitly distinguish itself from adjacent siblings like get_campaign_stats or get_credit_usage, so it falls short of a 5.

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

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

The metric enum and group-per-metric mapping imply when this tool is the right pick for brand reporting, but there is no explicit when-to-use guidance or named alternatives (e.g., to get campaign-specific numbers, use get_campaign_stats). 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?

With readOnlyHint=true already covering safety, the description adds useful behavioral context: it identifies the brand as belonging to the API key and enumerates the data returned, including registration, opt-in, inbox, and credit-limit details. It does not cover error behavior or rate limits, but those are less critical for this read-only lookup.

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 core action and resource, then succinctly lists the returned fields and the brand-scoping context. The trailing endpoint note is compact 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?

There is no output schema, so the description carries the return-value burden. It enumerates the key fields the agent can expect, explains that the result is the API key's brand, and clarifies that all other tools operate within that brand.

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

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

The tool takes zero parameters, so there is no parameter semantics to document. The baseline for zero-parameter tools is 4.

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

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

It names the specific resource (the brand for the current API key) and enumerates the returned fields, making the operation unmistakable. It also distinguishes the tool by noting that every other tool works within this brand, which helps separate it from sibling get/list operations.

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 gives clear context: this returns the brand scoping the API key, and all other tools operate within that brand. However, it does not explicitly state when to call it versus other discovery or settings tools, nor does it list 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?

readOnlyHint=true already establishes this is a safe read. The description adds the raw endpoint path and a preview of returned fields, which is useful, but says nothing about error behavior for an unknown id, pagination, or auth requirements.

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

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

Compact and front-loaded: the action and its key output fields come first, with the endpoint path as a secondary detail. Slightly redundant to include the HTTP path, which adds little for an agent, but nothing is verbose.

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

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

With no output schema, the field enumeration is genuinely valuable for setting expectations on the response. It stops short of describing the shape/types of those fields or failure modes, but it is adequate for a single-parameter read.

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% — campaign_id is fully documented as a positive integer with bounds — so the schema does the heavy lifting. The description only restates 'by id' and adds no format or constraint detail beyond it. 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: retrieves a single campaign by id, and it enumerates the fields returned (body, media_url, status, audience_size, schedule, completion). It implicitly contrasts with slicktext_list_campaigns (one vs many) but never names that sibling.

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' — call it when you already have a campaign_id. There is no explicit when-to-use/when-not guidance and no mention of the obvious alternatives (slicktext_list_campaigns to find one, slicktext_get_campaign_stats for metrics).

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description's main added value is disclosing the return surface (metrics plus campaign, audiences, links) and the underlying GET endpoint. It adds no auth, rate-limit, or pagination context, so it is a modest but real supplement to 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?

Effectively one front-loaded sentence naming the resource and its metrics, followed by the endpoint. The long metric enumeration is informative rather than padding, though the raw field list is slightly dense.

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

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

With no output schema present, the description usefully compensates by enumerating the returned fields and noting the included campaign, audiences, and links. This is sufficient for an agent to call and interpret the tool, though the group-by-source behavior and return shape are not elaborated.

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 both parameters (campaign_id, group-by-source enum) are fully described in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Performance of one campaign') and enumerates the returned metrics, making the tool's scope unambiguous. It does not name or differentiate against close siblings like slicktext_get_campaign or slicktext_get_analytics, which keeps it just short of a 5.

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

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

Usage is implied by the metric list (fetch performance metrics for a given campaign), but there is no explicit when-to-use guidance and no mention of alternatives such as slicktext_get_analytics or slicktext_get_campaign. An agent can infer intent but must choose between siblings 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?

The readOnlyHint=true annotation already establishes this is a safe read, lowering the burden on the description. The description adds what fields come back, but says nothing about behavior on a missing/invalid id, permissions, or rate limits.

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

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

Two sentences, front-loaded with the core action, no filler. The field enumeration is long but earns its place since there is no output schema; slightly dense for a one-parameter lookup.

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?

Because no output schema exists, enumerating the returned fields is genuinely useful compensation, and the description even surfaces the brand_id path parameter that is absent from the input schema. Minor gaps remain around not-found/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?

With only one parameter and 100% schema description coverage, the schema fully documents contact_id, so the baseline is 3. The description's 'by id' is consistent with the schema but adds no syntax or constraint detail beyond it.

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

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

States a specific verb+resource ('Get one contact by id') and enumerates the returned fields, so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from the sibling slicktext_find_contact, which is the nearest alternative, so it falls short of a 5.

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

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

'by id' implies the entry condition (you must already have a contact id), which is implied usage guidance. However, it never states when to prefer this over slicktext_find_contact or slicktext_list_contacts, and gives no exclusions or 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, so the safety profile is covered. The description adds the API endpoint (GET /brands/{brand_id}/inbox-threads/{id}/content) and the id provenance, which is useful context, but it does not describe return format, pagination, or any auth/brand-context requirements implied by the endpoint. With annotations carrying the safety load, a 3 is appropriate.

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 plus the endpoint, front-loaded with the core action and id source, then the alternative routing. Every sentence earns its place with no wasted words.

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 read tool with one required parameter, full schema coverage, readOnlyHint annotation, and no output schema, the description is complete enough. It covers purpose, where to get the id, and the related message-history tool. Return values need not be explained given the absence of an output schema.

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

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

Schema description coverage is 100% and already documents conversation_id with an example. The description adds meaning beyond the schema by telling the agent exactly where to obtain the id: 'the _id from slicktext_list_conversations'. That provenance is valuable operational context not present in 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 ('Get the content of one inbox conversation by its id'), and explicitly ties the id to its source tool (slicktext_list_conversations). This clearly distinguishes it from sibling list_conversations (lists many) and list_messages (message history).

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 the agent for the related but distinct task: 'For the message-by-message history also call slicktext_list_messages with source=InboxThread and source_id=<conversation id>.' This names the alternative tool and the exact parameters to use, so the agent knows when to pick this tool versus its sibling.

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

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating call, so the bar is lower. The description adds the underlying route (GET /brands/{brand_id}/usage) and the exact shape of the credit breakdown, which is genuinely useful context, but it says nothing about auth requirements, caching, or billing-period boundaries.

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

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

One front-loaded sentence naming the resource and its returned fields, followed by a short route reference. Every clause carries information; the endpoint path is slightly redundant but still orienting.

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 does the useful work of listing the returned credit fields, and the readOnlyHint covers the safety profile. For a zero-parameter read, an agent has enough to invoke it correctly; only the billing-period semantics remain vague.

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

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

The tool takes zero parameters, so the baseline of 4 applies. Schema coverage is 100% and there is nothing for the description to clarify beyond the fact that the brand context is implicit in the route.

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 (message credits for the current billing period) and enumerates the four values returned (total_credits, credits_used, credits_available, limit), which clearly separates it from every sibling in the list. It never states an explicit verb, relying on the name 'get', so it falls just short of the highest tier.

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 tool is self-evidently a read-only usage lookup, and no condition, prerequisite, or alternative tool is mentioned. There is no explicit statement of when to call this versus get_analytics or any other reporting sibling.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds real context by disclosing that the response includes contact_list_ids (the lists keyword texters are added to) and the underlying REST route. It says nothing about auth requirements, rate limits, or error behavior, but the bar is lower given the read-only annotation.

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

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

One tight sentence plus the endpoint route; nothing is wasted and the essential information is front-loaded. The endpoint path is mildly redundant for an agent but useful metadata, so slightly below a perfect score.

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

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

With no output schema, the description carries the burden of describing the response, and it does so only partially by naming contact_list_ids while leaving the rest of the keyword object's fields unspecified. For a trivial get-by-id tool this is adequate but not thorough.

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 parameter is fully described in the schema as a positive integer id. The description only adds 'by id,' which is no meaning beyond what the schema already states, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Get one keyword by id') and clarifies the singular scope, which implicitly separates it from the sibling list_keywords. It also previews one returned field (contact_list_ids), so the agent knows what it gets back. It stops short of an explicit sibling contrast, but the purpose is unmistakable.

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

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

Usage is only implied: 'by id' tells the agent it needs a keyword id in hand, which suggests using this after enumeration rather than as an entry point. There is no explicit when-to-use/when-not guidance and no mention of the list_keywords alternative for discovery.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description does add real behavioral value by disclosing that the returned contact count spans all statuses (subscribed/not subscribed/unsubscribed/blocked), which goes beyond the schema and annotations. It stops short of describing error behavior for a bad id or the shape of the returned list object.

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

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

One front-loaded sentence with the payload detail trailing it; nothing is wasted. The raw REST endpoint paths (GET /brands/{brand_id}/lists/{id} ...) are implementation detail of marginal use to an agent choosing a tool, which slightly dilutes the otherwise tight phrasing.

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 fills some of that gap by naming what comes back (the list plus a status-agnostic contact count). For a one-param read against a known brand this is nearly complete; only the returned list fields and failure modes are left unstated.

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

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

Schema coverage is 100% — list_id is already documented as a positive integer with bounds — so the description's 'by id' adds nothing beyond it. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb and singular resource ('Get one contact list by id') plus the extra payload it returns (contact count). This cleanly distinguishes it from the plural sibling slicktext_list_lists, which an agent can select against 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?

Usage is only implied by the phrase 'by id' — the agent can infer this is the single-item fetch versus a listing call, but no sibling is named and no when-not-to-use condition is given. Adequate but leaves the list_lists vs get_list choice 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, so the safety profile is covered and the bar is lower. The description usefully discloses the return payload shape (statuses, timestamps, completion_percentage, audience) and the underlying endpoint, but says nothing about pagination traversal, ordering, or result limits beyond what the schema already documents.

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

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

A single dense sentence that front-loads the action and resource, then lists the payload contents, followed by the endpoint. No filler and nothing repeated from structured fields.

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

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

With no output schema, the field enumeration in the description is the only documentation of return values and it covers the essentials well. It falls short only on list-operation conventions such as ordering or how many results a default call returns, which the schema partially covers via limit/offset.

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

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

Schema description coverage is 100% and all three parameters (limit, offset, status) are already well annotated, so baseline is 3. The description restates the status examples ('draft, scheduled, queued, sent'), adding marginal value but no syntax or edge-case 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 ('List the brand's SMS/MMS campaigns') and enumerates the fields returned, so the agent knows exactly what it fetches. It implicitly contrasts with the singular sibling slicktext_get_campaign via 'List', but never names an alternative, so sibling differentiation is left to inference.

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

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

There is no when-to-use guidance, no prerequisite (e.g. brand_id source), and no mention of when to prefer slicktext_get_campaign, get_campaign_stats, or the paginated siblings. The description only says what it returns, leaving the selection decision entirely to 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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: all filters are exact and case-sensitive with no partial search, and results are paged with count, has_more, and next_offset. This meaningfully reduces misuse, though it could say more about default page size 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?

Three dense sentences with the resource and returned fields front-loaded, followed by the filtering constraint, pagination contract, and endpoint. Every sentence carries information and there is 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 read-only listing tool with full schema coverage and no output schema, the description supplies the filter semantics, the pagination return shape, and the underlying endpoint. It is essentially complete; only alternative-routing detail is absent, which is immaterial to calling it correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, first_name, last_name, custom_fields, and opt_in_status in detail. The description reinforces the global exact-match rule, but the per-parameter semantics are largely duplicative of the schema, warranting the baseline 3.

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 (the brand's contacts/subscribers) and enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly differentiate from close siblings like slicktext_list_list_contacts, slicktext_list_segment_contacts, or slicktext_find_contact, which keeps it below 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 guidance on when to use this tool versus alternatives such as slicktext_find_contact (single lookup) or slicktext_list_segment_contacts (filtered subsets). The 'exact, case-sensitive, no partial search' note is about how filtering behaves, not about tool selection, so it does not qualify as 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 declare readOnlyHint=true, so the safety profile is covered. The description adds value by disclosing the returned field set and the underlying endpoint (GET /brands/{brand_id}/inbox-threads), but says nothing about pagination behavior, brand scoping/auth requirements, 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?

A single front-loaded sentence plus the endpoint path; no filler or repetition. The endpoint path is arguably redundant, keeping it just short of a 5.

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

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

With no output schema, the description usefully compensates by listing the returned fields. Pagination, filtering scope, and brand context are only implicitly covered by the schema and endpoint string, leaving minor 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?

Schema description coverage is 75% with limit/offset and assigned_to_user_id already documented in the schema. The description restates the status enum values and alludes to the assignee filter, but adds little beyond the structured enum and does not explain semantics of the undocumented status 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+resource ('List two-way inbox conversations') and enumerates the fields returned (status, contact, last message, assignee, tags, unread state), so the agent knows exactly what this call yields. It does not explicitly distinguish itself from slicktext_get_conversation or slicktext_list_messages, 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 when-to-use statement, no mention of the sibling alternatives (get_conversation for a single thread, list_messages for messages), and no guidance on when filtering by status or assignee is appropriate. The enumerations imply a listing/overview use case only weakly.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that: it discloses which fields come back and clarifies that internal_name is 'the key used in contact filters and writes,' which is operationally useful for an agent deciding what to do next.

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

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

A single front-loaded sentence naming the resource and its returned fields, followed by the endpoint. No filler, no restatement of the title.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the main thing an agent needs. It could have added a note on pagination flow (the schema mentions next_offset, but the description does not reinforce it), leaving a small 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?

Both parameters (limit, offset) are fully documented in the schema at 100% coverage, so the schema carries the load. The description adds nothing about pagination or ordering, which is the baseline-3 outcome when the schema already 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 and resource ('List the brand's contact custom fields') and even enumerates the returned fields, which no sibling tool covers. An agent can distinguish it from list_contacts, list_lists, or list_segments immediately.

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 verb and the 'brand's contact custom fields' scope, but there is no explicit when-to-use statement, no mention of prerequisites, and no named alternative. With no closely competing sibling, the omission is tolerable but not helpful.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the returned field list and the endpoint path, which is useful given there is no output schema, but it discloses nothing about pagination behavior or brand scoping beyond the path template.

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

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

A single front-loaded sentence with the field list parenthetically attached, followed by the endpoint. Tight and waste-free, though the raw path adds limited value to an agent that already has the 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 simple read-only list tool, the definition covers purpose, returned fields, and endpoint, while annotations handle safety and the schema handles pagination. Only the lack of pagination/result-shape context keeps it short of complete.

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

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

Schema description coverage is 100% with both pagination params fully documented, so the baseline is 3. The description adds no parameter meaning except referencing {brand_id} in the path, which is not even a declared schema 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?

The description gives a specific verb+resource ('List the inbox tags') and clarifies what the resource means ('used to label conversations'), plus names the fields returned. No sibling tool covers inbox tags, so explicit differentiation isn't needed, but it also isn't provided.

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 tags 'label conversations' hints at when an agent might want them, but there is no explicit when-to-use or when-not-to-use guidance and no alternative tools 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, so safety is covered without description help. The description adds the raw endpoint (GET /brands/{brand_id}/keywords) and enumerates which fields the keyword records contain, but says nothing about pagination defaults or empty-result behavior beyond what the schema implies.

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

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

A single front-loaded sentence plus the endpoint path — no padding, and the resource/scope leads. The endpoint restatement is mildly redundant with the tool name but harmless.

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

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

For a read-only list tool with no required parameters, a fully documented schema, and no output schema, this is close to sufficient: it tells the agent what the records look like. Missing only pagination/result-shape detail, which the schema largely covers.

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 limit, active, and offset each fully described in the schema, so the baseline is 3. The description adds no filtering syntax or clarification beyond those field names, so it does not exceed 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 ('brand's text-to-join keywords') and enumerates the record fields returned, which distinguishes it from the singular slicktext_get_keyword sibling. It does not explicitly name that sibling or contrast scope, so it falls short of a 5.

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

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

There is no when-to-use guidance, no mention of when to prefer this over slicktext_get_keyword for a single record, and no note about prerequisites such as needing a brand_id in context. Only the fields returned 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?

readOnlyHint=true already establishes the safety profile, and the endpoint path confirms a read. The '(paged)' marker adds a genuine behavioral trait beyond the annotations, but it doesn't disclose page size behavior, what the response looks like, or how the offset/limit interact.

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, zero filler, with the purpose front-loaded before the endpoint. Slightly minimal rather than padded, which is the right failure mode.

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 paged list tool with no output schema, the description covers the essential scope and paging. It does not describe the returned contact shape or total-count behavior, which is a modest gap given no output schema exists to carry that.

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 (limit, offset, list_id, opt_in_status) are already documented in the schema, including pagination semantics via next_offset. The description adds nothing beyond that 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+resource with a scoping qualifier: 'List the contacts in one contact list'. The 'in one contact list' scope distinguishes it from the unfiltered slicktext_list_contacts and from slicktext_list_segment_contacts, though neither sibling is named 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 description implies usage (fetch members of a given list) but gives no when-to-use, when-not-to-use, or alternative routing. With three overlapping contact-listing siblings, an agent gets no explicit guidance on which one to pick.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the returned field names (contact_list_id, name, description, created) and the HTTP endpoint, which is genuinely useful given no output schema, but it discloses nothing about pagination behavior or result limits.

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

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

A single compact sentence plus a short clause, front-loaded with the resource and return fields, with zero wasted words.

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 listing tool with no output schema, the description compensates by enumerating return fields and the filter, and pagination is covered by the schema's offset description. Only the absence of result-ordering or pagination-flow detail keeps it from a 5.

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

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

Schema description coverage is 100%, so all three parameters (name, limit, offset) are fully documented in the schema itself. The description's mention of an exact name filter restates the schema and adds no new syntax or semantic detail.

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 (the brand's contact lists), and the plural form differentiates it from the singular sibling slicktext_get_list. It doesn't explicitly name or contrast with that sibling, so it falls just short of a 5.

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

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

The description notes an 'Optional exact name filter,' which implies one usage mode, but gives no explicit when-to-use/when-not guidance and never routes the agent to alternatives like slicktext_get_list or slicktext_list_list_contacts. Usage is only inferable.

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

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

readOnlyHint=true already establishes this as a safe read, so the description adds value by disclosing that all filters are exact matches (not fuzzy) and by explaining the source/source_id pairing rule, which is non-obvious behavior. It does not mention rate limits or result ordering, but the behavioral additions are genuinely useful.

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

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

One dense paragraph that front-loads the returned fields and then the filtering semantics, with the endpoint at the end. Every clause carries information, though the enumerated field list makes it slightly long.

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 (to, from, body, direction, source, status, credits, contact) is valuable and appropriate. Combined with the exact-match and source/source_id explanations, an agent has enough to call the tool correctly; only pagination behavior is left implicit.

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

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

Schema coverage is high (88%) so most parameters are already documented, but the description adds meaning beyond the schema by clarifying that to/from can be used to pull a single contact's full history and that source_id is interpreted as a conversation id when source=InboxThread. That relational detail is not present in 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 specific verb and resource ('List individual SMS/MMS messages sent and received by the brand') and enumerates the returned fields, making the scope clear. It implicitly separates itself from conversation-level siblings by stressing 'individual' messages and the InboxThread/conversation-id path, but it never names an alternative tool, so it falls short of full sibling differentiation.

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 gives concrete usage patterns: filters are exact matches, use to/from with a phone number to read one contact's history, or source=InboxThread with source_id set to a conversation id. That tells the agent how to shape calls for common intents, though it offers no explicit when-not-to-use guidance or named alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only '(paged)' and the endpoint path; it doesn't mention rate limits, ordering of results, or what happens for an empty/unknown segment. Adds some but not rich behavioral context.

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

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

A single compact sentence plus endpoint reference, front-loaded with the verb and resource. No wasted words.

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 paged list tool with a fully documented schema and annotations carrying the safety profile, the description covers what's needed to invoke it. Return shape is not described, but with no output schema this is a minor gap for a simple list endpoint.

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 segment_id are fully documented in the schema (including the next_offset pagination hint). The description adds nothing parameter-specific beyond noting paging, so the baseline 3 is appropriate.

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

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

States a precise verb+resource: 'List the contacts that currently match one segment (paged)', plus the underlying endpoint. It is distinguishable from siblings like slicktext_list_contacts and slicktext_list_list_contacts by the segment scoping, though it never explicitly contrasts 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?

Usage is implied by the name and resource scoping — an agent can infer this is for reading a single segment's members. There is no explicit when-to-use guidance, no mention of the alternative list_contacts/list_list_contacts tools, and no stated prerequisites such as segment existence.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine context beyond that: it names the returned fields (segment_id, name, description) and the underlying endpoint, which is useful given there is no output schema.

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

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

A single front-loaded sentence plus an endpoint reference, with zero filler. Every clause earns its place.

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

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

For a read-only list tool with full parameter documentation and readOnlyHint covering the safety profile, the description supplies the missing return-shape information in place of an output schema. It lacks only pagination behavior, which the schema already handles.

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 both limit and offset fully documented, including the next_offset pagination hint, so the schema carries the burden. The description adds no parameter detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List the brand's segments') and clarifies what a segment is (rule-based contact groups), which usefully distinguishes it from slicktext_list_lists. It does not explicitly name a sibling to route against, so it falls short of a 5.

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

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

The read-only listing intent is implied by the name and description, but there is no explicit when-to-use guidance and no mention of when to prefer slicktext_list_lists or slicktext_list_segment_contacts instead. 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?

Goes well beyond the annotations: it discloses that only passed fields are sent, that changing fields can fire brand workflows which may immediately SEND REAL TEXTS, and it names the triggering events. The annotations only flag destructive/openWorld; the description supplies the actual operational hazard.

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 a 'WRITE:' marker and the partial-update rule, then the risk warning. Dense but every clause carries weight; the trailing PUT path is the only mildly redundant element.

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 with no output schema and destructive side effects, it covers write semantics, opt-in rules, and workflow fallout well. The remaining gap is that most of the 15 fields are undocumented in both schema and description, but the high-risk behaviors are adequately surfaced.

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 47%, so the description must compensate for the 15 parameters. It adds meaningful semantics for opt_in_status (though the schema already states the consent rule) but says nothing about custom_fields, mobile_number, or the other undocumented fields, leaving much of the coverage gap unfilled.

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 (change fields) and resource (an existing contact), and the word 'existing' implicitly distinguishes it from slicktext_create_contact. It does not name the sibling explicitly, and the PUT endpoint is echoed rather than adding routing value, 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?

Gives real conditional guidance: opt_in_status can unsubscribe/block, and 'subscribed' must only be set with explicit consent. However, it never names an alternative tool or states when to prefer slicktext_create_contact or slicktext_add_contact_to_lists over this one.

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