TextUs MCP by usefulapi

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

Adds genuine context beyond the minimal annotations (only destructiveHint=true and a title): the mutation label, the fact that the note is internal and invisible to the contact, and the underlying POST endpoint. It does not clarify why a note-add carries destructiveHint=true or whether notes can be edited/removed, which would have closed the gap.

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

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

Three compact sentences, front-loaded with the operation type, followed by the key behavioral fact and the API mapping. No wasted text.

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

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

For a two-parameter write tool with no output schema, the description supplies the essentials: mutation semantics, visibility of the created note, and the backing endpoint. Only the destructiveHint rationale and idempotency/limits are left unexplained.

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 (contact id, note text with a 5000-char cap). The description adds no parameter-level information beyond the endpoint template, so the baseline 3 applies.

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

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

States a specific verb+resource ("adds an internal note to a contact") and the WRITE prefix immediately separates it from the read-side sibling textus_list_contact_notes. An agent knows exactly what this does without opening the 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 WRITE label and the word "adds"; there is no explicit when-to-use or when-not guidance, and the read counterpart textus_list_contact_notes is never named as the alternative for retrieving notes.

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 "WRITE:" marker plus the raw endpoint (POST /{account}/contacts) reinforces the mutation semantics already implied by destructiveHint=true, so it is consistent rather than contradictory. However, it says nothing about duplicate-phone handling, whether the call is idempotent, permission requirements, or what object comes back — meaningful gaps for a create operation even allowing for the lower bar set by annotations.

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

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

Two short, front-loaded sentences with no filler; the operation type leads and the endpoint follows. Nothing is padded, though the terseness comes at the cost of substance rather than being a model of density.

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 6 parameters, 3 of them required, and no output schema, the description should ideally say what a successful create returns (e.g., the new contact ID) and how failures like duplicates surface. It leaves both unaddressed, though the fully-described schema and the destructiveHint partially compensate.

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

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

Schema description coverage is 100%, so all six parameters (including the account-slug cross-reference to textus_list_accounts and the phone_type default) are already documented in the schema. The description adds no field-level meaning beyond that, so the baseline 3 applies.

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

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

The opening "WRITE: creates a new contact in an account" gives a specific verb (creates) and resource (contact) scoped to an account, which cleanly separates it from the read siblings like textus_get_contact and textus_list_contacts. It stops short of explicitly naming an alternative, but the create-vs-read distinction 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?

There is no when-to-use guidance, no preconditions stated (the account slug requirement only appears in the schema), and no mention of what to do when a contact already exists at that number. The agent is left to infer everything about selection context from the verb 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the underlying GET /accounts/{account} endpoint and the shape of the returned fields. It says nothing about error behavior for an unknown slug, permissions, or rate limits, which would raise it further.

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 core purpose and returned fields, with the endpoint appended as compact technical context. Nothing is redundant or 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 output schema, listing the returned fields (name, phone numbers, type, links) is genuinely useful, and the endpoint corroborates the read semantics. A simple single-parameter read doesn't need much more, though error cases for a bad slug remain unaddressed.

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

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

Schema coverage is 100% and the single parameter is well documented in the schema, including its source (the `slug` field from textus_list_accounts). The description only restates 'by slug' and adds no format or validation detail beyond the schema, so baseline 3 applies.

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

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

Names a specific verb (get) and resource (one account) plus the identifying key (slug) and the fields returned (name, phone numbers, type, links). It implicitly separates itself from the many list_* siblings by emphasizing a single account, though it never names textus_list_accounts directly.

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 clearly the single-record counterpart to listing accounts, and the schema notes the slug comes from textus_list_accounts. The description states no explicit when-to-use or when-to-prefer-a-sibling guidance itself.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main additions are the returned field set and the underlying REST endpoint. It does not disclose error behavior (e.g. not-found), permissions, or rate limits, so it adds only modest context beyond the annotation.

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

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

