smsmode MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description adds that it is a WRITE, that the action cannot be undone, and that the server enforces the SCHEDULED-status precondition by refusing already-sent messages. That enforced-refusal behavior is genuine context beyond the annotation, though no auth or rate-limit details are given.

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?

Dense but front-loaded: the WRITE marker and core action lead, preconditions follow, the irreversibility warning is explicit, and the endpoint tag closes. 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 one-parameter, no-output-schema cancellation tool, the description covers the precondition, the irreversibility, and the failure mode. It does not state what the call returns, but with no output schema and a DELETE-style operation that gap is slight.

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 message_id field already documents its source (smsmode_send_sms or smsmode_list_messages), so the description need not repeat format details. It adds no parameter meaning beyond the schema, which is the expected baseline 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?

States a specific verb (cancels) and resource (ONE scheduled message), plus the precise status precondition (SCHEDULED, sent with send_at) that distinguishes it from any read/list sibling. An agent can select it 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 a clear when-to-use condition (message still scheduled via send_at) and a when-not condition (smsmode refuses messages already sent). It does not name a sibling alternative, but no other sibling performs cancellation, so the omission is minor.

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; the description adds real behavioral context beyond that, notably that a negative amount means owed on a POST_PAY account and that an administrator key may see sub-organisations. It omits return format details, but the added semantics are substantive.

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

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

One dense, front-loaded sentence that leads with the resource, plus the endpoint path at the end. Every clause carries meaning, though the parenthetical and long enumeration make it slightly packed.

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 and no parameters, the description carries the full burden of describing return values, and it does so field by field (amount, currency, payment type, state, consumption, limit). It also supplies the endpoint path, leaving nothing an agent 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter syntax and instead spends its words on outputs, which is the right choice 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?

States a specific verb and resource ('credit balance of the connected smsmode account') and enumerates exactly what is returned: amount, currency, payment type, state, monthly consumption and limit. This clearly separates it from siblings like get_consumption or get_organisation.

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?

'Good first call; check it before sending SMS' gives explicit timing and a concrete precondition tied to a sibling action. It does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's main added value is the explicit GET endpoint and the enumeration of returned fields. It does not disclose error behavior (e.g. 404 for a bad id) or any auth/rate-limit characteristics, so with annotations carrying the safety profile this sits at a solid but unremarkable 3.

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 with zero filler; the payload summary is front-loaded and the sibling routing plus endpoint form a useful trailing clause. Every sentence earns its place.

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

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

With no output schema, the description compensates by enumerating the returned fields, and with one fully-documented parameter there is little else an agent needs. Minor gaps remain around failure modes and pagination-free single-object retrieval, but nothing essential to 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?

Schema coverage is 100% and the single campaign_id parameter is fully documented in the schema, including its UUID pattern and its origin in smsmode_list_campaigns. The description adds no format or sourcing detail beyond that, so the schema does the heavy lifting and 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 ('Get an SMS campaign') and enumerates exactly what the caller receives: state, period, recipients count, text, price and per-status delivery counts. This clearly separates it from smsmode_list_campaigns (many campaigns) and smsmode_list_messages (individual messages), so an agent can pick it 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?

Explicitly routes the agent to smsmode_list_messages with campaign_id when individual messages are wanted, which is the key branch point. It stops short of a full when/when-not statement (e.g. no guidance on what happens for an unknown or scheduled campaign id), but the context is clear.

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 non-mutating read, so the description only needs to add context. It adds the scope of returned data (type, flow, sender IDs, limits, consumption), which is useful given there is no output schema, but it says nothing about permissions, freshness, or not-found behavior.

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

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

