OpenPhone MCP by usefulapi

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

Beyond the destructiveHint annotation, the description discloses that this adds a persistent record and that emails/phoneNumbers are stored under default field labels — a real behavioral trait. It stops short of stating auth requirements, duplicate handling, 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?

Three short sentences, front-loaded with the core action and followed by the write warning and a storage detail. The REST endpoint line is mildly redundant given the tool name but is cheap and informative.

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

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

For a 9-parameter write tool with no output schema and only a destructiveHint annotation, the description covers the mutation semantics adequately but omits the return value (created contact id), error/duplicate behavior, and permission requirements.

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 all nine parameters and their types. The description adds only a marginal note on how emails/phoneNumbers arrays are stored, which does not materially extend the schema. 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 ('Create a new contact in the workspace') plus the concrete side effect and backing endpoint (POST /contacts). This clearly separates it from the read-oriented siblings openphone_get_contact and openphone_list_contacts.

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 create semantics and the 'WRITE ACTION' framing, but there is no explicit when-to-use guidance, no mention of how to handle existing/duplicate contacts, and no named alternative for read or update flows among the many sibling 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?

readOnlyHint already declares this as a safe read. Beyond that the description adds genuinely useful context: the underlying REST endpoint (GET /calls/{id}) and, importantly, the shape of the returned call (direction, status, duration, participants, timestamps) — valuable since no output schema exists. It does not cover error behavior (e.g. unknown id), 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?

One sentence front-loads the verb, resource, lookup key, and returned fields, then appends the REST mapping. 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, listing the returned fields is exactly the right compensation, and the id format covers the only input. Missing is any note on failure modes or how to obtain a valid id, which would round out a single-parameter getter.

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

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

Schema coverage is 100% and the single parameter is fully documented there, so the baseline is 3. The description's "starts with 'AC'" note simply repeats the schema's own id description and adds no format, uniqueness, or lookup guidance beyond it.

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

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

States a specific verb and resource ("Get a single call by its id") and enumerates the fields the call object contains, which implicitly distinguishes it from list_calls and the get_call_recordings/summary/transcript sub-resource siblings. It stops short of naming an alternative explicitly, so it is clear but not fully sibling-differentiating.

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 id-prefix condition ("starts with 'AC'") and the by-id framing imply when this tool is appropriate, but there is no explicit when-to-use/when-not guidance and no pointer to list_calls for discovery or to the sub-resource getters for recordings/transcript/summary.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral detail by enumerating the returned fields (URL, duration, start time, status) and the underlying REST endpoint, but says nothing about permissions, empty-result behavior, or recording availability delays.

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 tersely front-loaded sentence plus the REST endpoint reference; every clause carries information and 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?

For a read-only, single-parameter tool with no output schema, the description compensates by sketching the response shape and citing the endpoint. It is essentially complete, missing only minor edge-case behavior such as what happens when no recording exists.

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

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

Schema coverage is 100% and the single callId parameter is already documented with its 'AC' prefix. The description repeats 'by its id' without adding format, validation, or error semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get the recordings for a call by its id') and names the returned fields, so the agent knows exactly what it produces. It does not explicitly contrast itself with close siblings like openphone_get_call_transcript or openphone_get_call_summary, but the resource noun is distinctive enough to route correctly.

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: it is obvious you call this when you want a call's recordings, but there is no when-to-use/when-not guidance and no mention of the transcript/summary alternatives that share the same call context. Adequate but leaves selection between siblings to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds plan-dependent availability and the summarization precondition, plus the underlying REST endpoint, which is meaningful context beyond the annotation.

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

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

Three short sentences, front-loaded with the purpose before the availability caveat and endpoint reference. No filler.

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

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

With no output schema, the description helpfully names what comes back (summary and next steps) rather than leaving it opaque. Minor gap: no mention of behavior when the call was not summarized (error vs empty).

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 callId parameter is documented in the schema (including the 'AC' prefix). The description only restates 'by its id', adding no syntax or format detail, 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 (Get) plus a precise resource (AI-generated summary and next steps) and the lookup key (call id). It is clearly distinguishable from siblings like openphone_get_call_transcript and openphone_get_call_recordings.

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

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

