Trumpia MCP by usefulapi

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

Adds value beyond annotations: consent/legal requirements, potential API contract submission, and a returns-request_id + async follow-up model. One mild tension: the described endpoint 'PUT /subscription' implies idempotency while idempotentHint=false, which could mislead on retry 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?

Dense and front-loaded with the WRITE marker and core action first, then constraints, then return behavior. Every sentence carries information, though the run-on nature of the consent clause is slightly heavy.

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?

Without an output schema, the description still explains the return (request_id) and the follow-up tool, plus consent gating. Adequate for a mutation tool with rich annotations already covering safety hints.

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% (baseline 3), and the description adds the key constraint that each contact needs a mobile, email, or landline — a logical requirement not encoded in the schema's item properties. It also notes list names are comma-separated and must pre-exist.

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 (add) and resource (contacts to distribution lists), with the write nature flagged up front. Distinguishes itself from siblings like trumpia_update_subscription and trumpia_get_subscription by being the creation path.

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 preconditions: lists must already exist, each contact needs a valid identifier, and only consented contacts should be added (TCPA/CAN-SPAM/CTIA). It routes the agent to trumpia_get_request_report for async status, but doesn't explicitly contrast with trumpia_update_subscription for existing contacts.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior: the no-op outcome for already-sent messages and the underlying DELETE endpoint. It stops short of noting failure behavior for an unknown id, so not a full 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 clauses, front-loaded with the WRITE marker and the qualifying condition before the low-priority endpoint detail. Every sentence earns its place with no filler.

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

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

For a one-parameter mutation with no output schema, the description covers eligibility, no-op behavior, and the discovery path. It omits what the caller receives on success versus an invalid/already-sent id, which is a minor residual 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?

With a single parameter at 100% schema description coverage, the schema already carries the meaning ('Scheduled message id.'). The description only echoes it via the DELETE path template and adds no format or constraint detail beyond the schema's numeric pattern.

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 (cancel) and resource (a scheduled, unsent message) and explicitly scopes what qualifies. The reference to trumpia_list_scheduled_messages lets an agent distinguish this from the listing sibling without opening either schema.

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

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

Gives an explicit when ('a message that is scheduled and has not been sent yet') and an explicit when-not ('Does nothing for a message already sent'), plus names the sibling used to discover candidate messages. Nothing about tool selection 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.

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered; the description adds valuable context beyond that: it returns request_id and list_id, and it notes the regulatory disclosure requirement for frequency/description. It does not detail failure behavior or whether a duplicate name errors out.

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 operation class and resource, then terse statements about return values and naming constraints. Each sentence carries information, though the telegraphic style leaves a couple of ideas implicit.

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 discloses the return payload (request_id, list_id). Combined with the rich input schema and the destructive/annotations, an agent has enough to invoke it correctly; only error/duplicate handling is 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 all four parameters are already documented in the schema, giving a baseline of 3. The description reinforces the disclosure intent behind frequency and description and the character restriction on list_name, but adds no syntax or format detail the schema lacks.

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 ('create a distribution list') and distinguishes itself from siblings like trumpia_get_list, trumpia_list_lists, and trumpia_update_list. The 'WRITE:' prefix signals the operation class 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?

Implies usage by labeling it 'WRITE: create', but never states when to use this versus trumpia_update_list or trumpia_add_subscriptions, nor any prerequisites. Usage context is only inferable from the name.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds only the resource scope (domestic vs international credits) and the underlying endpoint, with no mention of caching, rate limits, or staleness of the balance figure.

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

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

Two short sentences, front-loaded with the resource scope, with no filler. The trailing 'GET /balance/credit' is mildly redundant against the tool name but does map the call to the underlying API.

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 parameters and no output schema, the description is nearly sufficient: it tells the agent this returns remaining domestic and international text credit counts. Minor gaps remain around units/currency of credits and whether the read is account-wide, but nothing critical to invoking the tool is missing.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The endpoint path reinforces that no arguments are needed.

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

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

The description names a specific resource and scope: the account's remaining domestic and international text credits. An agent knows exactly what is returned and cannot confuse it with any sibling, none of which deal with billing/credits. The verb is only implied by the tool name and endpoint path rather than stated outright.

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 call this tool, no prerequisites (e.g. auth/account scope), and no alternatives mentioned. The context of 'check balance before sending' would be useful given the sibling send_message/send_sms tools, but it 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful detail beyond that: the exact payload an agent gets back (type, allowed values, max length, required flag, mail-merge text) plus the underlying REST route. That return-shape disclosure matters because 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?

