FireText MCP by usefulapi

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 a non-obvious failure mode (URL error on non-trackable messages) and the vendor endpoint, which is context the annotation cannot supply. It does not cover pagination behavior or empty-result cases.

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 telegraphic sentences with the core purpose front-loaded and no filler. The parenthetical field list is compact rather than wasteful, though the clipped style slightly hurts readability.

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 previews the returned fields and states the message-ID prerequisite plus the sub-account/pp details live in the schema. For a single-resource read tool the agent has what it needs to call it correctly.

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

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

Schema description coverage is 100%, so pp, page, message, and subaccount are already fully documented in the schema; the description adds nothing about them. The parenthetical field list describes return values, not parameters, so baseline 3 applies.

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

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

States a specific resource and scope: link clicks for one sent message, plus the fields it returns (mobile, names, clicked, userAgent). An agent can distinguish it from firetext_get_delivery_report by the 'click' focus, though the description never names that sibling, so it stops short of 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 a clear eligibility condition: only messages sent with FireText's Trackable SMS feature, otherwise the vendor returns a URL error. That is real when-to-use guidance, but no alternative tool or fallback is named for non-trackable messages.

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 that the lookup is keyed strictly by mobile number and hints at the shape of the record returned, but says nothing about not-found handling or account/subaccount scoping effects.

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 tight sentence front-loads the essential lookup key, and the endpoint reference is short. Nothing is padded, though the endpoint path is metadata of marginal use to an agent selecting the tool.

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

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

With no output schema, the field enumeration (firstname, lastname, mobile, customField1-3) usefully tells the agent what comes back, and only two well-documented parameters exist. The missing piece is behavior on a missing/invalid number.

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 mobile formats and the subaccount rule already spelled out in the schema. The description only restates 'by mobile number' and defines no parameter semantics of its own, 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 the resource (one contact), the lookup key (mobile number), and even enumerates the returned fields (firstname, lastname, mobile, customField1-3). It is clearly a single-record read, which separates it from the list_* siblings, though it does not name any 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?

There is no guidance on when to use this versus alternatives such as list_unsubscribed or the subscribe/unsubscribe contact tools, nor any mention of preconditions or failure behavior when the number is not found. Usage must be inferred from the name alone.

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

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

The readOnlyHint annotation already declares this is a safe read, lowering the burden on the description. The description adds the account-vs-subaccount scope but says nothing about the return format or whether an empty/low value has special meaning. Adequate but thin behavioral context.

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

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

Two short, front-loaded sentences with no filler. The trailing 'FireText: /credit.' is a REST endpoint reference of marginal value but costs little.

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

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

For a simple read-only tool with one optional parameter and no output schema, stating what is returned (remaining message credits) covers the essential need. Only the return shape/format is left implicit, which is minor here.

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

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

Schema coverage is 100%, so the 'subaccount' parameter is fully documented in the schema. The description's mention of 'or a sub-account' mirrors the schema without adding syntax, default, or omit behavior guidance, 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 precise verb and resource ('Number of SMS credits (messages) remaining') and clarifies scope ('on the FireText account or a sub-account'). None of the siblings return credit data, so an agent can distinguish it immediately.

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

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

The description describes what the tool returns but gives no explicit when-to-use guidance, no prerequisites, and never names an alternative. Implied usage (check remaining balance) is left entirely 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 only declare readOnlyHint=true, so the description must carry the rest, and it does add real value: the returned fields (mobile, names, messageSent, messageUpdate) and the full status vocabulary (Delivered / Declined / Buffered / Pending with Network / Rejected / Unconfirmed). It does not mention pagination behavior for a report that can return up to 25,000 rows, which is a modest 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 tight sentences: what it returns, how to identify the message, and the vendor endpoint. The identifying information is front-loaded and 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, the description usefully enumerates the returned fields and status values, which is exactly what an agent needs to interpret results. Pagination semantics for the large per-page values are left to the schema, leaving a small gap but nothing critical for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents pp, page, message, reference, and subaccount in detail. The description's 'message id OR the custom reference' phrasing essentially restates what the schema already says ('alternative to message'), adding no new syntax or format information, so the 3 baseline 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 gives a concrete verb and resource ('Per-recipient delivery status of one sent message') and enumerates the exact fields and status values returned. It is clearly distinguishable from siblings like firetext_get_click_report, firetext_get_sent_summary, and firetext_list_sent_messages, which cover different report scopes.

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 tells the agent how to identify the target ('Give the FireText message id OR the custom reference used when sending'), which is genuinely actionable. However, it never states when to prefer this per-message report over siblings such as the aggregate get_sent_summary or get_click_report, so the routing guidance is implicit rather than explicit.

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

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