Gives a real precondition for use: availability depends on the plan and whether the call was summarized. It stops short of naming explicit alternatives or when-not-to-use conditions, but the gating context is clear.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds value by disclosing the response shape (segments, speaker, text, timestamps, status, duration), but says nothing about transcript availability latency, missing/empty transcripts, auth requirements, or error behavior for calls without transcripts.

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 zero filler: the purpose and return contents are front-loaded, then the REST endpoint and method are appended. 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?

For a single-parameter read tool with no output schema, the description usefully previews the returned transcript structure and the underlying REST call. What's missing for full completeness is any note on when a transcript may be unavailable or whether access is scoped to the caller's call history.

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

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

Schema coverage is 100% and the id parameter is documented in-schema including the 'AC' prefix hint, so the baseline is 3. The description restates the id lookup but adds no format or validation 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 (Get) and resource (call transcript) identified by id, and lists the payload contents (dialogue segments with speaker, text, timestamps, status, duration). This clearly distinguishes it from sibling read tools like openphone_get_call_summary or openphone_get_call_recordings.

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 description ('by its id'), and the sibling list contains adjacent tools (get_call_summary, get_call_recordings), but the description never explicitly states when to prefer this tool over those or that the call must already exist. Adequate but not explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully confirms the underlying REST call (GET /contacts/{id}) and enumerates the returned field groups, but adds no pagination, error, or auth context.

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

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

Two tight sentences with the purpose front-loaded and the REST endpoint as supporting detail. No wasted words, though the endpoint string is arguably redundant with 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?

With no output schema, the description compensates by naming the default fields (name, company, role, emails, phone numbers) and flagging custom fields. Enough for an agent to know what comes back from this simple single-param read.

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 ('The contact id.'). The description restates the id requirement without adding format, prefix, or sourcing guidance, 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 ('Get a single contact by its id') and enumerates the returned field groups. It distinguishes itself from the list_contacts sibling only implicitly via 'single', so it stops short of an explicit differentiation.

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 'by its id' implies the precondition for use (you already hold a contact id), but there is no explicit when-to-use statement and no named alternative for lookup by other means (e.g. list_contacts or a search tool). Usage is inferred 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds workspace-level scope and the underlying REST endpoint, but says nothing about pagination, rate limits, or whether the list can be empty — modest added value over the annotation.

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

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

Two sentences plus an endpoint reference, all front-loaded with the core purpose first. The REST path adds grounding but is the least essential 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 zero-parameter read-only listing with no output schema, the description adequately covers what is returned and why it matters. A brief note on result shape or ordering would fully close the 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?

The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing parameter-wise for the description to compensate for.

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 — listing the workspace's contact custom-field definitions — and enumerates the returned fields (name, key, type). This clearly distinguishes it from siblings like openphone_get_contact (a single contact) and openphone_create_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?

The description supplies one downstream usage hint ('use the returned keys when creating contacts with custom fields'), which implies this is a prerequisite lookup step. However, it names no alternative tools and gives no exclusions or conditions for when not to call it.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds the REST endpoint mapping (GET /messages/{id}), which is mildly useful for groundedness, but says nothing about error behavior for missing/invalid ids or the shape of the returned 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?

Two short sentences, front-loaded with the action and resource, no filler. Every clause carries information.

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

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

For a simple single-resource lookup with one fully documented required param and readOnlyHint covering safety, the description is essentially complete. Only the return-value/error behavior is unaddressed, which is minor given the tool's simplicity and lack of an output schema.

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

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

Schema coverage is 100% and there is only one parameter whose 'starts with AC' format is already documented in the schema. The description merely repeats that prefix hint, adding no new meaning beyond the structured field.

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

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

Specific verb+resource: 'Get a single message by its id'. The word 'single' implicitly contrasts with the sibling openphone_list_messages, but the differentiation is not made explicit, so an agent must infer it.

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 'a single message by its id' — you would use it when you already have an id rather than listing. However, there is no explicit when-to-use statement, no mention of the list_messages alternative, and no note on where ids come from.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that, the description adds genuine context: result ordering ('newest first') and the return fields ('direction, status, duration and timestamps'), plus the underlying REST mapping. It omits paging behavior and any rate-limit or permission notes.

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 tightly written sentences with the core operation front-loaded and the return summary trailing. The final REST endpoint note is low-value filler, but nothing else 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?