A single front-loaded sentence listing the returned attributes, followed by the exact endpoint. No filler; every clause earns its place.

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

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

With no output schema, the description usefully compensates by enumerating the returned fields, and annotations carry the safety profile. Minor gaps remain around error/not-found behavior and the relationship to the list sibling.

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% for the single customdata_id parameter, so the schema already carries the semantics. The description only echoes the id's role via the endpoint template and adds no format or constraint detail beyond the schema's pattern.

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

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

Names the specific resource (one custom data field) and enumerates exactly what it exposes: type, options, required flag, mail-merge text. It's clear what the tool returns. However, it never contrasts itself with the sibling trumpia_list_custom_fields, so sibling differentiation is left implicit.

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 or when-not guidance. The obvious alternative, trumpia_list_custom_fields for enumerating all fields, is not mentioned, nor is any prerequisite (e.g., needing a known customdata_id) stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and the nature of the returned payload, which is genuinely useful, but says nothing about permissions, error cases, or pagination.

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

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

Two short sentences with the payload description front-loaded and the endpoint tacked on. Efficient, though the trailing 'GET /keyword/{keyword_id}' largely repeats information already carried by 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?

A read-only single-resource getter with one fully documented parameter and no output schema; the description compensates for the missing output schema by naming the returned fields. Nothing essential to invoking it correctly is absent, though the return shape is only partially sketched.

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 keyword_id parameter is fully documented in the schema, including its source tool. The description adds only the /keyword/{keyword_id} path template, which restates the schema rather than extending it, 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 resource and scope: a single mobile keyword retrieved 'in detail', with the fields surfaced (auto-response message, code, alternative messages). This clearly separates it from the sibling trumpia_list_keywords by singularity, though it never names that 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?

The phrase 'one ... in detail' implies retrieval-by-id versus the list tool, but no explicit when-to-use, when-not, or alternative is given. The schema's pointer to trumpia_list_keywords as the id source is the only routing hint.

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 the safe read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds meaningful context by disclosing what the call returns (display name, description, message frequency, subscription/mobile/email counts) and the underlying endpoint, which matters 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?

A single front-loaded sentence plus endpoint reference, with no wasted text. Slightly terse but appropriately sized for a one-parameter read 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?

For a simple read tool with one fully-documented parameter and annotations covering safety, the definition is largely complete; its field enumeration compensates for the absent output schema. Auth/error behavior is not covered but is not essential here.

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

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

Schema description coverage is 100% and the list_id parameter is already documented with its source (trumpia_list_lists), so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema provides.

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

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

The definition names the specific resource (a single distribution list) and enumerates the returned fields, which implicitly distinguishes it from the sibling trumpia_list_lists. The verb itself is only carried by the name/title ('Get'), not the description text, so it falls just short of an explicit verb+resource statement.

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 phrasing 'One distribution list' implies this fetches a single known list rather than enumerating them, which weakly implies the list_lists alternative, but no explicit when-to-use or when-not 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?

Annotations already declare readOnly, non-destructive and open-world behavior, so the safety profile is covered. The description adds return-content knowledge the annotations cannot: possible status values (sent / scheduled / canceled) and the credit-usage and per-channel failure figures. It omits nothing an agent needs before calling.

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

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

A single dense sentence plus an endpoint fragment, with the resource named first and the returned fields enumerated afterward. Every clause is informative, though the endpoint path is slightly redundant for an agent that only needs the tool call.

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 single-parameter tool with no output schema, the description compensates by enumerating the returned fields and status values. Safety and parameter origin are covered; only pagination or freshness behavior is left unstated, 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?

Only one parameter exists and the schema documents it at 100% coverage with the pattern and origin ('Message id returned by trumpia_send_message'). The description restates that origin but adds no format or syntax 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 (delivery statistics of a message), and enumerates the exact payload: status, totals, sent/failed counts per channel, credits used. It even cites the endpoint GET /message/{message_id}, letting an agent differentiate it from siblings like trumpia_get_request_report or trumpia_list_scheduled_messages.

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 'of a message sent with trumpia_send_message' establishes the precondition and the source of the required message_id, which is meaningful routing context. It does not, however, state exclusions or name an alternative to use when this tool is the wrong choice.

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?