The readOnlyHint annotation already establishes this as a safe, non-mutating read, so the description's burden is lower. It usefully discloses what the response contains (campaign count, recipient count, credits used), but adds nothing about aggregation basis, timezone of the date range, or rate limits.

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

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

Two very short clauses, front-loaded with the outcome ('Totals...') before the metric list. The trailing 'FireText: /sentreport' endpoint reference is mild implementation detail that does not help an agent choose or invoke the tool.

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 appropriately names the three returned metrics, which is the key information an agent needs. All three parameters are schema-documented, so the only real gap is the absence of sibling differentiation and date-range boundary behavior.

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

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

Schema description coverage is 100%, so from/to formats and the subaccount module caveat are already fully documented. The description only reiterates the date-range concept and adds no format, boundary-inclusivity, or subaccount semantics 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 ('Totals for a date range') and enumerates what is summed: campaigns, recipients, credits used. An agent can tell it produces aggregate figures rather than the per-message listings returned by siblings like list_sent_messages, 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?

There is no when-to-use or when-not-to-use guidance and no routing to the many sibling report tools (get_delivery_report, get_click_report). The date-range phrasing hints at the context, but the agent must infer when the summary is preferred over the detailed reports.

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 added value is the list of returned fields, which is useful given there is no output schema. It does not disclose pagination behavior or result ordering, so it adds only modest 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?

Two short fragments with no filler; the resource statement and returned fields come first. The trailing 'FireText: /keywords.' is minor API trivia rather than agent-facing guidance, but it costs almost nothing.

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 paginated read-only list tool with a fully documented schema and a readOnly annotation, the description supplies the missing piece (what fields come back) and nothing essential is absent. Pagination guidance is already covered by the schema.

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

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

Schema description coverage is 100%, so pp, page and subaccount are fully documented in the schema itself (including the sub-account module caveat). The description adds nothing about parameter semantics, 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 title and description together give a clear verb+resource: list the SMS keywords on the account, and it even enumerates the returned fields (keywordID, number, keyword, reference). It does not explicitly distinguish itself from siblings, but 'keywords' is unique among the report/message/contact tools, so an agent can select it confidently.

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 or when-not-to-use guidance, no mention of prerequisites (e.g. sub-account module), and no alternatives named. The agent must infer that this is simply the keyword-listing operation.

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 signals a safe read operation. The description adds useful behavioral context beyond annotations: it lists returned fields, explains the date format, and discloses the stateful from="last" behavior that returns only new messages since the last call. It omits rate limits, authentication needs, and pagination response shape, but these are less critical for a read-only list tool with full schema coverage.

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

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

The description is front-loaded with the core purpose, then efficiently covers returned fields, key parameter behavior, and the FireText endpoint. Every sentence earns its place and there is no filler.

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

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