Two compact sentences, with the payload summary front-loaded ahead of the endpoint literal. The endpoint string adds little for an agent but 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 single-parameter read tool with no output schema, the field enumeration plus the read-only annotation give an agent enough to call it and anticipate the response shape. Error and empty-result behavior 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%: channel_id is documented with a UUID pattern and a hint to obtain it from smsmode_list_channels. The description's 'channels/{id}' merely restates the schema, adding no new syntax or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Details of one channel') and enumerates the fields returned, so an agent knows this is the single-channel counterpart to smsmode_list_channels. It stops short of naming the sibling explicitly, so differentiation is implied 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 phrase 'one channel' implicitly tells the agent this is for a single known channel rather than a listing, but there is no explicit when-to-use, no exclusion, and no named alternative. Usage must be inferred from context.

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 is already declared by annotations, but the description adds genuine behavioral value by describing the shape of the returned payload (breakdown by mcc/mccMnc, quantity and price per sub-item, optional delivery statuses) and the underlying endpoint. This compensates for the absence of an output schema. It does not cover error/permission behavior, 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?

A single front-loaded sentence establishes what the record contains, followed by the endpoint path. Nothing is padded, though the raw REST path contributes little for an agent selecting an MCP 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 and only readOnlyHint in the annotations, the description carries the burden of describing the return payload, and it does so adequately via the breakdown/sub-item/status details. Missing pieces such as error behavior or empty-result handling keep it from a 5.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the group_by enum values and the detail_statuses flag. The description mirrors that information ('by country (mcc) or network (mccMnc)', 'optionally with delivery statuses') without adding syntax or format detail beyond it, 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?

The description gives a specific verb+resource ('One consumption record') and further scopes it by naming the breakdown dimension and per-sub-item fields. It contrasts implicitly with smsmode_list_consumptions via the singular 'record', but never names the sibling, so differentiation is inferred rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use guidance in the description. The usage is inferable from the singular scope (fetch one consumption by id), and the schema notes the id comes from smsmode_list_consumptions, but the description itself does not route the agent among alternatives.

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

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

readOnlyHint=true already establishes this as a safe read, so the burden is lower. The description goes beyond that by disclosing exactly what comes back (delivery status, delivery date, recipient network, text, parts, price), which is genuinely useful given there is no output schema.

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

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

One tight sentence of return contents followed by the endpoint path; no filler and the resource is front-loaded. Nothing could be cut 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?

For a two-parameter read with no output schema, the enumerated return fields cover the main gap, and readOnlyHint covers safety. Error behavior (e.g. how a missing/invalid id is reported) is the only notable omission.

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 message_id and channel_id are fully documented in the schema, including where the id comes from. The description adds no parameter-level syntax or constraints, 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 (retrieving one message) and enumerates the returned fields, which distinguishes it from the plural smsmode_list_messages. It stops short of explicitly naming the sibling it is not, so it lands just under the top band.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing against smsmode_list_messages or smsmode_get_campaign. The '{id}' path implies a single-record fetch but nothing in the text tells the agent when this is the right call versus a list.

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 useful context about what fields come back (balance, monthly limit, consumption), but says nothing about permissions, error behavior, or whether consumption data is scoped to a period.

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 that leads with scope and then lists returned fields, followed by the REST endpoint. Tight and readable; the raw endpoint string is mildly redundant but conventional and non-obstructive.

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 and does summarize the returned fields, giving the agent enough to know what it will receive. Missing only usage context and any indication of error/missing-organisation 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 coverage is 100%: the single organisation_id parameter is documented with a UUID pattern and its provenance (obtained from smsmode_get_balance). The description adds nothing beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Full details of one organisation') and enumerates the content returned: contacts, addresses, company info, balance, monthly limit, consumption. The resource is naturally distinct from siblings like get_balance or get_campaign, though the description never names an alternative to reinforce the 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as smsmode_get_balance for a quick balance check. The only routing hint ('from smsmode_get_balance') lives in the schema parameter description, not the tool 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?

The readOnlyHint annotation already covers the safety profile, so the 'Read only' sentence is partly redundant, but the description adds genuine context by describing what the response carries (quantity, price, per-status delivery counts) in the absence of any output schema. It also scopes the meaning of 'campaign' as a grouped send. It does not mention rate limits or ordering, which keeps 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 short, front-loaded sentences with no filler; the resource and its contents lead, followed by the read-only caveat and the endpoint. The telegraphic noun-phrase opening is compact but slightly clipped compared to a full verb-phrase statement.

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

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