Beyond the readOnly/openWorld annotations, the description explains that writes are processed asynchronously and that the reply may contain the final result, an in-progress status, or a failure. This adds meaningful behavioral context for a status-report tool.

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 tool's purpose, then explains the required input and expected reply states in two efficient sentences. The endpoint reference is brief and useful rather than wasteful.

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

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

With one required parameter, read-only annotations, and no output schema, the description provides enough completeness by explaining the async context and the possible reply outcomes. An agent can call it correctly without additional clarification.

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 schema already has 100% description coverage for the single request_id parameter, and the description largely restates that it comes from a write reply. It adds modest context by noting which write tool returned it, but does not add syntax or validation details 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 operation and resource: retrieving the outcome of an earlier asynchronous write request. It clearly distinguishes this request-report tool from sibling get/list tools by tying it to write requests and request_id values.

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 clearly says to use the tool after a write request by passing the request_id returned by the write tool. However, it does not explicitly name alternatives or when-not-to-use conditions, leaving the usage context strong but not fully exhaustive.

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

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

Annotations already establish readOnly=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds meaningful context beyond them: the call returns personal data and includes verified flags and custom data, which matters for handling and downstream use. It does not discuss error behavior for a missing id, 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?

A single compact sentence front-loads the resource and contents, and every clause (fields, PII warning, endpoint) carries information. The endpoint path is slightly redundant with the tool name but serves as a mapping aid.

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

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

For a one-parameter read with no output schema, listing the returned fields plus the PII warning gives an agent enough to call it and interpret the result. Not mentioning not-found behavior or id source failures is a minor remaining gap.

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

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

Schema coverage is 100%, with the lone subscription_id documented including its numeric pattern and origin. The description adds nothing beyond that (the endpoint template merely mirrors the parameter), 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?

Names a specific verb and resource ('One subscription') and enumerates the fields returned, which distinguishes it from trumpia_list_subscriptions and trumpia_search_subscriptions by scope. It never explicitly names those siblings as alternatives, so the differentiation is implicit 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?

Retrieval is implied by 'One subscription... /subscription/{subscription_id}', and the schema notes the id comes 'from a list or search', hinting at the workflow. But there is no explicit when-to-use statement, no exclusion, and no pointer to a named alternative tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only that results contain id and name plus the underlying endpoint (GET /customdata) — modest extra context, no pagination or ordering detail.

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, front-loaded with the payload description and ending with the endpoint. Nothing is padded, though the endpoint fragment adds little for an agent that only sees the tool interface.

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 parameters, full annotation coverage, and no output schema, the description is nearly self-sufficient — it even discloses the returned fields (id and name). Only the ordering/pagination behavior of the listing is 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?

The tool takes zero parameters, so the schema carries no semantics to supplement and the baseline is 4. The bracket '(id and name)' does slightly describe the return shape, but that concerns output rather than parameters.

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 (custom data fields) and scope ('All'), with a concrete payoff ('used as mail-merge values'). It doesn't explicitly distinguish itself from the singular sibling trumpia_get_custom_field, but the 'All' framing makes the listing role clear.

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 through the phrase 'used as mail-merge values'; there is no explicit when-to-use, when-not, or pointer to trumpia_get_custom_field for single lookups. Adequate but leaves the agent to infer the 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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming the GET /email/sender endpoint, explaining that Trumpia returns a bare array which is wrapped, and giving the returned sender object shape. It omits auth or rate-limit details, but those are less critical for this simple read operation.

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 delivers the purpose, response shape, wrapping caveat, and endpoint. Every element earns its place with 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?

No output schema exists, so the description must explain return values; it does so by listing senders with sender_id, address, and default and by noting the bare-array wrapping. With annotations covering safety and no input parameters to explain, this is complete for the tool.

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

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

There are zero input parameters, so there is no parameter semantics for the description to compensate for; the baseline is 4. The description correctly does not invent parameters.

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

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

The description uses a specific verb and resource: registered email sender addresses, clarified as the From / Reply-To addresses allowed for email messages. It does not explicitly compare against siblings, but none of the listed siblings appear to cover email senders, so the purpose remains clear.

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

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