With no output schema, the description helpfully enumerates the returned fields, which is important for an agent to understand results. It also covers date format and the special from="last" mode. It could mention ordering or pagination response details, but for a read-only list tool with full schema parameter coverage, it is largely complete.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description restates the YYYY-MM-DD date format and the from="last" semantics, which the schema also covers, and does not add meaning for pp, page, or subaccount. Baseline 3 is appropriate when the schema carries parameter documentation.

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 (inbound SMS received on the account's FireText numbers/keywords). It distinguishes itself from sibling firetext_list_sent_messages by explicitly scoping to received/inbound messages, and it enumerates the returned fields so the agent knows what data to expect.

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 establishes clear context: use this for inbound/received SMS rather than sent or scheduled messages, which are covered by siblings. It does not explicitly name alternatives or when-not conditions, but the scope is clear enough for an agent to route correctly.

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. With no output schema, the parenthetical field list (messageID, queuedOn, scheduledFor, recipientCount, sourceAddress, sendTo, message) does add real return-shape context, but nothing is said about pagination behavior or result volume, which the schema only partially 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?

Very compact: a one-line purpose fragment plus a dense field list and an endpoint tag. It is front-loaded and wastes no words, though the parenthetical field dump is slightly opaque to a reader who does not yet know the return shape.

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, fully-described, no-required-param list tool this is adequate, and listing the returned fields compensates for the absent output schema. It falls short of complete because pagination expectations and sibling routing are left entirely 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 description coverage is 100% and all three parameters (pp, page, subaccount) are documented in the schema itself, so the baseline is 3. The description adds no additional meaning about parameter interaction, defaults, or scoping.

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 phrase 'Messages queued for later sending' identifies the resource and implicitly distinguishes it from sent/received messages, but there is no explicit verb (the reader must infer 'list' from the tool name) and no direct contrast with siblings like firetext_list_sent_messages. The purpose is inferable but not stated as a self-contained action.

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

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

No when-to-use guidance is given. The description never explains how this differs from firetext_list_sent_messages or firetext_list_received_messages, nor when an agent should prefer it. The trailing 'FireText: /scheduledmessages' is an endpoint reference, 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 this a safe read, so the burden is lower. The description adds value by disclosing the shape of the result (messageID, sentOn, sentTo group, recipientCount) and the messageID linkage to other reports, but says nothing about pagination behavior despite the pp/page parameters.

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 terse, front-loaded fragments with essentially no filler; the returned-field list and the messageID tip come first. It is telegraphic rather than wasteful, though the fragmentary style slightly hurts readability.

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

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

With no output schema, the description compensates by enumerating the returned fields and the key messageID, and annotations cover the safety profile. Only pagination and the 'last' start-date behavior are left unaddressed, which is a minor gap for an all-optional, fully-documented schema.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema (pp, to, from with 'last', page, subaccount). The description only restates the YYYY-MM-DD date format and adds nothing about the 'last' keyword or subaccount semantics, 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+resource (list sent messages/campaigns) and enumerates the returned fields, so it is distinguishable from list_received_messages and list_scheduled_messages. It does not explicitly name the sibling it contrasts with, but the scope is unambiguous.

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

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

The line 'The messageID is what the delivery and click reports need' implies a downstream workflow with get_delivery_report/get_click_report, which is useful routing context. However, it never says when to choose this over get_sent_summary or the received/scheduled list siblings, so usage is only implied.

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 the safety profile, and the description adds the concrete payload fields (names, mobile, custom fields, addedOn, unsubscribedOn, reason) plus the backing endpoint. However, it says nothing about pagination behavior despite pp/page params, nor about the 'last' cursor semantics.

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 compact single sentence plus a parenthetical field list and an endpoint reference. It is front-loaded with the resource and free of filler, though the telegraphic fragments read more like notes than prose.

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

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

With no output schema, the description compensates by enumerating the returned fields, and all six input parameters are fully documented in the schema. The only gap is pagination and cursor behavior, which is not addressed.

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 pp, page, from, to, group, and subaccount in detail. The description only echoes the date-range and group concepts with no added syntax or format guidance, so it does not exceed the baseline.

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

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

The description clearly states the resource ('Contacts that opted out') and enumerates the returned fields, so an agent knows this is a read/list operation on unsubscribed contacts. It does not explicitly name sibling alternatives like firetext_unsubscribe_contact, but the read-vs-write distinction is inferable.

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

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

The description notes 'Optional date range and group API id' but frames these as parameters rather than situations. There is no statement of when to reach for this tool versus firetext_get_contact, firetext_subscribe_contact, or firetext_unsubscribe_contact.

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 declare destructiveHint=true; the description adds the cost model (one credit per 160 GSM characters per recipient, unicode costs more), irreversibility ('Cannot be undone'), and a hard recipient cap of 10. This is exactly the behavioral context an agent needs before a money-spending, destructive action, and it is consistent with 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-loaded with the two highest-severity facts ('WRITE, SPENDS MONEY'), then constraints, then the precondition. Dense but every clause carries operative information; nothing is padding.

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

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

Covers cost, limits, irreversibility and preconditions, which is most of what is needed for a mutation tool with only a destructiveHint annotation. It does not indicate what the call returns (no message ID / response shape explained), a minor gap given no output schema exists.

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. The description goes beyond the schema by tying message length and the `unicode` flag to credit consumption, which lets an agent reason about cost implications of parameter choices rather than just syntax.

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 to real phones') with the scope of the operation made explicit. It is unmistakably the only write/send tool among a sibling set of read/report/contact-management tools, so an agent can route to it without ambiguity.

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 strong precondition — 'Only call after the user confirmed the exact text, sender and numbers' — and rules out unsupported workflows ('no groups, templates, scheduling or repeats'). It does not name an alternative sibling, but none exists for this operation, so the guidance is effectively complete for routing.

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 only destructiveHint=true provided, the description adds real value: it flags the call as a WRITE, discloses that no SMS is sent, and warns that update=true overwrites firstname/lastname/custom1-3. It stops short of stating auth requirements or the handling of fields omitted during an update.

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

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

Front-loads the 'WRITE:' marker and the core action, then adds only the constraints an agent needs. Slightly dense/run-on in the middle clause, but every sentence 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 9-parameter mutation tool with no output schema, it covers the essential edge cases (opt-out, no-SMS side effect, overwrite behavior on update). It leaves subaccount semantics and non-update parameter behavior to the schema, which is 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 description coverage is only 44%, so the description must compensate. It clarifies the role of mobile, group and update and gestures at the name/custom fields, but firstname, lastname, custom1-3 and subaccount still lack any description-level meaning. Partial compensation for the coverage gap, landing at the baseline.

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

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

States a specific verb and resource ('adds a contact (by mobile number) to the FireText account') with the dual mode spelled out ('or with update=true refreshes the names/custom fields'). The 'Does not send any SMS' clause cleanly separates it from firetext_send_sms, so an agent can route 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 the conditional use of update=true and states the important exclusion that opted-out contacts cannot be re-added this way. It gives clear context but never names a sibling tool (e.g. unsubscribe_contact) as the alternative path, so it stays just short of explicit when/when-not routing.

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; the description adds substantive context beyond that: the 'WRITE:' classification, the fact that no SMS is sent, and the important consequence that rejoin is only possible via SMS. It does not cover idempotency or behaviour when the contact is unknown, but the key side effects are disclosed.

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

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

Three short sentences, front-loaded with the 'WRITE:' classification and the primary effect, with no filler. The trailing 'FireText: /unsubscribe.' endpoint note is minor but provides API mapping value.

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 3-parameter destructive write with minimal annotations and no output schema, the description covers the critical points: scope default, no SMS sent, and irreversibility without SMS. Only the response shape and not-found behaviour are left unspecified.

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, and the description adds real meaning beyond the schema by clarifying that omitting 'group' unsubscribes from all groups (the schema only says 'only if the account unsubscribes per group'). The mobile and subaccount params remain schema-documented only.

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 (opts out) plus resource (a contact in the FireText account) and the effect (no longer receives group messages). The default scope ('all groups') and the contrast with the sibling firetext_subscribe_contact make the operation unambiguous.

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

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

Gives clear context for use: default is account-wide opt-out, with the group parameter only applying when the account unsubscribes per group. It does not explicitly name firetext_subscribe_contact as the inverse or state exclusions, but the conditions for using the default vs per-group mode are spelled out.

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