Two sentences with no filler: the capability and returned payload are front-loaded, and the endpoint reference is a compact trailing clause. Nothing is redundant or 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?

For a one-parameter read tool with annotations covering safety and no output schema, the description's enumeration of returned fields fills the main gap an agent would have. Only error/failure behavior is left unstated, which is minor here.

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

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

Schema description coverage is 100% and the schema already explains that 'campaign' is a campaign id sourced from textus_list_campaigns. The description adds no format, validation, or lookup detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one campaign') and enumerates what comes back (message body, state, schedule, recipient counts), which distinguishes it from the list variant. It stops short of explicitly naming textus_get_campaign_analytics as the sibling that covers metrics, so the boundary with analytics is only inferable from the field 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?

'Get one campaign' plus the singular scope implies retrieval of a known id, and the schema note points at textus_list_campaigns as the id source. There is no explicit when-to-use guidance, no exclusion against textus_get_campaign_analytics, and no statement of what happens if the campaign does not exist.

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 underlying endpoint mapping (GET /{account}/campaigns/analytics) and names the aggregated metrics, but says nothing about the aggregation window (lifetime vs. some implicit period), which materially affects interpretation of the numbers.

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

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

Two compact sentences, with the resource scope front-loaded and the endpoint reference as supporting detail. 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 single-parameter read-only aggregation tool with no output schema, listing the metrics returned and the account scope is largely sufficient. The one real omission is the time window over which the aggregation applies.

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

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

Only one parameter and schema coverage is 100%, so the schema already explains that 'account' is the account slug sourced from textus_list_accounts. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema fully documents the input.

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 aggregated statistics') and enumerates the metrics returned (campaigns sent, recipients, delivery) scoped to 'all campaigns of an account'. This distinguishes it implicitly from textus_list_campaigns and textus_get_campaign, though it never names those siblings.

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

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

The scope ('for all campaigns of an account') implies when to use it — account-wide rollup rather than per-campaign detail — but there is no explicit when/when-not guidance or named alternative for single-campaign stats vs. the conversation stats tool.

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 value by enumerating returned fields and citing the underlying endpoint (GET /contacts/{contact}), but says nothing about error behavior for a missing contact or response shape beyond the field list.

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 what the tool does; the endpoint reference is secondary but still earns its place for debugging. No filler or repetition 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?

For a one-parameter read tool with readOnlyHint and no output schema, the description covers purpose, returned data, and endpoint. Missing only edge-case behavior (e.g. unknown contact id), which is minor at this complexity.

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

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

Schema description coverage is 100% and the single 'contact' parameter is already documented with its provenance ('from textus_list_contacts'). The description adds no syntax or format detail beyond the schema, 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 and resource ('Get all known data about one contact') and enumerates the returned data: name, phone numbers, custom data, tags. It implicitly distinguishes itself from textus_list_contacts by specifying 'one contact', though it does not name the sibling explicitly.

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

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

Usage is implied: fetch a single contact once you know its id. It does not state when to prefer textus_list_contacts or textus_list_contact_filters instead, and the guidance on where the id comes from lives in the schema, not the description.

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 already declaring the safety profile, the description adds useful behavioral context by disclosing what the response contains (contact, assigned users, state, last message) and the underlying API route. It omits pagination/error behavior, but for a simple read that is minor given 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 tight sentences, front-loaded with the core action and response contents; nothing extraneous. The API route line is compact and does not dilute the message.

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

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

For a single-parameter read tool with readOnlyHint and no output schema, the description adequately covers purpose and the shape of returned data. It could do slightly more to distinguish from adjacent conversation endpoints, but nothing essential 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?

Only one parameter with 100% schema coverage, so the schema already documents 'conversation' fully. The description echoes the path parameter but adds no format or constraint detail beyond it, matching the baseline 3 for well-covered schemas.

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 one conversation') and names the fields returned (contact, assigned users, state, last message). It does not explicitly differentiate itself from siblings like textus_get_conversation_timeline or textus_get_conversation_stats, which is the main gap.

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?