The description implies the tool is used to retrieve allowed sender addresses, likely to obtain sender_id values for email messages, but it gives no explicit when-to-use or when-not-to-use guidance. There is no direct sibling alternative, yet the invocation context is left implicit.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint 'GET /keyword', with no note on pagination, result volume, or whether archived keywords are included — minimal added value.

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, front-loaded with what is returned. The trailing 'GET /keyword' is implementation detail that 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?

With no parameters and no output schema, the description carries the burden of describing return shape, and it does name the three returned fields. It omits any sense of result size or completeness guarantees, which keeps it short of full completeness.

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 no parameters, which is the baseline-4 case; nothing needs documenting. The listed fields (id, keyword, short/long code) describe the response, not inputs, so they are a bonus rather than parameter semantics.

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 (mobile keywords) and enumerates the returned fields (id, keyword, short or long code), which separates it cleanly from the singular sibling trumpia_get_keyword. It lacks an explicit verb like 'list all', but the scope is unambiguous for a zero-parameter tool.

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 at all. With 22 siblings including trumpia_get_keyword, the description never says to use this for a full enumeration and get_keyword for a single lookup, so the agent must infer the choice from names 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context beyond that: the shape of the result (id and name) and the domain meaning of a list as a grouping of subscriptions for targeted messages, plus the underlying GET /list endpoint. It stops short of disclosing result limits or pagination behavior for what is an unbounded list call.

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

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

Three short, front-loaded fragments with no filler: output content first, then a one-line domain gloss, then the endpoint. Efficient, though the telegraphic fragments read more like notes than a structured sentence.

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 tool with no output schema, the description covers purpose and returned fields adequately. However, it omits pagination, result-size limits, or ordering for a call that returns every list in an account, which an agent calling an open-world list endpoint would benefit from knowing.

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 there is no parameter semantics to document and the baseline for an empty schema is 4. The parenthetical '(id and name)' describes return fields rather than inputs, which is still helpful but not parameter guidance.

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 pair ('All distribution lists') and even names the returned fields (id, name), so an agent knows exactly what it gets. It does not explicitly differentiate from the sibling trumpia_get_list, though 'All' implies the enumeration vs. single-record distinction.

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

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