For a 7-parameter read-only list tool with no output schema, the description covers what the tool does, how results are ordered, and what fields come back, which is close to sufficient. Pagination semantics (pageToken/nextPageToken) are left to the schema, which is acceptable but leaves a small gap.

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

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

Schema description coverage is 100%, so every one of the 7 parameters (including required phoneNumberId/participants and pageToken/maxResults) is already fully documented in the schema with formats and examples. The description only restates the user and date-range filters at a high level, adding no syntax beyond what the schema supplies. Baseline 3 applies.

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

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

The description gives a specific verb and resource with scope ('List calls between one of your OpenPhone numbers and a participant'), plus ordering ('newest first') and filter dimensions. It clearly separates itself from the singular get_call sibling by being a list operation, 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?

Usage is implied by the filtering language ('optionally filtered by user and created date range'), which suggests when the filters are relevant. There is no explicit when-to-use statement, no exclusion conditions, and no pointer to alternative list tools such as openphone_list_conversations or openphone_list_messages.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely useful context: it enumerates the returned fields (name, company, emails, phone numbers) plus custom fields, and maps to the REST endpoint GET /contacts. It omits pagination behavior and rate limits, but the added return-shape detail is meaningful, especially with 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?

Two sentences, zero filler, front-loaded with the core action and scope; filters and return content follow in priority order.

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 list tool with no output schema, the description covers return content and the endpoint, which is what an agent needs to interpret results. Pagination is documented in the schema via pageToken/nextPageToken, so the only minor gap is not stating paging behavior in prose.

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 four parameters including filter semantics and the pageToken/maxResults constraints. The description only restates that externalIds and sources act as filters, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource with scope ('List contacts in the workspace') and names the two filter dimensions. It doesn't explicitly contrast with the singular openphone_get_contact sibling, so an agent must infer list-vs-get from the name.

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 'optionally filtered by external ids or sources' implies when the filters are useful, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative (e.g., get_contact for a single record). Usage 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: results are sorted by most-recent activity and each conversation carries participants, assignee, and last-activity metadata, plus the underlying REST endpoint. It does not explain pagination behavior, which is the one remaining gap.

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

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

Two compact sentences front-load the resource, ordering, and filters, followed by a short REST endpoint reference. No filler, though the endpoint line is marginally redundant for an agent that never calls the raw 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?

For a 9-parameter read tool with no output schema, the description covers resource, ordering, filter categories, and returned metadata, which is enough to invoke it correctly. Only pagination flow (pageToken/nextPageToken) is left entirely to the schema.

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

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

Schema description coverage is 100%, so every parameter (userId, pageToken, maxResults, date bounds, phoneNumbers, excludeInactive) is already documented in the schema. The description restates the filter categories but adds no syntax, format, or defaulting detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List conversations (threads)'), states the ordering ('most-recent activity first'), and enumerates the filter dimensions. It cleanly separates this tool from siblings like openphone_list_messages and openphone_list_calls by naming the conversation/thread resource.

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 tells the agent which filters are available (phone numbers, user, created/updated ranges), which implies when the tool is useful, but it never states when to prefer this over a sibling such as list_messages or list_calls, nor any prerequisites. Usage is inferable rather than explicit.

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

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

readOnlyHint=true already declares this is a safe read. The description adds return-field context (text, direction, status, timestamps), which is useful, but says nothing about pagination behavior, rate limits, or result ordering despite pageToken/maxResults existing. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Three short, front-loaded sentences with no filler; the core scope comes first, followed by return values and the REST mapping. Tight overall, though the REST endpoint sentence is mildly decorative for an agent.

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 list tool with full schema coverage, the definition covers purpose, scope, and return fields. The absence of an output schema is partly compensated by the field list, but pagination guidance is left entirely to the schema.

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

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

Schema description coverage is 100%, so all seven parameters, including formats like E.164 and ISO-8601, the 1-100 range, and cross-references to sibling lookup tools, are already documented in the schema. The description adds no parameter meaning beyond 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 verb (List) and resource (messages) scoped to a conversation between an OpenPhone number and participants, and even names the return fields and REST endpoint. It does not explicitly distinguish itself from siblings like openphone_get_message or openphone_list_conversations, 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 'in a conversation between one of your OpenPhone numbers and one or more participants' implies when to use it, but there is no explicit guidance on alternatives (e.g. get_message for a single message) or when not to use it. Usage 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?