For a 7-parameter, zero-required listing tool with no output schema, the description covers purpose, returned fields, and safety context, while the schema fully documents filters, pagination, and defaults. Nothing essential is missing, though a note on result ordering or the relationship to smsmode_get_campaign would have closed the last 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 every parameter (page, status, dates, page_size, channel_id, ref_client) is already documented, including the pagination hint about next_page and the default date window. The description adds no format or syntax detail beyond restating the status enum values, so the baseline 3 applies.

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

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

The description names the specific resource ('SMS campaigns (grouped sends)') and clarifies the domain term, then enumerates what each record contains (status values, quantity, price, delivery counts). It is distinguishable from smsmode_get_campaign (plural listing vs. single fetch) and from smsmode_list_messages, though it never explicitly contrasts itself with those siblings. The only weakness is that it is a noun phrase rather than containing its own verb.

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: 'Read only: this server does not send campaigns' signals that smsmode_send_sms is a different concern, but there is no explicit when-to-use guidance or routing to smsmode_get_campaign for a single campaign. An agent can infer the listing intent from the name and schema, but nothing tells it when this tool is preferred over its siblings.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds useful return-content context (sender, limits, consumption) and identifies the underlying GET endpoint, but discloses nothing about pagination behavior, result volume, or ordering beyond what the schema's page/page_size fields imply.

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 purpose and return content, followed by a short endpoint citation. Little waste, though the endpoint reference adds marginal value for an agent choosing a 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?

No output schema exists, yet the description names the returned fields (default sender, daily and monthly limits, consumption) and the schema itself covers paging via page/page_size and next_page. For a read-only list tool with zero required parameters, an agent has enough 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 every parameter (including the flow and type enums) is already documented in the schema. The description restates the flow and type values without adding filtering semantics, format, or interaction rules, so it matches the baseline for a fully-covered schema.

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

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

States a specific verb and resource ('List messaging channels') plus the type and flow dimensions and the fields returned (default sender, daily/monthly limits, consumption), so an agent knows exactly what it gets back. It does not, however, differentiate itself from siblings such as get_channel or list_consumptions, whose content overlaps with the consumption data mentioned here.

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 'A channel id is needed to scope messages or consumption to one channel' implies the practical reason to call this tool (obtaining a channel id), but it never explicitly says when to use this versus get_channel or list_consumptions, and gives no exclusions or prerequisites.

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

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

With readOnlyHint=true already declaring a safe read, the description still adds real value: the data returned (counts plus price amount and currency, per month/day), the default time window, and optional channel narrowing. It stops short of covering pagination behavior or auth/rate-limit constraints, so not 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 compact sentences, front-loaded with the most decision-relevant fact (what data comes back and at what granularity). The default restatement mildly duplicates schema defaults, keeping it just under maximum efficiency.

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?

Nine all-optional parameters at full schema coverage plus a clear statement of the returned metrics and default window means an agent has everything needed to call it; no output schema exists, and the description still summarizes return content 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% and enums document period_type, channel_type and flow, so the baseline is 3. The description adds the framing 'optionally for one channel' and restates the default monthly/last-3-months behavior that the schema already encodes per-parameter, so it adds little beyond the structured data.

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

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

States a specific verb/resource ('Sent-message counts and money spent per month or per day'), the returned fields (price amount and currency), the granularity, and the underlying endpoint. An agent can distinguish it from the singular smsmode_get_consumption sibling by the plural list 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?

Usage is implied through the stated defaults ('monthly, the last 3 months') and optional channel scoping, which tells an agent this is the aggregate-reporting entry point. However, it never says when to use this vs smsmode_get_consumption or when to reach for a different granularity, so no explicit routing guidance is 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?