Usage is only implied by the scope word 'All' – an agent can infer this is the enumeration call rather than a single-list lookup. There is no explicit when-to-use, prerequisite, or alternative guidance (e.g., contrast with trumpia_get_list or the search/filter 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the response is a bare array from Trumpia that gets wrapped, and the exact response shape is disclosed. It does not cover rate limits or auth, which keeps it from 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 sentences with no filler, and the wrapping caveat is included compactly. It leads with the return shape rather than the action, which is slightly less front-loaded than ideal, but nothing is wasted.

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

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

There is no output schema, so the description carries the burden of describing the return value — and it does, specifying the wrapper object and the per-item fields (org_name_id, name, default). For a zero-parameter read tool with annotations covering safety, this is nearly complete; only auth or pagination context is absent.

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

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

The tool takes zero parameters, so the baseline is 4. The description still adds meaning by explaining that the returned org_name_id is the value used as org_name_id on messages, giving the identifier a concrete role.

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

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

The description states a specific verb and resource ('Registered organization names') and identifies the endpoint (GET /orgname), so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from sibling list tools such as trumpia_list_lists or trumpia_list_custom_fields, so it stops short of a 5.

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

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

Usage is implied rather than stated: it hints the returned id 'can be set as org_name_id on messages', which suggests a downstream use case. There is no explicit when-to-use guidance, no prerequisites, and no named alternative among the many sibling list tools.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the result shape (id, description, scheduled time, recipient counts), the pagination mechanism, and that total_count reports the full population.

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 clauses, with the resource definition front-loaded before the paging advice and the return-count note. The trailing 'GET /message/scheduled' is mildly redundant for an MCP caller but not wasteful enough to hurt.

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

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

With no output schema, the description usefully names the returned fields and total_count, and the fully documented input schema covers the parameters. The only material gap is that it never says scheduled messages disappear from this list after sending, which affects interpretation of results.

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 each of the three parameters is already fully documented in the schema, including the order enum. The description echoes offset and limit but adds no syntax or default detail beyond them, and omits order entirely — baseline 3 is correct.

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 with a scoping qualifier — 'Messages that are scheduled and not yet sent' — and enumerates the returned fields, so an agent can distinguish it from get_message and cancel_scheduled_message. It stops short of explicitly naming a sibling, but the verb+resource+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?

Usage is implied rather than stated: 'Use offset and limit to page' tells the agent how to consume results, but there is no guidance on when to prefer this over get_message or other list tools, nor any prerequisite/conclusion, as messages leave the list once sent.

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 this a read-only, non-destructive, open-world call, so the safety profile is covered. The description adds genuinely non-obvious behavior: page sizes of 100-10000 and the fact that next_page is only set when a full page came back, which tells the agent how to detect the end of results. It still doesn't say what happens when the account simply has no subscriptions.

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 with zero filler, leading with what is returned before the pagination rules and the endpoint. Every clause carries information the 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?

With no output schema, the description correctly carries the return-shape burden by stating it returns ids only and explaining next_page. Combined with the fully documented two-parameter schema, an agent has what it needs to enumerate subscriptions. Only the omission of any tie-in to the search sibling keeps it from being fully 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%, with page and row_size both documented including defaults and bounds, so the baseline of 3 applies. The description restates the 100-10000 row_size range but adds no new syntax or semantics beyond what the schema already carries.

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 the resource (subscription/contact ids) and the ordering (newest first), so an agent knows exactly what this returns. It also distinguishes itself from the sibling that provides full records by pointing at trumpia_get_subscription. It stops just short of a 5 because the listing verb is inherited from the name/title rather than restated, and the neighboring trumpia_search_subscriptions is never addressed.

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 an explicit routing rule: use trumpia_get_subscription when details are needed, since this returns ids only. That is clear context for one alternative, but with trumpia_search_subscriptions in the sibling set, the agent gets no guidance on when a filtered search is preferable to a plain paged listing.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them: it discloses that only ids are returned, how the 'all' sentinel behaves, and the underlying GET /subscription/search endpoint.

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

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

Dense but front-loaded: the searchable fields come first, then the list-scoping caveat, then the routing hint. The semicolon-heavy packing is efficient, though slightly compressed compared to clean 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 stating that ids are returned and pointing to trumpia_get_subscription for details, and pagination is fully specified in the schema. It stops short of describing the result ordering or envelope, which is a minor gap for a read-only search.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by enumerating the searchable fields for search_type and clarifying that search_data 'all' returns every subscription holding data of that type. It does not add anything for page/row_size, which the schema already covers.

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 (find) and resource (subscription ids) plus the full set of searchable fields, and explicitly routes to trumpia_get_subscription for full details. An agent can distinguish it from trumpia_list_subscriptions and trumpia_get_subscription without opening any schema.

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

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

Names the follow-up tool when details are needed ('use trumpia_get_subscription for details') and notes the optional list scoping, giving clear context. It does not, however, explicitly contrast itself with the sibling trumpia_list_subscriptions, which is the nearest alternative.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true; the description goes well beyond them by stating that messages spend credits, cannot be recalled once sent, require opt-in compliance, and should be user-confirmed. It also discloses the return payload (request_id and message_id) and the underlying endpoint PUT /message.

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 critical warning ('spends credits and cannot be recalled') is front-loaded in the first clause, which is exactly right for a destructive write. The remaining sentences each carry distinct information (recipients, compliance, confirmation, tokens, return values), though the token enumeration is slightly list-like rather 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?

For a 12-parameter mutation tool, the description covers the destructive nature, credits cost, scheduling and cancellation path, compliance preconditions, mail-merge behavior, and return identifiers. With no output schema present, the 'returns request_id and message_id' note closes the main remaining 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 baseline is 3; the description adds real value beyond the schema by documenting mail-merge token syntax ([$FirstName], [$LastName], [$FullName], [$CustomData-NAME]) that maps to the mail_merge_* parameters and the body fields. It does not spell out any of the other 12 parameters, but the schema covers those adequately.

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 concrete verb and resource ('send an SMS and/or an email to distribution lists or specific subscriptions') and immediately scopes the operation as a real, credit-spending, non-recallable write. It also names the related sibling trumpia_cancel_scheduled_message for the scheduling case, so an agent can distinguish this from pure read/list tools 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 explicitly covers when to use it (send now, or schedule with send_date), the alternative path for undoing a scheduled send (trumpia_cancel_scheduled_message), and the preconditions ('Subscribers must have opted in (TCPA, CAN-SPAM, CTIA)', 'Confirm the recipients and text with the user first'). The only missing routing note is against the sibling trumpia_send_sms, but the guidance is otherwise 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?

Adds substantial behavioral detail beyond annotations: spends a credit, cannot be recalled, requires recipient consent, may require API Certification, and should be confirmed with the user. Annotations already declare destructive, non-idempotent, and open-world behavior, and the description enriches this with operational consequences.

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

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

Front-loads the highest-risk information: real SMS, credit spend, irreversible. Each sentence adds a distinct operational warning or return detail, and the endpoint is listed cleanly at the end 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?

Despite no output schema, the description states the return identifiers. It covers consent, credit cost, irreversibility, confirmation guidance, and API Certification caveats, which is enough for an agent to call this destructive tool responsibly.

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 all five parameters thoroughly. The description reinforces that it sends one SMS to one mobile number with text, but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource: sends one real SMS to one mobile number without adding the contact first. The scope phrase 'without adding the contact first' effectively distinguishes it from contact-adding siblings and from list-based messaging tools.

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

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

Provides clear usage context: direct one-off SMS without contact creation, recipient consent required, possible API Certification, and confirmation with the user first. It does not explicitly name an alternative sibling or state when not to use it, 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the partial-update semantics ('Only the fields you pass change'), which tells the agent that omitted fields are preserved rather than reset. It does not, however, explain what the destructive behavior actually entails or note any auth/rate-limit constraints.

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

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

Two short sentences, front-loaded with the WRITE marker and the field list, ending with the endpoint. No filler, no redundancy, and the most decision-relevant information comes first.

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 5-parameter mutation tool with no output schema, the description covers the operation type, the mutable fields and the partial-update rule, while annotations carry the write/destructive/idempotent profile. It stops short of explaining the return value and the meaning/units of 'frequency', but nothing essential for selecting or invoking the tool is absent.

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

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

Schema description coverage is only 20% (list_id is the sole documented parameter), so the description bears much of the burden. It partly compensates by naming the four optional fields that can be modified, mapping them to list_name, display_name, frequency and description. It adds no constraint detail (30/50/20 character limits, frequency range 1-999, or what 'frequency' measures), so the semantic picture remains incomplete.

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?

Opens with an explicit WRITE marker plus a precise verb+resource ('change a distribution list's') and enumerates exactly which fields are mutable (name, display name, frequency, description), which cleanly separates it from the read-only siblings like trumpia_get_list and trumpia_list_lists. The endpoint reference (POST /list/{list_id}) confirms the operation type. An agent can identify this tool without opening the schema.

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

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

'Only the fields you pass change' communicates partial-update behavior, which is meaningful invocation guidance. However, there is no explicit statement of when to choose this over trumpia_create_list or trumpia_get_list, nor any mention of prerequisites or auth. Usage context is implied rather than stated.

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

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

It explicitly labels the operation as a WRITE, describes the partial-update semantics, tells the agent the call returns a request_id, and gives the underlying endpoint. Annotations already flag destructiveHint and idempotentHint, so this adds useful context, though it does not warn about what mutation of list membership or customdata entails.

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 with no filler; the WRITE marker and the field list are front-loaded, then the partial-update rule, then the return value and endpoint.

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 an 8-parameter mutation with nested objects and no output schema, the description covers operation type, partial-update behavior, return value (request_id), and scope. Minor gaps remain around how list membership and customdata entries merge on update.

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 only 25%, yet the description enumerates the semantics of the optional fields (contact detail fields plus custom data and list membership) that the schema leaves undocumented. It does not explain nested details like whether list_names appends or replaces, but it compensates well for the low coverage.

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

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

The description names a specific verb (change) and the exact editable fields (name, email, mobile, landline, custom data, list membership) on a subscription resource, so it is clearly distinguishable from sibling create/read tools like trumpia_add_subscriptions and trumpia_get_subscription.

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?

"Only the fields you pass change" clearly establishes the partial-update use case, but the description does not say when to prefer this over trumpia_add_subscriptions or how it relates to cancel/get operations, so usage context is implied rather than spelled out.

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