readOnlyHint=true already covers the safety profile, and the description adds useful non-obvious context: the returned field set, the dependency relationship with other tools, and the underlying REST endpoint (GET /phone-numbers). No pagination or rate-limit detail, but for a simple read-only list this is solid additional context.

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

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

Three compact sentences, zero filler, with the resource, its role in the workflow, and the API mapping front-loaded in that order. Every clause carries information an agent can act on.

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-optional-parameter, read-only list tool with no output schema, the description inlines the returned fields and explains its place in the call sequence. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single userId parameter is fully documented in the schema, including its 'US' prefix format and cross-reference to openphone_list_users. The description adds nothing about 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?

States a specific verb and resource ('List the OpenPhone numbers in the workspace') and enumerates the returned fields, so an agent knows exactly what it gets back. It also distinguishes itself from siblings by noting it is 'usually the first call' whose phoneNumberId output feeds most other 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?

Explicitly positions usage ('Usually the first call — most other tools need a phoneNumberId'), which is genuine routing guidance relative to siblings like get_call or send_message. It stops short of stating exclusions or a full when-not-to-use condition, so it falls just short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description carries a lighter burden. It adds the REST endpoint (GET /users), which is mildly useful for traceability, but discloses nothing about pagination limits, rate limiting, or scope of visibility beyond the annotations.

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

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

Two compact sentences: the first states what is returned, the second states why to call it. The endpoint reference is a short trailing clause. Nothing is padded or 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?

For a two-parameter read-only list with no output schema, the description covers purpose, returned fields, and intended use well enough to invoke correctly. Minor gaps remain around pagination behavior and visibility scope, which the annotations and schema don't cover either.

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% – pageToken and maxResults are both fully documented in the schema, including the 1-50 range and default of 10. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List workspace users') and enumerates the returned fields (id, email, name, role), which is more than a bare restatement. It does not explicitly contrast itself with siblings like openphone_list_contacts, but the resource is unambiguous enough that an agent won't confuse the two.

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

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

Gives a clear reason to call it: 'Use to find a userId for scoping other calls.' This is a genuine usage context rather than an implied one. It lacks any when-not guidance or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only nature and adds useful behavioral detail (it does not create or delete). It also discloses the REST endpoint GET /webhooks. It stops short of pagination or auth behavior, 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 sentences, front-loaded with the core action and return fields, followed by the safety boundary and the endpoint. Every sentence earns its place with no redundancy.

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

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

With no output schema, enumerating the returned fields (id, url, events, status) meaningfully compensates and confirms the read-only nature. Only minor omissions remain, such as pagination or empty-state behavior.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent 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 a specific verb (List) and resource (webhooks) with explicit scope (configured in the workspace) and even enumerates the returned fields. An agent can identify this as the read-only webhook inventory without ambiguity.

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

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

The 'Read-only inventory — this tool does not create or delete webhooks' line clarifies the use context and draws the boundary against mutation operations. No sibling webhook tool exists to route to, so the lack of named alternatives is not a gap, though it stays implicit rather than stating when to reach for it.

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

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

Annotations only carry destructiveHint=true; the description does the heavy lifting by disclosing that this is a WRITE ACTION, that it sends a real message, that it may incur carrier cost, and that A2P 10DLC registration is required, plus the underlying endpoint. This is behavior an agent cannot infer from the annotation 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?

Three tight sentences: what it does, the critical write/cost caveat, and the API mapping. Front-loaded and free of 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, and the description still doesn't hint at what a successful response contains (message id, delivery status) or failure modes beyond registration. For a send tool this is a minor gap; the send-time risks are well covered.

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 parameters (to, from, userId, content, setInboxStatus) are already documented with formats and bounds. The description only restates the 'up to 10 recipients' limit already encoded as maxItems, adding no new parameter meaning.

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 an SMS/text message from one of your OpenPhone numbers') plus the recipient ceiling, which cleanly separates it from the read-side siblings like openphone_get_message and openphone_list_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 description establishes prerequisites (approved A2P 10DLC registration) and warns that this is a real send, but it never states when to choose this tool over an alternative or any exclusions. Usage is implied by the write nature rather than explicitly guided.

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