SuperPhone MCP by usefulapi

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

Goes beyond the annotations by disclosing that passing a new tag name implicitly creates that tag (a side effect not covered by idempotentHint or destructiveHint) and that the call returns the contact with its tags. It does not explain why the tool is flagged destructiveHint=true, which is the one behavioral trait the annotations raise but leave uninterpreted.

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, write-classification and core action front-loaded, no filler. The GraphQL mutation names at the end are compact provenance rather than padding.

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

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

With 3 parameters, no output schema, and one required field, the description covers the write, the two input modes, the creation side effect, and the return shape. Only the destructiveHint rationale and any permission/rate-limit expectations are missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema's terse "Tag names." does not: a name that does not exist will create the tag. That materially affects how the agent chooses between tag_names and tag_ids.

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 ("apply tags to a contact") and front-loads the WRITE classification. It is clearly distinguishable from the sibling superphone_remove_contact_tags and from superphone_update_contact.

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

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

Explains the two usage modes (by name, which creates the tag if new, or by tag id) and notes that tags can drive automations, giving the agent a reason to pick this tool. It stops short of naming when to use a sibling instead, but the alternative that matters (remove_contact_tags) is unambiguous 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 destructiveHint=true and idempotentHint=false; the description adds the concrete consequence ("adds to the contact's total spent") and a specific irreversibility caveat ("cannot be undone with this server"), which is exactly the context annotations cannot convey. It stops short of stating permissions or how the aggregate is affected on failure.

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 sentences, zero waste, front-loaded with a WRITE marker so the agent immediately knows the operation class. Every sentence carries distinct information: intent, side effect, return value.

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

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

