Text-Em-All MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds substantive context beyond that: it flags the mutation explicitly ('MUTATES Text-Em-All data'), states the permission requirement, and discloses that the created user is returned. It does not note side effects like invitations or rate limits, keeping it out of 5 territory.

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 mutation warning and the endpoint, then handles parameters and return value in compact sentences with no filler. Slightly dense with three distinct concerns packed together, but every clause earns its place.

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

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

With no output schema present, the description compensates by stating that the created user is returned, and it covers permission needs and the free-form field convention. Required-parameter behavior (0 required) is not addressed, leaving a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the PascalCase key convention for the free-form `fields` bag and naming valid keys (EmailAddress, Permissions) that the schema itself never lists. That meaningfully reduces misuse risk for a passthrough object.

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

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

States a specific verb and resource ('adds a new user to your account') and anchors it to the exact API operation (POST /v1/account/users). It does not explicitly contrast itself with the sibling update_account_user, 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 one real prerequisite — 'a master user can do this' — which tells the agent whether the caller is eligible. It offers no routing guidance against alternatives such as update_account_user or the generic textemall_request, so usage is only partially specified.

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 description goes well beyond the destructiveHint annotation, disclosing that it mutates data, sends real messages, and spends account credits, plus the return value. It stops short of covering auth requirements or rate limits, but the credit-spend warning is genuinely useful 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?

The most important warning — mutation and credit spend — is front-loaded in caps. The paragraph is dense but each sentence carries actionable information about types, fields, or contacts.

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?

Covers the mutation/credit implications, the endpoint, the SMS-vs-Announcement branching, contact structure, and the return value. With no output schema, stating 'Returns the created broadcast' fills the gap adequately.

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, but the description adds real value by tying parameters together conditionally: textMessage is required for 'SMS' while voiceText or fields.Audio is needed for 'Announcement', and it clarifies the PascalCase passthrough convention for `fields`.

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

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

States a specific verb and resource ('creates + sends a broadcast to the given contacts') and even names the API endpoint. It implicitly distinguishes itself from the sibling create_draft_broadcast by emphasizing that it actually sends, not just drafts.

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 clear context — it mutates data and spends account credits — which tells an agent this is a real send operation, not a dry run. However, it never explicitly names create_draft_broadcast as the non-sending alternative or states when to prefer one over the other.

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 supply destructiveHint=true and a title, so the description carries real weight: it flags the mutation, clarifies that a draft is staged rather than sent, states that an SSO URL is returned for completion in the UI, and cites the endpoint. It also softens the misleading destructiveHint by clarifying no message is sent.

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

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

A single dense paragraph with the mutation warning front-loaded, followed by mechanism, alternative, endpoint, and return shape in descending priority. No sentence is 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 mutation tool with nested inputs and no output schema, the description covers the write semantics, the human-in-the-loop workflow, the endpoint, and the return value (SingleSignOnUrl). Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both the contacts array and the escape-hatch 'fields' object are already documented in the schema with PascalCase examples. The description only restates 'with the given contacts' and adds no syntax beyond what the schema provides, 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 ('stages a broadcast' / 'creates a DRAFT') and immediately bounds the scope ('does NOT send anything'). It explicitly contrasts with the sibling create_broadcast, so an agent can distinguish the two 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?

Gives an explicit selection rule: 'Safer than create_broadcast when a human should review before sending.' This names the alternative and the condition that should route the agent to it, leaving nothing 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 safety is covered. The description adds real value beyond that by disclosing the return payload (company/billing info, AvailableCallUnits, CallBalance) and its role as a credential smoke test — useful given there is no output schema. It omits auth requirements or rate-limit behavior, but the annotations lower the bar.

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 tightly packed sentences: purpose and payload first, then endpoint and usage cue. No filler, every clause carries 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 no-param read tool with no output schema, the description supplies enough: what is returned, specific field names, and how to use it. It could go one step further on error/auth-failure behavior, but nothing essential for calling it correctly is missing.

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

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

The tool takes zero parameters, so per the baseline there is nothing to document and no way for the description to add parameter meaning. Schema coverage is 100% on an empty object.

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

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

