Messente MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is already covered. The description adds the useful nuance that re-adding an existing number is harmless and names the underlying endpoint, but says nothing about auth requirements, rate limits, or error 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?

Front-loaded with a 'WRITE:' signal and tightly written, with no filler. The trailing 'Messente: POST /phonebook/blacklist' endpoint reference is low-value for an agent but short enough not to hurt 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?

For a single-parameter write tool with full schema coverage and annotations carrying the safety profile, the description covers what the tool does and its effect adequately. No output schema is needed for a simple blacklist operation, though a note on confirming success would round it out.

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

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

Schema description coverage is 100% and the phone_number parameter already documents E.164 format with an example and a regex pattern. The description adds only the cardinality note ('one phone number', i.e. not a batch call), which is marginal beyond the schema.

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

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

The description states a specific verb+resource ('add one phone number to the account's blacklist') plus the downstream effect ('Messente will no longer send messages to it'), which lets an agent distinguish it from messente_check_blacklist and messente_list_blacklist 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?

The description conveys the purpose and effect of the write, so usage is implied, but it never states when to prefer this over the sibling tools (check_blacklist, list_blacklist) or any prerequisites/preconditions for blacklisting.

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 the outcome semantics (found = blacklisted, 404 = not), which is genuinely useful context beyond the structured fields, though it does not cover auth requirements or rate limits.

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

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

Two tight sentences. The purpose is front-loaded and the endpoint/outcome detail follows without 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?

For a single-parameter read tool with no output schema and annotations covering safety, the description supplies the essential outcome semantics. It lacks explicit usage-vs-alternative guidance, which holds it short of 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 the E.164 format and the phone parameter are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already says, so 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?

Specific verb+resource ('Check whether one phone number is on the account's blacklist') and clearly distinguished from siblings add_to_blacklist and list_blacklist. The scope note 'one phone number' contrasts with the listing sibling.

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

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

The behavior of the underlying API (found vs 404) is disclosed, which implicitly signals use context, but there is no explicit when-to-use vs alternatives like list_blacklist or add_to_blacklist. Adequate but with a clear gap.

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 openWorldHint=true, covering safety and external scope. The description adds that this is a legacy API and provides the endpoint URL, which is useful context but does not disclose auth requirements, rate limits, or deprecation status.

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

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

Two sentences, front-loaded with core purpose followed by API endpoint detail. Every sentence earns its place with no redundancy.

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

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

For a zero-parameter, read-only tool with annotations covering safety and open-world behavior, the description is complete: it specifies the returned value (SMS credit balance in EUR) and the underlying API endpoint.

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

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

The tool takes zero parameters, so per the rubric baseline is 4. The description adds no parameter meaning because none exist, but no gaps are present.

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 (Messente account's remaining SMS credit balance) with units (EUR). Clearly distinguishes from siblings like get_prices and get_statistics, which serve different purposes.

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 explicit guidance on when to use this tool versus alternatives such as get_statistics or get_prices. The description merely states what it does, leaving usage context 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 and openWorldHint, so safety is covered. The description goes beyond them by disclosing the return payload (per-message status codes such as DELIVRD/UNDELIV/FAILED, error, price charged) and a real operational constraint about high-volume polling, which is exactly the kind of non-obvious behavior an agent needs.

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 sentence covering purpose, identifier source, return fields, and the polling caveat, followed by the raw endpoint. Zero 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?

With no output schema, the description compensates by enumerating the returned fields (status, error, price). For a single-parameter read tool with read-only annotations, nothing needed to invoke or interpret 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% and there is a single required parameter, so the baseline is 3. The description adds provenance (the id comes from messente_send_sms) but no format, length, or edge-case detail beyond what the schema already states.

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 (delivery report of a sent message) keyed by omnimessage_id, and explicitly names the sibling that produces that id (messente_send_sms). An agent can distinguish this from messente_get_statistics or messente_get_prices without opening another 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 clear context for use (after sending, via the id returned by messente_send_sms) and an explicit usage caution: Messente asks not to poll this for every message at scale. It stops short of naming a preferred alternative for bulk status (e.g., statistics or webhooks), so it is strong but not a full when/when-not/alternative 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: results are per SMS part and per mobile network (not a single blended price), and the backing call is a legacy GET /prices.

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 sentence, front-loaded with the verb and resource, then the estimation use case, then the API endpoint. Zero filler and nothing an agent must skip past to get the point.

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

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

For a single-parameter, read-only pricing lookup with no output schema, the description tells the agent what comes back (per SMS part, per mobile network) and why it matters. Minor gaps remain around currency and whether partial prices are returned for networks without coverage, but nothing blocking.

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 'country' parameter is fully documented in the schema (ISO 3166-1 alpha-2, with examples EE/GB). The description only restates that pricing is for 'one country', adding no syntax or constraint detail beyond the schema. 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 ('Get this account's price per SMS part') and pins down the exact granularity (one country, per mobile network), which separates it from siblings like get_balance or get_statistics. The parenthetical cost-estimation framing makes the intent unmistakable.

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

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

Explicitly routes the agent: 'use it to estimate what messente_send_sms will cost', naming the sibling that consumes this data. It lacks a negative case (e.g., when to call get_balance or lookup_numbers instead), so it stops 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's 'a read-only report' largely restates structured data. It does add one genuinely useful nuance — that this read operation is exposed as POST /statistics/reports — which prevents an agent from assuming the HTTP verb implies a write. Beyond that, no rate limits, permission requirements, or cost/aggregation caveats 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?

One front-loaded sentence carries the purpose, with a short parenthetical noting the upstream endpoint. Appropriately sized with no filler, though the endpoint note is marginally redundant with the read-only annotation.

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

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

With no output schema, the description correctly names what is returned (total messages and total price, broken down per country) plus the optional type filter. That covers the essentials for a read-only report tool; only the return shape/units of 'price' are left unstated.

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

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

Schema description coverage is 100%, so the schema already documents start_date, end_date, and message_types with formats and enum values. The description only confirms the optionality of message_types and the date-range scope, adding little beyond the structured fields — 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+resource ('Get total messages and total price per country') with aggregation granularity and scope (date range, optional message types), which cleanly separates it from siblings like get_prices and get_delivery_status. It never names an alternative sibling explicitly, but the resource 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?

There is no when-to-use guidance, no exclusions, and no mention of the closest sibling (messente_get_prices). The only usage-ish signal is that message_types is optional, which is really parameter information rather than routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the return contract ('total count and at most `limit` numbers') and clarifies the domain meaning of blacklisted entries, but says nothing about pagination limits beyond the schema, auth requirements, or ordering.

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-load what the tool returns before the domain gloss and API mapping. Every element earns its place except the trailing 'Messente: GET /phonebook/blacklist', which is marginal for an agent that already has the tool name.

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 stating the return shape (count plus up to `limit` numbers), and the two paging parameters are fully covered in the schema. Adequate for a low-complexity, read-only list tool; only ordering and paging boundary behavior remain unstated.

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

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

Schema description coverage is 100%, so both limit and offset are already documented in the schema; this is the baseline-3 case. The description only restates that `limit` caps the returned numbers and adds no format, ordering, or inter-parameter semantics 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?

States a specific verb and resource ('List the phone numbers on the account's blacklist') and parenthetically defines what the blacklist means ('numbers Messente will not send to'). It implicitly distinguishes itself from messente_check_blacklist (single-number check) by describing a full list, but never names that sibling to make the split explicit.

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: you call this to enumerate the account's blacklist, and limit/offset imply paging through a long list. There is no explicit when-to-use guidance, no statement of when to prefer messente_check_blacklist instead, and no prerequisites or exclusions.

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

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

Annotations declare readOnlyHint=false without saying why; the description fills that gap by disclosing per-lookup credit charges (EUR 0.002) and the required account service. It also documents the 10-numbers-per-call ceiling and the underlying endpoint. It does not explain why the tool is flagged non-read-only (balance mutation) in so many words, keeping this 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, front-loaded sentences: purpose first, then cost/prerequisite constraints, then the call limit. Every element is useful, though the trailing 'Messente: POST /hlr/sync.' endpoint note is the one item an agent does not strictly need to 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 compensates by naming the data points returned (valid, ported, roaming, network) plus cost and volume constraints. It stops short of describing response shape or failure behavior for invalid numbers, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100% and there is a single parameter, so the E.164 pattern and min/max items are already fully documented structurally. The description restates the 10-number limit but adds no format or syntax detail beyond the schema, making 3 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 and then enumerates exactly what the lookup returns: validity, portability, roaming status, and network. This is far more specific than its siblings (blacklist, balance, SMS, statistics) and lets an agent 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?

It gives a real prerequisite (the Number Lookup service must be enabled, with a monthly fee) and a cost cue that steers usage decisions, but it never states when NOT to use it or points to an alternative sibling for related needs. Usage context is implied through cost and enablement rather than explicitly framed.

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 destructive/non-idempotent/non-readonly, but the description adds cost consequences (per-SMS-part billing, account credit spent), irreversibility ('Not undoable'), a legal/compliance constraint against unsolicited messaging, and the underlying API call shape. This is substantial context beyond the structured hints.

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 'WRITE' flag and the money cost, which is what an agent most needs. The remaining content is dense and occasionally overloaded with punctuation, but nearly every clause carries a distinct constraint 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?

Covers cost, limits, compliance, and irreversibility for a mutation tool with no output schema. The one gap is that it never says what comes back (e.g., a message ID usable with messente_get_delivery_status), which would help chaining, but otherwise nothing essential is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantic constraints on `to` ('one message per recipient, never to a list') and clarifies that the cap is per call, not per message broadcast. Sender default behavior is left to the schema.

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

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

States a specific verb and resource ('SENDS REAL SMS TEXT MESSAGES') with explicit scope ('SMS only', one message per recipient). An agent can distinguish this immediately from siblings like messente_get_prices, messente_check_blacklist, or messente_get_delivery_status.

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 explicit when-to-use conditions (send to opted-in recipients only, max 10 recipients, no lists) and routes the agent to the pricing sibling for pre-send cost estimation. Compliance boundaries are stated as prohibitions, not hints.

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