For a 4-parameter mutation with full schema documentation and clear annotations, this covers purpose, side effect, irreversibility, and return value. Minor gaps remain: no note on required fields (delegated to schema) or what happens if the contact does not exist.

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% — every parameter has a description, examples, format hints, and bounds — so the description correctly does not duplicate them. Its parenthetical "(name, amount, date)" merely echoes three of the four fields without adding format or default semantics (e.g. `created_at` defaulting to now is only in 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 ("record") and resource ("a purchase or donation against a contact") plus the key identifying fields. No sibling tool performs contributions, and the GraphQL mutation name (`createCustomContribution`) pins down exactly which backend operation this is.

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 context of use is implied — logging a purchase or donation for a contact — but there is no explicit "use this when…" framing, no prerequisite (contact must already exist), and no mention of alternatives or when-not to use it. Adequate, but the agent has to infer the trigger.

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 write/destructive/non-idempotent behavior, and the description adds useful context that no message is sent and that the new contact is returned. However, it does not warn about the practical consequence of destructiveHint=true / idempotentHint=false — namely that repeated calls may create duplicate contacts.

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

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

Four short clauses, front-loaded with the WRITE marker and required parameter, with zero filler. Every sentence earns its place.

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

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

Given 21 parameters, no output schema, and rich annotations, the description covers the essentials: required field, key identity fields, no-message side effect, and return value. The one notable gap is duplicate-creation guidance for a non-idempotent create.

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?

All 21 parameters are documented in the schema (100% coverage), so the schema does the heavy lifting. The description adds a little meaning by flagging first_name as required and recommending mobile/email for reachability, but does not explain the many optional fields (vip, unsubscribed, archived, hidden) that carry behavioral weight.

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 ('WRITE: create a contact') and explicitly names the underlying GraphQL mutation `createContact`, making it distinguishable from siblings like superphone_update_contact and superphone_find_contact without inspecting 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?

Includes an actionable constraint ('add a mobile number or email so it can be reached') and clarifies a boundary ('Creating a contact does not send it a message'), implicitly routing messaging to send_message. It stops short of naming update_contact as the tool for existing records, so it's clear context rather than full when/when-not 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral information — it returns the full contact or null on no match (so a miss is not an error), and names the backing GraphQL query contactByIdentifier. No auth or rate-limit context, but that is a minor gap here.

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 action and keys in one sentence, followed by return behavior and then a trailing GraphQL name fragment that is marginally useful. No filler, though the query-name detail is the weakest element.

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

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

For a two-parameter read with no output schema, the description covers keys, format, and the null-on-no-match return, which is what an agent needs to branch on results. It does not say what happens when both email and mobile are supplied, leaving one small behavioral question open.

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

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

Schema coverage is 100%, so baseline would be 3. The description exceeds that by resolving the ambiguity of zero required parameters — it states at least one identifier must be supplied — and reinforces the E.164 format expectation for mobile.

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 plus the exact lookup keys ('Find one contact by exact mobile number or email address'). The emphasis on 'exact' and 'one' implicitly separates it from list_contacts and from fuzzy lookups like search_numbers, so an agent can pick it without opening sibling schemas.

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 useful invocation context ('give at least one') and format guidance (E.164), but never names an alternative such as get_contact when an ID is already known, nor says when this tool is the wrong choice. Usage is implied rather than explicitly routed.

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 read-only, non-destructive behavior, so the description is not burdened with safety disclosure. It adds useful behavioral context by listing the returned data fields and noting the underlying GraphQL `me` query, though it does not describe error handling or rate-limit 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?

The description is a single front-loaded sentence plus a short technical note. Every element adds useful information about scope or return content, 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 simple, zero-parameter, read-only account retrieval tool with no output schema, the description provides sufficient completeness: resource identity, authentication context, returned fields, and the underlying query. Nothing critical is omitted for correct invocation.

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

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

The tool has zero parameters, so parameter semantics baseline is 4. The empty schema is consistent with the description, which correctly presents this as a no-argument account lookup.

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

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

The description clearly identifies the resource as the Superphone account behind the API key and enumerates returned fields, which distinguishes it from contact, conversation, and message tools. It lacks an explicit retrieval verb in the description itself, but the title 'Get account' and the GraphQL query reference make the purpose unambiguous.

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

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

The intended usage is implied: call this when you need the account associated with the API key. There is no explicit guidance on when to prefer or avoid this tool versus alternatives, but for a zero-parameter account tool the implication is reasonably clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by scoping the return ('latest 10 conversations'), which tells the agent results are bounded and partial. It says nothing about permission requirements or error behavior for an invalid id.

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 with the payload contents front-loaded after the verb+resource, plus a short trailing note on the underlying GraphQL query. Every clause carries information; the GraphQL reference is minor but harmless.

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 must describe the return value, and it does so concretely: profile fields, tags, contributions, and the latest 10 conversation ids. Combined with annotations covering the safety profile, an agent has enough to call this correctly; only cross-tool selection guidance 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?

There is one parameter at 100% schema description coverage, so the schema already documents contact_id fully. The description restates the by-id access pattern but adds no format, source, or constraints beyond the schema — baseline 3 for high 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?

States a specific verb and resource ('One contact by id') and enumerates the returned payload (profile fields, tags, contributions, latest 10 conversations), which makes it distinguishable from list_contacts and find_contact by shape. It stops short of naming those siblings explicitly.

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

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

The by-id framing implies this is the follow-up to a search/list result rather than the discovery tool, and it helpfully routes the agent to superphone_get_conversation for the embedded ids. However, it never states when to prefer find_contact or list_contacts, so the alternative-selection logic 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add behavior. It does: default page size, 'newest last' ordering, the full set of returned fields, and the cursor-chaining rule for older pages. Return shape matters here because there is no output schema, and ordering/pagination disclosure is exactly the kind of context annotations cannot carry.

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 the resource and scope, then the pagination rule. Dense but every clause carries information; the long field enumeration is the only mild readability cost.

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 payload fields, ordering, default page size and how to page backwards, which is what an agent needs to call and continue correctly. Only the absence of explicit sibling routing keeps it short of 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 coverage is 100%, so the schema already documents conversation_id, message_count (1-100, default 20) and the before cursor semantics. The description largely restates those facts rather than adding new meaning 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 resource and scope: 'One conversation with its most recent messages (default 20, newest last)' and enumerates the returned fields (body, from/to, direction, status, errors, media). This implicitly separates it from superphone_list_conversations (many conversations) and superphone_get_message (a single message), though neither sibling is named.

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?

Offers concrete operating guidance for pagination: 'To read older messages pass `before` = the previous reply's previous_cursor.' However, it never says when to reach for this tool versus superphone_get_message or superphone_list_conversations, so the selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying GraphQL operations (`form` / `defaultForm`), which is mild debugging context, but says nothing about return shape or failure behavior for a missing id.

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

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

Two compact sentences with the primary behavior and the default fallback front-loaded; the trailing GraphQL query names are marginal but very short. No filler or repetition.

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 full annotation coverage and no output schema, the description supplies what an agent needs to call it correctly, including the omitted-argument behavior. Only the return content of a form is left implicit.

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 optional parameter is fully documented in the schema, so the baseline of 3 applies. The description's 'omit for the default form' restates the schema rather than adding new 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 a specific verb and resource ('one sign-up form'), and covers both operating modes: by id, or the account default when form_id is omitted. This contrasts implicitly with superphone_list_forms, though no sibling is named 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 default-form behavior when form_id is omitted is a useful usage rule, but there is no explicit guidance on when to choose this over superphone_list_forms or other form-related tools, and no exclusions or prerequisites are 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 returned field set and identifies the underlying GraphQL query `message`, which is genuinely useful context, but says nothing about permissions, missing-id/not-found behavior, 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 short fragments, front-loaded with the resource and immediately followed by the return payload — no wasted words. The telegraphic fragment style is slightly terse but never ambiguous.

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 with no output schema, listing the fields returned and naming the GraphQL query is enough for an agent to call it correctly. Only the absence of not-found/error behavior keeps it from a 5.

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

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

Schema coverage is 100% with a single well-documented message_id parameter, so the baseline is 3. The description only restates 'by id' and adds no format, scoping, or lookup-hint detail 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?

States a specific verb+resource combination ('One message by id') and enumerates the returned fields (body, from/to, direction, delivery status, error, media), which clearly separates it from sibling reads like get_conversation or list_conversations. It does not explicitly name a sibling, so it falls short of a 5.

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

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

The phrase 'by id' implies that this is a single-record lookup requiring a known message_id, but there is no explicit when-to-use/when-not guidance and no mention of alternatives for discovering message ids (e.g., get_conversation). Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: deterministic ordering (oldest first), the cursor-based paging contract, and the semantics of `total` (size of the whole list, not the page). The parenthetical "tags (up to 20)" is slightly ambiguous about whether it limits tags per contact or fields returned.

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 plus two short clauses; ordering and pagination are front-loaded and the GraphQL query name trails as a useful appendix. No filler, and 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 does the work of enumerating the returned fields, the flag set, ordering, and the meaning of `total`, so the agent can use the response without guessing. Minor residual gaps: no mention of default page size behavior in prose (it is in the schema) and no scoping/auth notes for an openWorldHint 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?

Schema description coverage is 100%, so both `after` and `page_size` are already fully documented, which sets a baseline of 3. The description adds value by tying `after` to the previous reply's next_cursor as a paging flow and by defining `total` relative to the unpaged list, clarifying how the two parameters interact with the response.

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 SMS contacts (the subscriber list)") and immediately enumerates the returned fields, so the agent knows exactly what it gets back. It is clearly distinguished from the singular siblings superphone_get_contact and superphone_find_contact by being a bulk list of the whole subscriber base.

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 makes clear this returns the full list (oldest first) and explains the pagination loop via next_cursor, which is the main usage decision for this tool. It stops short of explicitly routing away from find_contact or get_contact when a specific record is wanted, leaving that inference to the agent.

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 genuinely useful context beyond that: the platform enum mapping (TWILIO=SMS, FACEBOOK=Messenger), hidden/archived flags, the pagination loop via next_cursor, and the GraphQL query name. Absent rate-limit or ordering details 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?

A single dense sentence plus a short routing clause and pointer to the GraphQL query — every fragment earns its place, and the most important information (what it lists, how to page, where to go next) is front-loaded.

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

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

There is no output schema, yet the description enumerates the returned fields, explains pagination, and decodes the platform enum, which is exactly what an agent needs to interpret results. Nothing material for calling this read-only list tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (after, page_size) are already fully documented with limits and defaults. The description only restates the pagination flow ('Page with next_cursor') without adding syntax or edge-case behavior, so the schema is doing the heavy lifting — baseline 3.

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

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

States a specific verb+resource ('List text conversations (the inbox)') and enumerates the returned fields (id, participant number, platform, flags, creation date, contact). It also names the underlying GraphQL query and points to superphone_get_conversation for detail, so it is clearly separable from its 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?

Explicitly routes to the alternative: 'Read the messages of one with superphone_get_conversation,' which tells the agent when to switch tools. No explicit exclusions or conditions (e.g., filtering/preconditions) are given, keeping it below 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?

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value beyond them by enumerating exactly what each form record contains (id, public hashId, domain, titles, opt-in flag, optional fields, redirect URL, default/enabled flags) and naming the backing GraphQL query.

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 whose field enumeration is dense but purposeful, followed by the GraphQL query identifier as a short trailing qualifier. No filler and nothing redundant.

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

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

With no output schema, the field list is the agent's only signal about return shape, and it provides that. Minor gaps remain: no mention of ordering, pagination, or what an agent should do if the list is empty, but for a parameterless read tool this is close to sufficient.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly presents this as an unfiltered enumeration with no arguments to explain.

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 opens with a specific verb and resource ("List the sign-up (opt-in) forms") and clarifies the domain concept of opt-in forms, which an agent can distinguish from mutation siblings. It stops short of explicitly differentiating from the close sibling superphone_get_form, relying on the implicit list-vs-get contrast.

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: an agent can infer this is the tool for enumerating all forms with no filtering. There is no explicit guidance such as "use superphone_get_form when you already have an id" and no exclusions or prerequisites 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 genuinely useful behavioral context beyond that: the exact response shape (id, destination URL, active flag) and the full enum of subscribable event types, plus the backing GraphQL query name.

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

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

Two compact sentences, front-loaded with the action and return fields. The long parenthetical event list is the bulkiest element but earns its place by telling the agent the exact value vocabulary it will see in results.

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-argument read tool with no output schema, the description carries the return-value burden well by naming the returned fields and event values. Only minor gaps remain (whether results are ever paginated, and whether the destination URL may be truncated/masked).

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. It correctly does not waste text inventing input 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 a specific verb and resource ("List the configured webhooks") and immediately enumerates the fields returned, so the agent knows exactly what it gets. No sibling tool lists webhooks, so differentiation is implicit but 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 by the name and the read-only listing framing, but there is no explicit guidance on when to call this versus other discovery tools or what prerequisites exist (e.g., account scope). No exclusions are offered, though none are obviously needed for a catalog 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still adds real value by disclosing the downstream effect on segments/automations and the response shape. The GraphQL mutation names give an extra implementation anchor not present in structured fields.

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

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

Three short sentences, front-loaded with the operation and the mutation classification, then the side effect and return value. No filler or redundant restatement of the schema.

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 what is returned ('the contact with its remaining tags'), and the side-effect warning covers the destructive behavior. Only a note on failure modes (e.g. unknown tag names) is missing, which is minor.

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%, including the 'give tag_names or tag_ids, not both' exclusivity rule, so the schema already carries the parameter semantics. The description's 'by name or by tag id' merely restates it at a high level and adds no syntax or format detail 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?

Opens with a specific verb+resource ('remove tags from a contact') and adds the two supported mechanisms ('by name or by tag id'). Against the sibling superphone_add_contact_tags the verb alone distinguishes the operation, so an agent can route correctly 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?

It states the consequence ('can take the contact out of tag-driven segments and automations') and the name-vs-id alternative, which implicitly tells the agent when this matters. However, there is no explicit when-to-use/when-not guidance and no named sibling alternative (e.g. update_contact) for cases where this is the wrong 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 cover readOnlyHint=true, destructiveHint=false, and openWorldHint=true; the description reinforces the safety profile with 'this tool never buys a number,' which is the key behavioral risk for a number-search tool. It also discloses that results carry price, which annotations don't express.

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 what is searched and the optional filter in the first clause, then the safety constraint and the backing GraphQL query name. The GraphQL reference is minor but useful for debugging; nothing is padded.

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

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

With no output schema, the description compensates by noting results include price. It is a single optional parameter, read-only tool, so the remaining omission (result ordering/pagination) is small.

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

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

Schema description coverage is 100% and the single parameter's pattern and description already document the prefix semantics. The description's 'optionally starting with some digits (for example an area code)' mirrors the schema rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb (Search) and resource (phone numbers available to buy), plus scope: the account, optional prefix, and that results include pricing. No sibling tool covers number search, so no ambiguity risk.

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?

Establishes clear context: numbers that could be bought, with an optional prefix filter. It also explicitly warns this tool never buys, implicitly pointing an agent to a purchase step elsewhere. No named alternatives exist among siblings, so the bar is met without 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 destructive/open-world/non-idempotent, and the description adds materially: message is delivered immediately, consumes the account's messaging credits, cannot be recalled, and returns the new message id. These consequences (cost, irreversibility, return value) are not derivable from the annotation flags alone.

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 severity marker 'WRITE, IRREVERSIBLE', then packs constraints, addressing rules, and return value into a few dense sentences with no filler. Length is proportionate to a destructive send operation.

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

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

No output schema exists, yet the description states the return value (new message id). Combined with the schema covering all four parameters, an agent has everything needed to call this destructive tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuinely non-schema constraint: exactly one of conversation_id or mobile must be supplied (the schema expresses no oneOf), plus E.164 guidance with the US country-code default. The platform/mobile interaction is left unaddressed, keeping it below a 5.

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 — send a real text message to a customer from the account's number — and distinguishes it from sibling read tools like superphone_get_message and superphone_list_conversations by framing it as a write/dispatch action. The GraphQL mutation name `sendMessage` anchors it further.

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

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

Explicit when-to-use and when-not: only send what the user explicitly asked for, to the number they named, and never to opted-out contacts. It also gives the routing rule for the two addressing modes — exactly one of conversation_id (existing thread) or mobile (new recipient).

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 safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds real operational detail beyond them: the read-modify-write implementation, the API's requirement that first_name be sent on every update, the empty-string clearing rule, and that the updated contact is returned. It doesn't warn about side effects on omitted fields beyond the patch note, or mention permission requirements.

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

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

Front-loaded with the WRITE marker, then four tight clauses covering patch semantics, the first-name quirk, clearing, and the return value. Nothing is repeated from the annotations and no sentence is filler.

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

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

For a 22-parameter mutation with no output schema, the description covers the essential mechanics (partial update, clearing, return value) and the schema documents all parameters. Gaps are minor: error behavior, whether unknown fields are rejected, and auth requirements are 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 coverage is 100%, so the baseline is 3; the description goes beyond it by explaining empty-string clearing for text fields and the special first_name handling that isn't visible in the schema (first_name is not even required in the schema). It doesn't cover the boolean flags' semantics (vip, hidden, archived), which remain thin.

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 specific verb+resource ("change fields of an existing contact"), which cleanly separates it from create_contact, get_contact, and find_contact. An agent can identify the operation 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?

States the patch semantics clearly ("Only the fields you pass change") and gives the clearing convention ("Pass an empty string to clear a text field"), which is the main ambiguity an agent would face. It doesn't explicitly name alternatives like create_contact or get_contact, so it stops short of full when/when-not routing.

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