openphone

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

Annotations only supply destructiveHint=true, so the description usefully clarifies the semantics: it is an additive write that creates a persistent record, and it discloses that emails/phoneNumbers are stored under default field labels rather than custom ones. It also names the underlying REST call (POST /contacts). It stops short of stating auth requirements, duplicate-handling behavior, or irreversibility.

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 action and its persistence consequence, then the parameter nuance, then the endpoint. No filler sentences.

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 is adequate but incomplete: it never states what is returned on success (e.g., a new contact ID) or how duplicate contacts are handled. The absence of an output schema means the description could reasonably carry that information, and it does not.

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 real meaning beyond the schema by explaining that emails and phoneNumbers are passed as simple string arrays and land under default field labels - a constraint the schema does not convey. It says nothing about role/company/externalId, which the schema already documents.

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 ('Create a new contact in the workspace') with scope stated. Every sibling tool in the list is a read operation (get_*, list_*) or send_message, so creation is trivially distinguished from all of them.

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

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

No when-to-use or when-not-to-use guidance, and no alternatives or prerequisites (e.g., dedupe against openphone_get_contact / list_contacts before creating) are mentioned. The 'WRITE ACTION' label implies caution but does not route the agent between 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=true already tells the agent this is a safe read, so the description's main addition is the underlying REST call (GET /calls/{id}) and the field set returned. It does not disclose error behavior for a missing/invalid id or any pagination/auth nuance, which is acceptable given annotation coverage but adds only moderate value.

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

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

One sentence plus endpoint reference, front-loaded with the verb, resource, and lookup key. No filler and nothing an agent must scroll past.

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

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

There is no output schema, so the description usefully compensates by listing the returned fields, and it notes the id prefix. It stops short of describing error/not-found handling, but for a single-read tool with a trivial schema this is nearly 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?

Single parameter with 100% schema description coverage; the schema already documents the id format, and the description's 'starts with AC' simply restates it. Baseline 3 applies since the schema carries the 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 precise verb+resource ('Get a single call by its id') and enumerates the returned surface (direction, status, duration, participants, timestamps), which implicitly separates it from sibling readers like get_call_recordings, get_call_summary, and get_call_transcript. An agent can distinguish it from list_calls 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?

Usage is implied — retrieve one call when you already have its id — but the description never states when to prefer this over list_calls or the transcript/summary variants. No exclusions or prerequisites are given, leaving routing 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 the safety profile is covered; the description adds real value by disclosing the return shape (URL, duration, start time, status) and the underlying REST endpoint. It stops short of noting auth requirements or behavior when no recording exists.

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

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

One front-loaded sentence covering purpose plus return fields, followed by a compact endpoint reference. Nothing is redundant or padded.

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

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

For a single-parameter read tool with no output schema, the description covers what the agent needs: the required id and the shape of the response. Only minor gaps remain (empty-result behavior, pagination/auth), which are low-risk for this call.

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 schema already explains that callId starts with 'AC', so the description's 'by its id' adds no new syntax or format detail. Baseline 3 is appropriate when the schema carries the 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 and resource ('Get the recordings for a call by its id') and even names the fields returned, which cleanly separates it from siblings like get_call_transcript, get_call_summary and get_call. It does not explicitly name those siblings, so an agent must infer the distinction from the resource noun alone.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives; the only condition given is the implicit 'you have a callId'. An agent must already know that recordings differ from summaries and transcripts.

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 meaningful behavior beyond that: the result is AI-generated, includes next steps, and may be unavailable depending on plan or whether summarization occurred. It stops short of describing the response shape or what a not-summarized call returns.

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 that front-load the purpose and then the availability caveat; the REST endpoint reference is compact and useful. Slightly dense with three separate pieces of information but no filler.

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

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

For a one-parameter read with no output schema, the description covers purpose, the content of the result (summary + next steps), and the main failure condition. Only the exact return structure is unstated, which is minor given the tool's simplicity.

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 is fully documented in the schema (including the 'AC' prefix). The description adds nothing beyond 'by its id', so the baseline 3 for schema-covered parameters 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 precise verb and resource ('Get the AI-generated summary and next steps for a call by its id'), which cleanly separates it from siblings like openphone_get_call_transcript or openphone_get_call_recordings. An agent can identify the tool's output without opening the schema.

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

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