'Get one conversation' weakly implies retrieval of a single record vs the list sibling textus_list_conversations, but there is no explicit when-to-use or when-to-prefer-an-alternative (timeline/stats) guidance. 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 tells the agent this is a safe read; nothing here contradicts it. The description adds that the response contains three specific metrics, but says nothing about empty/null behavior for conversations with no outbound messages, whether the percentage is a ratio or a formatted string, or any auth/rate-limit context.

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

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

Two compact sentences with zero filler; the payload (the three metrics) is front-loaded and the API endpoint reference is appended as a secondary aid.

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

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

For a single-parameter read tool with no output schema, the description does the necessary work by naming the returned metrics, which stands in for the missing output schema. Only the shape/formatting of those metrics and empty-state behavior are left 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?

Only one parameter and schema description coverage is 100%, so the schema already defines 'conversation' as the conversation id. The description adds no format hints (e.g., id prefix or where to obtain the id), 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 and resource ('Get stats for one conversation') and enumerates the exact facts returned: start time, engagement grade, outbound delivery percentage. That distinguishes it from textus_get_conversation and textus_get_conversation_timeline by content rather than by an explicit comparison, so it stops 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 field list implies when the tool is useful (you want aggregate metrics rather than message content), but there is no explicit 'use this instead of X' guidance and no stated prerequisites such as needing a valid conversation id from a list call. Usage is inferable, 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?

readOnlyHint already covers safety, and the description adds real context beyond that: sort order (newest first) and what a message record contains (direction, body, delivery state). With no output schema, this return-shape disclosure is the main behavioral signal; pagination behavior itself is only implied.

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

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

Three short sentences, front-loaded with the core purpose and ordering. The trailing API endpoint line is boilerplate but compact and occasionally useful for mapping errors.

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 a fully documented two-param schema, the definition covers purpose, ordering and record contents. It is slightly thin on what the 'events' part of the timeline contains and takes return shape no further than the message fields.

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 the conversation id and the cursor (including how to read it from view.next) already documented. The description adds no parameter meaning of its own, 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 (get messages and events of a conversation) and adds ordering ('newest first'), which separates it from textus_get_conversation (metadata) and textus_get_conversation_stats. It never names those siblings explicitly, so an agent still infers the boundary.

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 a conversation's message/event history) but gives no explicit when-to-use/when-not guidance relative to the siblings it sits beside, such as textus_get_conversation or textus_get_conversation_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 readOnlyHint=true, so the safety profile is covered; the description adds useful content beyond that by disclosing what the response contains (account memberships and roles) and pinning the identity to the token owner. It stops short of detailing auth failure behavior or that no arguments are accepted, which is minor for a read-only endpoint.

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

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

Two short sentences with the purpose and returned contents front-loaded and the API endpoint appended as a reference. Nothing is repeated from the title 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?

For a zero-argument, read-only lookup with no output schema, the description covers what the tool returns (profile plus memberships and roles) and whose profile it is, which is sufficient to call it correctly. Slightly more routing context relative to textus_get_account would make it complete.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no identifying input is needed because the subject is derived from the API token, which is the only parameter-relevant fact an agent needs.

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 profile") and narrows the scope to "the user who owns the API token, including account memberships and roles," which separates it from account-level siblings like textus_get_account and textus_list_account_users. It does not explicitly name those siblings, so differentiation is implied rather than routed.

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 "user who owns the API token" implicitly tells the agent to use this for self-identity/current-user lookups, but there is no explicit when-to-use guidance, no stated exclusions, and no named alternative for looking up other users or accounts.

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 description adds useful context beyond that: results are scoped to accounts the user belongs to (permission-filtered), each row includes phone numbers and role, and the underlying endpoint is GET /accounts. Ordering, page size, and whether an empty list is an error are not covered.

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 purpose, then the highest-value fact (other tools need a slug from here), then the endpoint. Zero filler.

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

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