States a specific verb ('Fetch'), a specific resource ('Text-Em-All account settings'), and enumerates the payload ('company/billing info plus credit balances'). It also names the endpoint (GET /v1/account), so an agent can distinguish it from siblings like list_broadcasts or get_authorization_token without opening any schema.

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

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

Explicitly tells the agent when to reach for it: 'Use this first to confirm your credentials work,' which is actionable sequencing guidance. It stops short of naming alternatives or stating exclusions (e.g., when not to call it), so it lands at clear-context without full when/when-not 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?

The description adds substantial context beyond readOnlyHint: the signing model ('Signed with your App/Secret key only, no user token yet'), the endpoint, and the response shape ({ AuthToken }). It stops short of disclosing failure behavior (e.g., invalid credentials or rate limits on repeated logins), which would be the remaining useful detail for a credential-consuming call.

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, all front-loaded with the core exchange operation before the endpoint and bootstrapping advice. Every clause carries information the agent needs (auth inputs, endpoint, signing key, return value, one-time usage).

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 credential-exchange tool with no output schema, the description covers inputs, auth context, endpoint, return value, and usage lifecycle. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, making 3 the baseline. The description adds only marginal clarification by mapping password to the 'website login PIN/password' and labeling username as an account username, nothing about format or validation beyond that.

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 ('Exchange a username + PIN/password for that user's authorization token') and pins down the exact underlying endpoint (POST /v1/user/login). It is unmistakably distinct from the other siblings, which are all broadcast/list/account 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?

It gives explicit lifecycle guidance: 'Use this once to bootstrap; store the token in config thereafter,' which tells the agent both when to call it and when not to call it again. It does not name an alternative sibling for token reuse, but the once-only framing is clear enough that no inference is needed.

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 added value is the return-content hint ('including its status and summary'), which is genuinely useful because no output schema exists. It also names the underlying API endpoint. It does not mention failure behavior (e.g., unknown id), but the annotation covers the main safety question.

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 scope, with no filler. The trailing API endpoint line is mildly redundant with the tool name but compact enough not to hurt.

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

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

For a one-parameter read with full schema coverage and annotations covering safety, most of the burden is met, and the partial return-value note compensates for the absent output schema. The remaining gap is disambiguation from get_broadcast_details, which the description never addresses.

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 parameter is documented as 'The BroadcastID.' with a string/number union. The description only restates 'by id' and adds no format, source, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single broadcast by id') and scopes it to one record, which distinguishes it from the plural sibling list_broadcasts. However, it does nothing to distinguish itself from the very similar get_broadcast_details sibling, so an agent cannot be sure which of the two to pick from the text alone.

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 cue is implicit: you need an id, so this is a lookup. There is no statement of when to prefer this tool over get_broadcast_details or list_broadcasts, and no exclusions or prerequisites given. For a family with two near-identical 'get broadcast' siblings, that omission matters.

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 useful behavioral context by specifying what the read returns (per-contact reach and delivery status) and the underlying endpoint, but says nothing about pagination, result volume, or permission requirements.

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

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

Two short sentences with the resource and returned content front-loaded, so the agent reads the essential clause first. The trailing API endpoint note is mildly redundant with the tool name/route but not wasteful enough to drop the score further.

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 must indicate the return shape, and it does by naming per-contact delivery results and status. For a single-parameter read tool with readOnlyHint already declared, this is close to sufficient; only pagination/volume behavior is unaddressed.

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

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

Schema description coverage is 100% and there is only one parameter ('id', documented as the BroadcastID), so the schema carries the parameter burden. The description confirms the id identifies a broadcast but adds no format or source guidance beyond that, matching 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 ('Fetch') and a precisely scoped resource ('per-contact delivery details/results for a broadcast'), and even clarifies the returned content (who was reached, delivery status). This implicitly separates it from get_broadcast (broadcast-level) and list_broadcasts, but it never names a sibling explicitly, so it falls short of a 5.

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

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

The scope 'per-contact delivery details' implies when this tool is the right one (you need individual delivery outcomes rather than a broadcast summary), but there is no explicit when-to-use statement, no prerequisite, and no named alternative to choose against.

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 carry readOnlyHint=true; the description adds the output artifact ({ Url }), the intended consumption surface (browser/iframe), and explicitly confirms no account data is changed. It still omits things like URL lifetime/expiry or auth requirements, so it stops 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 lead with the action, then the optional scoping rule, then the return/endpoint facts. No filler, and the most important information is front-loaded.

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

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

There is no output schema, but the description compensates by naming the return field ({ Url }). With only two optional params and full schema coverage, an agent has everything needed to call this correctly and interpret the result.

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 semantics the schema lacks: both parameters must be supplied together to scope to one conversation thread, and textNumber must be a toll-free number. That joint-use constraint is meaningful beyond the per-field 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 artifact: generate a single-sign-on URL to the Text-Em-All conversations UI. It even names the backing endpoint (POST /v1/singlesignon/conversations) and the return shape, so an agent can distinguish it from siblings like get_authorization_token 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?

Explains where the URL is meant to be consumed (browser/iframe) and gives the optional scoping condition: pass toll-free textNumber plus the other phoneNumber to target a single thread. It does not name an alternative tool or state when-not-to-use, but no sibling competes for this exact job.

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 safe-read aspect is covered. The description adds real behavioral context beyond that: the return payload is a paged Feed with Size, Items, Previous and Next, which tells the agent to expect pagination cursors rather than a flat array. No rate-limit or auth behavior is mentioned, 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?

Front-loaded with purpose and return shape, then endpoint, then filtering/ordering, then the alternative. Dense but every sentence carries information; the brace-notation Feed summary is slightly compressed for readability but not wasteful.

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

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

With no output schema, the description usefully supplies the return shape (paged Feed) and covers filtering, sorting, pagination and the operator escape hatch. For a 5-param nested-object tool it is nearly complete, lacking only error/empty-result behavior and any note on default paging semantics beyond what the schema says.

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

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

Schema description coverage is 100%: page, params, sortby, pagesize and takesize are all documented in the schema, including the same equals-style example and the same textemall_request escape-hatch hint. The description therefore largely restates the schema, which sets the baseline at 3, though the inline operator example (StartDate~gte~2024-01-01) makes the constraint more actionable.

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

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

Specific verb + resource ('List broadcasts') with an explicit scope note that it covers both text and voice campaigns, plus the underlying endpoint GET /v1/broadcasts. It distinguishes itself from the sibling get_broadcast (singular) and textemall_request (named as the escape hatch for operators this tool can't express).

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

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

It states how to filter (equals-style `params`) and how to order (`sortby`), and explicitly routes a specific case — date-range operators like StartDate~gte~2024-01-01 — to the textemall_request sibling. There is no broader when-not guidance (e.g. when to prefer get_broadcast or list_lists instead), but the condition-based routing is concrete.

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 declare readOnlyHint=true, so safety is covered; the description adds the API path, that results come back as a Feed, and the honest caveat that the shape is inferred from the API's List model, which is meaningful context beyond the annotations.

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

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

Purpose and return fields are front-loaded, followed by the endpoint and the caveat. The NOTE sentence is slightly dense but earns its place by flagging model-inference risk.

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 readOnlyHint annotations, no output schema, and full param schema coverage, the description supplies the missing pieces: what a List is, what it returns, the endpoint, and the escape-hatch fallback. Little an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents page/pagesize/takesize and the params filter bag. The description adds little parameter-level detail (only that lists carry ListID/ListName), 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 saved contact lists") and clarifies the domain with "(groups you can broadcast to)", plus names the API endpoint GET /v1/lists. This clearly separates it from siblings like list_broadcasts, list_text_numbers, and get_broadcast.

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

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

Provides explicit conditional routing: if the account/endpoint differs, use the textemall_request escape hatch, and the schema's params note repeats that rule for range operators. It lacks general when-to-use framing, but the alternative-tool guidance is concrete.

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 covers safety, and the description adds that the result is returned as a Feed and that each entry carries a TextNumberID. That return-shape context matters because there is no output schema, though permissions, rate limits, and Feed traversal behavior are not mentioned.

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 resource scope, then the practical reason for calling it, then the endpoint mapping. No restated or filler content.

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 output schema, the description supplies the essential return context (Feed of TextNumber objects, key field) and the endpoint. It stops short of describing what other TextNumber fields an agent can expect or how large feeds behave, which is a modest gap.

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

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

Schema description coverage is 100%, so page, pagesize, takesize, and the params escape hatch are already documented in the schema. The description adds nothing about parameter behavior (defaults, paging interaction), 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 toll-free text (SMS) numbers on your account as a Feed') and pins the API mapping with 'Text-Em-All API: GET /v1/textnumbers'. It also distinguishes itself from the action-oriented sibling by noting the returned TextNumberID is the input to send_text_message.

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

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

Gives clear context for why an agent would call it: to obtain the TextNumberID required before sending a 1:1 conversation text. It does not, however, offer explicit when-not conditions or contrast with the other list_* siblings (list_broadcasts, list_lists).

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 destructiveHint annotation signals mutation, but the description goes further and discloses the traits an agent cannot infer: it spends credits, sends immediately/unrecoverably, hits POST /v1/conversations, and returns the conversation. That is substantive 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?

Front-loads the highest-signal warnings (MUTATES, sends, spends credits) before the mechanics. Dense, single-paragraph, with every clause earning its place.

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

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

With no output schema, the description still states the return value ('the conversation'), and it covers mutation, cost, endpoint, and the required id dependency. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all 7 parameters, establishing a baseline of 3. The description adds the acquisition path for textNumberId (list_text_numbers) but no format or constraint detail beyond what the schema provides.

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 1:1 conversation text message'), and pins the scope tightly: immediate, toll-free number, single contact. This cleanly distinguishes it from the bulk-oriented sibling create_broadcast.

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?

Makes the when-to-use condition clear via '1:1 ... to a single contact' and 'immediately', implying it is not for bulk sends. It also routes the agent to list_text_numbers for the required id, though it never explicitly names create_broadcast as the bulk alternative.

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

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

Annotations declare readOnlyHint=true, and the description reinforces it by stating READ-ONLY and 'only GET is allowed', which is an enforceable constraint rather than a restatement. It also discloses the return format ('parsed JSON'). No error or rate-limit behavior is mentioned.

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 tool's role, then the constraint, then the path format, then the return type in four tight sentences. The inline examples carry concrete information rather than filler.

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

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

For a raw passthrough GET tool with one parameter and no output schema, the description covers purpose, constraint, input format, and return shape. An agent has everything needed to construct a correct call.

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 the path parameter documented, so the baseline is 3. The description adds real value beyond the schema by showing that the full path must include the query string and by demonstrating filter syntax such as 'StartDate~gte~2024-01-01' and 'sortby=-StartDate'.

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

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

States a specific verb (GET) and resource (any Text-Em-All API path not wrapped by a dedicated tool) with explicit scope. The phrase 'escape hatch' plus 'not wrapped by a dedicated tool' cleanly separates it from every sibling like list_broadcasts or get_account.

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

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

Gives a clear selection rule: use this only for paths that dedicated tools do not cover, and it flags the power-user audience. It does not name which dedicated tool to prefer for a given task, but the routing condition is unambiguous.

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 cover destructiveHint=true; the description adds the mutation warning ('MUTATES Text-Em-All data'), clarifies that user_id is path-only and never sent in the body, and states the return value. It stops short of saying which fields are destructive or whether partial updates are safe.

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

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

Front-loads the mutation warning and endpoint, then packs usage details efficiently into a few dense sentences. Slightly information-heavy but every sentence contributes.

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

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

For a mutation tool with no output schema, the description supplies the key missing pieces: mutation semantics, path-vs-body handling, and return value. It does not cover failure modes or permissions, but is otherwise sufficient to call 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 user_id, firstName, lastName, and the fields bag. The description largely restates this (PascalCase examples, path-only user_id), adding only marginal meaning beyond the schema 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 ('updates an existing account user') and pins it to the exact API operation (PUT /v1/account/users/{user_id}). An agent can distinguish it from the sibling add_account_user 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?

Explains how to use the tool (pass changes via `fields` in PascalCase, user_id goes in the path only, not the body). This is clear operational context, but it never states when to prefer this over a sibling or any prerequisites/permission requirements.

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