It gives a real precondition ('Availability depends on your plan and whether the call was summarized'), which implies when the call may fail. However, it never routes the agent between this tool and the closely related openphone_get_call / get_call_transcript siblings, so the 'use this instead of that' guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by detailing the response shape (speaker/text/timestamp segments, overall status and duration) and naming the underlying REST endpoint, which helps an agent anticipate what it will receive.

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 compact sentence that front-loads the action and return content, followed by a short REST reference. No filler or 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, the description usefully characterizes the transcript payload, and for a single-parameter read tool that is nearly sufficient. Minor gaps remain: no mention of what happens if a transcript is missing/unavailable, nor any size or pagination considerations for long calls.

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 'id' parameter is fully documented there (including the 'AC' prefix). The description adds only 'by its id', so it neither clarifies nor misleads — baseline 3 for a fully-schema-documented parameter.

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 transcription for a call) and enumerates the returned content: dialogue segments with speaker, text, timestamps, plus status and duration. This clearly separates it from siblings like get_call_summary and get_call_recordings, so an agent can route correctly without opening any schema.

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

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

Usage is implied by the return content (use it when you need the actual dialogue, not a summary), but the description never states when to prefer this over get_call_summary, get_call, or get_call_recordings, nor any preconditions such as requiring the call to have been transcribed.

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 context about what is returned (default fields such as name, company, role, emails, phone numbers plus custom fields), but says nothing about error behavior for invalid ids 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 compact sentences, with the operation and scope front-loaded and return-field detail appended. The REST endpoint reference is mildly redundant but harmless; 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 simple single-resource read with annotations covering safety and a fully documented one-parameter schema, the description is nearly complete, even enumerating the return envelope since no output schema exists. Only failure modes and auth requirements are unaddressed.

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

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

Schema coverage is 100% with a single required 'id' parameter already documented in the schema. The description restates 'by its id' without adding format, prefix, or lookup semantics 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 names a specific verb and resource ('Get a single contact by its id') and enumerates the returned default fields plus custom fields. It distinguishes itself from openphone_list_contacts by scoping to one contact, though it never explicitly names that 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?

Usage is implied by the singular, id-based retrieval pattern, but there is no explicit statement of when to use this versus openphone_list_contacts or openphone_get_contact_custom_fields. No prerequisites or exclusions are given.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's main added value is the returned field shape (name, key, type) and the REST endpoint. It does not mention pagination, ordering, or whether an empty workspace returns an empty list, which are the remaining behavioral unknowns for a list operation.

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

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

Three short, front-loaded sentences with no filler: purpose, downstream usage, and endpoint provenance. 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?

For a zero-parameter read with no output schema, the description covers what is needed: what is returned (name, key, type) and how the result is consumed. 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?

The tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate and the description correctly implies the call is workspace-scoped with no filters or arguments.

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 (the workspace's contact custom-field definitions) and even names the fields returned (name, key, type). No sibling tool covers custom fields, and the purpose is unambiguous without opening the schema.

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

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

Explicitly routes the agent: 'Use the returned keys when creating contacts with custom fields,' which ties this read tool to openphone_create_contact. It gives clear context but no when-not-to-use guidance or alternative discovery paths.

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 safe read-only nature is covered structurally. The description adds the useful detail that the id is a message id starting with 'AC' and maps to the REST endpoint GET /messages/{id}, but it says nothing about error behavior for unknown ids or pagination/return shape. That is a modest addition over 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 clauses, front-loaded with the core action, with zero filler. Every element earns its place and is easy to scan.

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

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

For a one-parameter read-only lookup with full schema coverage and readOnlyHint annotations, the definition contains everything needed to invoke it correctly. The only mild gap is that no output schema exists and the description does not hint at the returned message shape, though this is largely predictable.

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 'id' parameter is fully documented in the schema, including the 'AC' prefix. The description only restates that same prefix hint, adding no format or constraint details beyond the schema, 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 (get) plus resource (a single message) and even pins the identifier format, so it is clearly distinguishable from openphone_list_messages, which returns many messages. It stops short of explicitly naming a sibling as an alternative, so it is clear but not maximally differentiated.

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 says what the tool does but never states when to reach for it versus openphone_list_messages or openphone_get_contact. There are no prerequisites, no conditions, and no exclusions 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: default ordering is newest first, and the response reports direction, status, duration and timestamps. It omits pagination behavior despite the pageToken/maxResults parameters, which is the main 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?

Three compact sentences with zero filler: scope, return fields, and the REST endpoint. Critical scoping information is front-loaded, and nothing is repeated from structured fields.

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 a fully documented schema and no output schema, the description supplies the missing return-field information and ordering. Only pagination semantics (how to resume with pageToken) are left unstated, a minor gap given the schema documents pageToken's origin.

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 seven parameters including formats and defaults, making 3 the baseline. The description reinforces the required phoneNumberId+participants pairing and the user/date-range filters but adds no syntax or constraint detail beyond what the schema states.

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

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

States a specific verb and resource ('List calls') plus the exact scope: calls between one of your OpenPhone numbers and a participant. It also gives ordering ('newest first') and filter dimensions, which cleanly distinguishes it from openphone_get_call (single call) and the other list_* siblings. An agent can identify it without opening the schema.

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

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

The description implicitly defines usage by stating the required shape of the query (between your number and a participant) and the optional filter axes (user, created date range), so the agent knows this is a scoped list operation, not a global one. It does not explicitly route to or away from openphone_get_call or openphone_get_call_transcript, so it stops short of 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?

readOnlyHint=true already establishes this is a safe read, so the annotation bar is met. The description adds value by disclosing what each result contains (default fields plus custom fields), which matters because there is no output schema. It does not discuss pagination limits or ordering behavior, keeping it short of a 5.

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

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

Two tight sentences with the purpose and return shape front-loaded and no filler. The trailing 'OpenPhone REST: GET /contacts' is mostly noise for an agent choosing a tool, slightly diluting an otherwise efficient description.

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 summarizes the returned contact fields, and the parameter surface is fully covered by the schema. For a simple optional-filter list tool with readOnly annotations, this is nearly complete; only pagination/ordering behavior is left unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including ranges and defaults. The description restates the externalIds and sources filters but adds no syntax or format detail beyond the schema, and says nothing about pageToken/maxResults — the expected baseline of 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 and resource ('List contacts in the workspace') plus the filtering scope, which is enough to separate it from most siblings. It does not explicitly name openphone_get_contact as the single-contact alternative, so sibling differentiation is only implied by the List/get split.

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

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

The description implies usage by stating the tool is for listing contacts with optional external-id/source filters, but it never states when to prefer this over openphone_get_contact or how it relates to the other list_* tools. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine beyond-schema context: results are ordered most-recent-activity-first and each conversation carries participants, assignee, and last-activity metadata. It stops short of describing pagination defaults or result volume behavior.

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

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

Two tightly packed sentences with zero filler: the ordering/scope clause comes first, then the return-shape note, then the REST mapping. Every clause carries information an agent can use.

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-only list tool with full schema coverage, the description supplies the missing pieces (sort order, returned per-item fields) and maps to the underlying endpoint. It would be complete at 5 if it noted pagination/nextPageToken behavior, since no output schema exists to convey that.

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 9 parameters is already documented with types and formats in the schema. The description only restates the filter categories (phone numbers, user, date ranges) without adding syntax, defaults, or interactions, 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 ('List conversations (threads)'), plus sort order and the filterable dimensions. The resource noun itself separates it from siblings like openphone_list_messages and openphone_list_calls, so an agent can route without opening any schema.

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

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

Usage context is only implied by the mention of optional filters ('optionally filtered by phone number(s), user, and created/updated date ranges'). There is no explicit statement of when to prefer this over sibling list tools and no exclusions or prerequisites, leaving routing guidance 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?

readOnlyHint=true already establishes the safe-read profile. The description adds value by naming the return fields (text, direction, status, timestamps) and the backing REST call, but discloses nothing about pagination behavior, ordering, or result limits beyond what the schema shows.

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 front-loaded sentences with no filler; the core scope lands first and the return fields and endpoint follow. Efficient, though the endpoint reference is marginally 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 annotations covering the read-only safety profile, a fully documented schema, and no output schema to explain, the description is nearly sufficient. It only lacks pagination/ordering context for a list tool, which is a minor gap.

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

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

Schema description coverage is 100%, so all seven parameters—including their formats (E.164, ISO-8601), constraints, and cross-tool hints—are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 is correct.

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

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

States a specific verb (List) and resource (messages) scoped to a conversation between an OpenPhone number and participants. It is clearly distinguishable from openphone_get_message (single message) and openphone_list_conversations. The REST endpoint mapping reinforces the precise purpose.

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

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

No when-to-use guidance relative to alternatives such as openphone_get_message for a single message or openphone_list_conversations. The description implies a listing scenario but never states when to prefer this tool or any prerequisites/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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context beyond that. It adds the dependency fact (most tools need a phoneNumberId) and the REST backing endpoint, but says nothing about pagination, result size, or permissions.

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 resource and return shape front-loaded, followed by the usage hint and endpoint mapping. The REST line is minor but useful for tracing behavior; 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 zero-required-parameter, read-only list tool with no output schema, the description covers purpose, return fields, and call ordering. Only pagination/volume behavior is unaddressed, a minor gap for a single-object list.

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

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

With one parameter at 100% schema coverage, the schema already documents userId fully, including its source tool. The description mentions phoneNumberId but never explains the userId scoping parameter, so it adds no meaning 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 and resource ('List the OpenPhone numbers in the workspace') and enumerates the returned fields (id, number, name, formatted number, assigned users, restrictions). This is enough for an agent to distinguish it from sibling list tools such as openphone_list_calls or openphone_list_users.

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?

'Usually the first call — most other tools need a phoneNumberId' gives clear context for when to reach for this tool. It stops short of naming specific alternatives or stating exclusions, but the ordering guidance is actionable.

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

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

The readOnlyHint=true annotation already establishes this is a safe read. The description adds the REST endpoint and the field set returned, which is useful, but says nothing about pagination behavior or ordering beyond what the schema covers.

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 purpose then use case then endpoint. Every clause 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 only optional parameters, a readOnly annotation, and no output schema, the description covers the essentials and pre-empts the missing output schema by listing returned fields. It could note pagination expectations but is otherwise complete.

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

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

Schema description coverage is 100% — both pageToken and maxResults are fully documented with ranges and defaults in the schema. The description adds no parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List workspace users') and even enumerates the returned fields (id, email, name, role). It is inherently distinguishable from siblings since no other tool lists users, though it does not explicitly name alternatives.

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?

'Use to find a userId for scoping other calls' gives a concrete when-to-use context, which is the primary reason an agent would call this. It stops short of naming exclusions or alternate paths, but the guidance 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; the description reinforces rather than contradicts it and adds useful context by naming the returned fields and the underlying REST endpoint (GET /webhooks). It does not discuss pagination, but for a zero-parameter read this is minor.

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

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

Two tight sentences with zero filler. The scope statement is front-loaded, followed by the read-only constraint and the endpoint reference.

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 and no parameters, yet the description compensates by listing the returned fields (id, url, events, status), giving the agent everything needed to call and interpret the tool.

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

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

The tool takes zero parameters, so per the rubric baseline is 4. The description adds no parameter detail, but none is needed for a parameterless call.

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 all webhooks configured in the workspace') and even enumerates the returned fields (id, url, events, status). No sibling tool covers webhooks, so the scope is unambiguous 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?

Clearly frames the context of use as a read-only inventory and explicitly rules out related operations ('does not create or delete webhooks'). There are no sibling webhook tools to route to, so the absence of a named alternative is not a real gap.

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

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

Annotations only carry destructiveHint=true, and the description materially extends that: it declares this is a WRITE action that sends a real message, discloses carrier cost, and names the A2P 10DLC registration prerequisite plus the underlying endpoint. It omits rate limits, idempotency/retry behavior, and delivery outcome, so not a 5.

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

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

Three tight sentences with the capability first, the critical WRITE warning second, and the REST endpoint last. No filler; each 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?

For a mutation tool with no output schema, the description covers the essential call-time risks (cost, registration) and the endpoint. It would be stronger with a note on what the caller gets back (e.g., sent message id) and failure modes for unregistered numbers, but nothing needed 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%, so the schema already documents every parameter including E.164 formatting, the 1-10 recipient cap, and the 1600-character body limit. The description's 'up to 10 recipients' merely restates the maxItems constraint and adds no new parameter-level 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?

Specific verb (send) plus resource (SMS/text message) and scope (from one of your OpenPhone numbers, up to 10 recipients). It is trivially distinguishable from read-oriented siblings like openphone_list_messages and openphone_get_message.

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

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

Gives clear real-world prerequisites before calling: it is a WRITE action, it incurs carrier cost, and it requires approved A2P 10DLC registration. It does not explicitly name alternatives or when-not-to-use (e.g., replies within an existing conversation), 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.