For a simple no-required-param list tool with no output schema, the description does tell the agent what comes back (phone numbers, role, and implicitly the slug it needs downstream). Pagination is handled by the schema, so nothing critical is missing, though the shape/field names of results are only loosely described.

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

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

There is one optional parameter and the schema fully documents it, including how to obtain the cursor value from `view.next`. The description adds nothing about the cursor, so the baseline of 3 applies when the schema does the work.

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

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

Names a specific verb and resource ('List the TextUs accounts') and adds scope ('the user belongs to') plus returned fields (phone numbers, role). It does not explicitly distinguish itself from the sibling textus_get_account, so an agent must infer that one is single-account retrieval and the other is enumeration.

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?

'Most other tools need an account `slug` from here' is a genuine routing hint that tells the agent to call this first as a discovery step. No explicit exclusions or when-not conditions are stated (e.g., versus textus_get_account when the slug is already known).

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 underlying endpoint (GET /{account}/users), which confirms a read, but says nothing about pagination behavior, result size, or permissions needed to enumerate account users.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded ahead of the API reference detail. Nothing could be removed without losing information.

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

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

With no output schema, the description could have sketched the return shape (a paginated user list) so an agent knows a cursor loop may be needed. As written it is adequate for a simple two-parameter list tool but leaves the response contract entirely 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%: both 'account' (with a pointer to textus_list_accounts' slug field) and 'cursor' (with the view.next convention) are fully documented in the schema. The description adds no parameter meaning 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 ('List') and resource ('users') with an explicit scope ('who belong to an account'), which cleanly separates it from siblings like textus_get_profile or textus_list_accounts. It does not explicitly name an alternative, but the resource is distinct enough that confusion is unlikely.

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 purpose statement: call it when you need the users of a given account. There is no explicit guidance on when to prefer this over textus_get_profile, nor any prerequisite note beyond the account slug reference buried in the schema.

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 exact REST endpoint, which is useful for understanding the data source. However, it does not clarify whether these are user-created saved views or fixed filter categories, and the "campaign views" phrasing diverges from the tool name's "campaign filters", leaving the returned object's nature ambiguous with no output schema to compensate.

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 compact sentence plus the endpoint reference, with the purpose front-loaded and no filler. The parenthetical example is arguably the only slightly loose 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 one-parameter read tool with annotations and full schema coverage, the minimum is met, but with no output schema the description should say what a campaign filter/view actually contains (names, ids, whether they're usable as filters elsewhere). That gap plus the title/description terminology mismatch leaves the agent guessing at the return shape.

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

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

Schema coverage is 100%; the single `account` parameter is documented in-schema as a slug sourced from textus_list_accounts. The description adds nothing about the parameter, 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 ("List the campaign views of an account") and includes the underlying endpoint, so the agent knows it is a read of saved campaign filter/view definitions. It does not distinguish itself from the nearest sibling, textus_list_campaigns, or explain how "campaign views" differ from the filters named in the title.

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?

Examples ("for example mine, all") hint at what the listed values look like, but there is no statement of when to call this versus textus_list_campaigns or textus_list_contact_filters, and no prerequisites or exclusions 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, so the safety profile is covered. Beyond that, the description adds genuinely useful behavior: results are ordered by scheduled time and each entry carries title, body and state. It omits pagination behavior (the `view.next` cursor flow), which is the main remaining gap.

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 compact sentence front-loads the resource, scope, ordering and returned fields, followed by a short endpoint reference. No filler, though the endpoint line is more developer reference than agent guidance.

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 should carry the return contract; it names title/body/state but never mentions that results arrive as a view with a `view.next` cursor, which the schema's cursor parameter implies. Adequate for a simple list call, but the pagination loop is left to inference.

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

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

Schema coverage is 100%, so all three parameters already have descriptive text including the `all` default for campaign_filter and the cursor sourcing rule. The description adds nothing parameter-specific beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource ('List campaigns (bulk messages)') plus the scope ('in a campaign view'), the ordering, and the API endpoint. It clearly separates itself from textus_get_campaign (single item) and textus_list_campaign_filters, 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?

No when-to-use, when-not, or prerequisite guidance. It doesn't say the `campaign_filter` slug typically comes from textus_list_campaign_filters, nor when to prefer textus_get_campaign for a single campaign. The endpoint line is reference info, not usage guidance.

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

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

readOnlyHint=true already declares the safe read profile, so the description needn't cover that. It adds the HTTP endpoint mapping, which is mildly useful for cross-referencing docs, but says nothing about pagination behavior, result ordering, or what an empty result means.

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

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

Two short sentences, purpose front-loaded, endpoint detail trailing. Nothing is wasted and nothing is buried.

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

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

For a simple two-parameter read-only list tool with full schema coverage, no output schema, and a clear readOnly annotation, the description is nearly sufficient. The only minor gap is that it doesn't hint at the shape of a returned filter, which an agent might want.

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 'account' and 'cursor' are already fully documented, including where the cursor comes from. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('saved contact filters (views)') scoped to an account, plus the underlying API endpoint. The resource noun naturally distinguishes it from siblings like textus_list_campaign_filters and textus_list_conversation_filters, though no 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?

There is no statement of when to use this versus related filter-listing tools or why an agent would pick it over textus_list_contacts. Only the implicit 'list saved filters for an account' context is conveyed.

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, so the description's main burden is lighter. It adds the underlying REST endpoint and the fact that notes are user-authored, but says nothing about ordering, result volume, or pagination behavior beyond what the schema's cursor field already declares.

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

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

Two short sentences with the purpose front-loaded and zero filler. The API endpoint reference is marginally redundant but serves as a useful cross-reference, so it doesn't hurt much.

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 two-parameter read tool with full schema coverage, a read-only annotation, and no output schema, so the description doesn't need to explain return values. It covers what the tool does and where it maps in the API, leaving only minor gaps around result shape and pagination expectations.

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

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

Schema description coverage is 100%, so both 'contact' and 'cursor' are already documented, including the pagination semantics in the cursor field. The description adds no parameter-level meaning beyond the schema, which is the expected baseline 3 here.

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

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

The description uses a specific verb ('List') plus the resource ('notes users wrote about a contact'), so an agent knows it retrieves contact notes. It doesn't explicitly separate itself from textus_add_contact_note, but the read/list framing makes the distinction fairly obvious.

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 'about a contact' implies the tool requires a contact in hand, so usage context is inferable. However, there is no explicit when-to-use/when-not, no mention of how this differs from textus_get_contact or textus_get_conversation_timeline, and no prerequisite 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 safety is covered; the description adds real behavioral context on top: results come back in alphabetical order, `all` is the default filter, and the underlying endpoint is GET /{account}/contact_filters/{filter}/contacts. Pagination limits and result caps are not described, keeping it 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 tight sentences: the core operation and ordering come first, then the two filter parameters, then the API mapping. Nothing is redundant and no sentence 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 read-only four-parameter list tool with full schema coverage and no output schema, the description covers operation, ordering, defaults, and backend mapping. Minor gaps remain around whether `all` includes opt-outs and what the page size is, but nothing blocking correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the schema — `q` searches name or phone, `contact_filter` defaults to `all` — without adding syntax, matching rules, or cursor mechanics beyond what the properties already say.

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

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

States a specific verb and resource ("List contacts of an account") plus return ordering (alphabetical), which clearly separates it from textus_get_contact and textus_list_group_contacts by implication. It never names a sibling explicitly, so differentiation relies on the reader inferring list-vs-get semantics.

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 explains how to use two parameters (search with `q`, saved view via `contact_filter`, default `all`), which implies when to use the tool. It gives no explicit when-not guidance or named alternative (e.g., use textus_list_group_contacts for group membership), so the agent must infer the boundaries.

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 real behavioral context beyond that: it discloses the return payload (filters with unread counts) and grounds the tool in a concrete API endpoint (GET /{account}/conversation_filters). It omits pagination/ordering behavior, but for a small read-only list that is a minor gap.

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 carrying the resource, examples, and return payload, followed by a compact endpoint reference. No filler or redundancy.

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

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

For a one-parameter, read-only list tool with full schema coverage and no output schema, the description covers what the tool does and roughly what comes back (filters plus unread counts). Only the exact response shape and ordering remain unstated, which is acceptable at this complexity.

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

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

Schema coverage is 100% and the single `account` parameter is documented with its source (`slug` from textus_list_accounts). The description adds only the phrase 'of an account', which does not extend the schema's meaning, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (conversation filters), and clarifies the ambiguous term with concrete examples ('inbox views such as unread, mine, closed') plus the payload ('with unread counts'). It reads clearly as distinct from textus_list_conversations, though it does not explicitly name any sibling to reinforce that distinction.

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: an agent can infer this is the discovery step for inbox views before calling textus_list_conversations, but the description never says when to prefer it over that sibling or whether it needs a prior textus_list_accounts call. No exclusions or prerequisites are stated.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It adds the newest-first ordering and the endpoint mapping, but says nothing about page size, whether filters restrict results, or what a conversation record contains.

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

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

Three short sentences, front-loaded with the primary behavior, then the search path, then the endpoint. No filler or repetition of schema text.

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

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

No output schema exists, yet the description covers what is returned only at the level of 'conversations, newest first'. Pagination is handled by the cursor field in the schema, so the main remaining gap is the shape of each returned conversation.

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 adds relational meaning the schema lacks: `q` is only meaningful in combination with the `search` filter. That coupling is not stated in the schema and is genuinely useful.

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 conversations in an inbox view'), plus the ordering guarantee ('newest message first') and the underlying endpoint. It is clearly distinguishable from the singular sibling textus_get_conversation.

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 tells the agent how to search: use filter `search` with `q` (phone number or text). It does not state when to prefer a sibling such as textus_get_conversation or textus_get_conversation_timeline, so routing is clear but not exhaustive.

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 only adds the REST endpoint (GET /groups/{group}/contacts), which is mildly useful context but says nothing about pagination behavior or return shape beyond what the cursor parameter already implies.

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

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

Two short sentences, front-loaded with the action and resource. The endpoint sentence is low-value but costs almost nothing in length.

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 simple two-parameter read tool with full schema coverage and readOnly annotations; the description is adequate for calling it correctly. A brief note that results are paginated via cursor would round it out.

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 group and cursor fully documented in-schema. The description adds no parameter detail beyond restating the path template, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the contacts that belong to a group') and scopes it to group membership, which implicitly separates it from textus_list_contacts. It does not name that sibling explicitly, so the 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?

The group-scoped framing implies when to use it (you have a group id and want its members), but there is no explicit when/when-not guidance and no mention of textus_list_contacts as the alternative for all contacts.

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, so the bar is lower. The description adds the underlying REST endpoint (GET /{account}/group_filters/{filter}/groups), which reveals the resource hierarchy that `group_filter` maps to, but says nothing about pagination behavior or result size limits even though a `cursor` param exists.

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 an endpoint reference, with the core purpose front-loaded. The API route is arguably redundant with the naming of the resource, but it is brief and does add 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?

For a simple read-only list tool with one required parameter, full schema coverage, and no output schema, the description covers resource, scope, and search. The only real gap is how to interpret/iterate results, which the cursor param partly implies.

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 are already documented in the schema, including the `mine` default and the cursor's provenance. The description adds only marginal framing ('search group names', 'group folder') and does not explain the `q` 'phone digits' matching or the relationship between group_filter and filter slugs beyond schema text.

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

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

States a specific verb and resource ('List contact groups in a group folder') and clarifies the two folder scopes ('mine' or account groups), which separates it from the similarly named sibling textus_list_group_contacts. It never explicitly names that sibling, so differentiation is inferable rather than stated.

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

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

The only usage-like sentence ('Use `q` to search group names') is parameter guidance, not situational guidance. There is no statement of when to call this versus textus_list_group_contacts or textus_list_contact_filters, and no prerequisites or exclusions.

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

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

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description adds useful specifics — the API endpoint and the 3-digit minimum on `q` — but says nothing about result volume, pagination behavior, or what the listing contains beyond phone numbers.

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

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

Two sentences, front-loaded with the purpose and followed by the one non-obvious parameter constraint and endpoint. Nothing is wasted and nothing is buried.

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

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

For a simple three-parameter read-only list with no output schema, the agent has enough to call it correctly: purpose, the key search constraint, and the endpoint. The return shape (what fields accompany each phone number) is not described, but it is minimally inferable from the name.

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 baseline is 3. The description does add one constraint not in the schema — `q` requires 3 or more digits for a partial search — but cursor and account semantics 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?

States a specific verb+resource ("List phone numbers that opted out of messages for an account") and names the underlying endpoint, which pins down the entity precisely. It does not explicitly contrast with siblings like textus_list_contacts, but the opt-out subject matter is distinctive enough that confusion is unlikely.

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 reader infers that calling without `q` lists all opt-outs and calling with `q` narrows the result. There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance (e.g. pointing to textus_list_contacts for non-opted-out numbers).

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 declares the safety profile, so the description's main addition is the underlying API route (GET /users/{user}/saved_replies), which confirms the read-only scoped-by-user behavior. It does not disclose pagination behavior or what a saved reply record contains, so the added context is real but thin.

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

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

Two short sentences, purpose front-loaded, API route trailing as reference. Nothing redundant and nothing buried.

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

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

For a two-parameter read-only list tool with a fully documented schema and no output schema, this is nearly complete. The only gap is any hint about the shape or ordering of returned saved replies, which the description leaves entirely to the caller's inference.

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%: `user` points at textus_get_profile and `cursor` explains exactly where to obtain the value from `view.next`. The description adds nothing beyond that, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('List the canned message bodies a user saved') and even glosses the meaning of 'saved replies', which removes ambiguity. No sibling competes for this resource, so explicit differentiation isn't required, but it is also not stated.

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

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

Usage is only implied: the agent can infer this is the read path for saved replies, but the description never says when to choose it, whether another tool returns canned replies in another context, or what prerequisites exist beyond the `user` 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 only flag destructiveHint=true; the description goes further by disclosing that messages cannot be undone, are never retried, and require explicit user approval via confirm=true. It also names the underlying endpoint (POST /{account}/messages), which helps the agent reason about side effects. This is exactly the added context the annotation bar asks for.

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?

Four short clauses, front-loaded with the WRITE label and the irreversibility warning before the procedural instruction. No filler; each sentence carries distinct information.

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

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

For a destructive write with no output schema, the description covers safety, approval workflow, and side effects well. The one gap is that it doesn't indicate what the call returns (message IDs, per-recipient status), which an agent may need to report back or verify delivery.

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 are already documented in the schema, including confirm's "Must be true" semantics. The description's mention of showing recipients and passing confirm=true largely restates the schema rather than adding format or constraint detail. 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 ("sends a REAL SMS") with scope ("from the account's number to one or more recipients"), which cleanly separates it from the read-only sibling tools like textus_get_conversation or textus_list_contacts. An agent can identify it as the sole outbound-write tool without opening the 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 an explicit precondition workflow: "Show the user the recipients and text first, then call with confirm=true." This tells the agent what to do before invoking. It stops short of naming alternatives or when-not-to-use cases, but for a terminal send action there is no obvious alternative to route to.

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