With only readOnlyHint available, the description carries behavioral weight and delivers: the default 10-day window, the full status vocabulary including status.detail, MT/MO semantics, the pagination protocol (pass next_page as page), and the underlying GET /sms/v1/messages endpoint. It does not disclose result-count totals or behavior when the window exceeds 10 days, which keeps 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-loads the return content, then defaults, then filters, then pagination and endpoint – a logical order with no filler sentences. The opening sentence is dense with parenthetical statuses but every clause carries information an agent needs.

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

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

No output schema exists, yet the description already enumerates the returned fields and the delivery-status states, and all 11 optional parameters are documented in the schema with 100% coverage. Gaps are minor: no error/empty-result behavior and no guidance on large window handling.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose adds semantics beyond the schema: statuses returned, direction MT = sent vs MO = replies received, and the next_page-as-page paging contract. It doesn't restate per-parameter constraints (max lengths, UUID patterns) but meaningfully clarifies the filter vocabulary.

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 ('messages') and immediately enumerates the returned fields (delivery status, recipient, sender, text, parts, price), which distinguishes it from the singular smsmode_get_message sibling. The added detail that status.detail names the failure cause shows the tool's output shape rather than restating 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?

Gives real operating context: default window of the last 10 days, how to filter by direction/recipient/ref/channel/campaign, and that the result is paged. It stops short of naming smsmode_get_message as the single-message alternative or stating when filtering is preferable, so the routing is implied 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?

Annotations only declare readOnlyHint=true, and the description adds meaningful context beyond that: a subscription prerequisite, a geographic limitation, and the specific 403 failure mode. It also enumerates the returned fields, which matters because no output schema exists. Rate limits or latency behavior are not covered, 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?

Two dense sentences: the first front-loads the return value, the second carries the eligibility constraints, and the endpoint path is appended as a compact technical reference. 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 no output schema, the description covers what is returned, who may call it, and the main failure condition. It is nearly complete; only secondary details such as error payload shape for non-403 failures or any rate limiting are absent.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema (international format, length bounds), so the baseline is 3. The description only echoes the number via the {msisdn} path placeholder, adding no format or validation detail beyond what the schema already 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?

The description names the resource (a phone number) and the exact payload returned (country, mcc/mnc, operator), so an agent knows precisely what this tool produces. No sibling tool performs a lookup, so it is unambiguously distinct from the get_/list_/send_ family.

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 clear eligibility constraints: premium smsmode subscription required, and only French numbers are supported (403 otherwise). This tells the agent when the call will fail, though there is no alternative tool to route to and no positive 'use this when' framing beyond the implicit lookup use case.

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, but the description discloses far more: it spends credit, costs per SMS part by encoding, can partly fail ('failures lists the refused numbers, which are not charged'), is never retried, and returns message ids/status. This is rich behavioral 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-loaded with the operator-relevant signals ('WRITE, SPENDS CREDIT') and every clause carries information (cost, failure mode, retry policy, limits). It is a dense wall of text with parentheticals, slightly heavy for a single sentence, but no waste.

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, yet the description explains the accept reply (message id and status, price maybe later), partial-failure semantics, and cost, and routes to smsmode_get_balance and smsmode_list_messages. An agent has everything needed to invoke and recover 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema - why encoding matters for cost ('GSM7: 160 characters for 1 part...'), that send_at schedules rather than sends now, and that stop is legally required for French marketing. It reinforces rather than merely repeats the schema.

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

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

States a specific verb and resource (sends one SMS text to 1-10 recipients) plus the scope constraint (batch of unit messages, no campaigns or lists). An agent can immediately distinguish this from reading siblings like smsmode_list_messages or smsmode_get_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?

Explicit prerequisites ('Check smsmode_get_balance first'), exclusions ('no campaigns or lists'), and a named alternative with its trigger ('after a timeout or error, check smsmode_list_messages (ref_client) before sending again'). Nothing is left to inference.

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