Spoke Phone MCP by usefulapi

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so "WRITE, destructive" largely restates structured data. The one piece of added value is the semantic consequence that the contact stops appearing in caller ID, plus the underlying REST endpoint; reversibility and permission requirements are still unstated.

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

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

Three short clauses, front-loaded with the write/destructive classification before the action and endpoint. Nothing is padded; every element 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 destructive, no-output-schema tool the description covers the action, scope, effect, and endpoint, and the schema's confirm field documents the approval gate. Only irreversibility and permission context are missing, 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 coverage is 33% – only confirm is documented in the schema. The description and the embedded path template (DELETE /phonebooks/{id}/contacts/{contactId}) do signal that phonebookId and contactId identify the parent phonebook and target contact, partially compensating, but no format or sourcing details are given.

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 (delete), resource (one contact in a phonebook), and scope (single contact), which clearly separates it from the get_/list_/save_phonebook_contact siblings. It doesn't explicitly name an alternative, but the verb+resource combination is unambiguous.

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

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

Usage is only implied by the verb; the description adds the consequence ("it stops showing in caller ID") but no explicit when-to-use/when-not or routing to alternatives such as save_phonebook_contact. An agent can infer intent but gets no guidance on preconditions beyond what the schema's confirm field states.

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 must add something beyond that — but it adds nothing about return shape, missing-id behavior, or whether recording data is included. The phrase 'one call record' only restates the name/title at a slightly finer grain.

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

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

A single front-loaded sentence with zero padding. Brevity is appropriate for a simple getter, though it borders on under-specification rather than tightness.

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 and one of two parameters undocumented, the description leaves real gaps: what fields a call record contains and what includeRecordingUrl changes. Annotations cover safety only, so for a tool whose output shape is unknown the description should say more.

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 50%: `id` is documented in the schema, but `includeRecordingUrl` has no description anywhere. The description says 'by call id' but adds no format details, and it silently omits the optional recording-URL flag, which is exactly the kind of behavioral choice a caller needs explained.

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 one call record by call id'), which clearly separates it from spokephone_list_calls (many) and spokephone_get_call_recording (a sub-resource). It doesn't explicitly name those siblings, but the singular 'one call record' plus the id-based lookup makes the distinction inferable.

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 guidance on when to use this versus spokephone_list_calls or spokephone_get_call_recording, and no mention of prerequisites, error cases (unknown id), or what happens after a call is deleted. The agent must infer usage entirely from the name and description.

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. The description adds real value by disclosing that the response contains a download URL, which is not otherwise documented since there is no output schema. It omits whether the URL expires, requires auth, or is a redirect, which would be helpful for a download-oriented tool.

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

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

A single tight sentence with the key payload ('details and download URL') front-loaded and no filler. It is arguably too short for the gaps it leaves, but nothing in it 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?

With no output schema, the description does minimal work to characterize the response ('details and download URL'), which is the right instinct. However, for a two-parameter tool where one parameter is undocumented and the returned URL's lifecycle is unstated, an agent is left guessing about acquisition of recordingId and URL validity.

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

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

Schema coverage is only 50%: 'id' is documented as 'Call id.' but 'recordingId' has no description at all. The phrase 'one recording of a call' hints at the call-id/recording-id pairing, but the description never names or explains recordingId, so it does not compensate for the documentation gap.

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 details and download URL of one recording of a call.' An agent can tell this is a single-recording fetch, and the mention of 'download URL' distinguishes it from siblings like spokephone_get_call or spokephone_get_transcript. It does not explicitly name those siblings, 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?

No statement of when to use this versus spokephone_get_call, spokephone_get_transcript, or spokephone_list_calls, and no note on how a recordingId is obtained or what to do if no recording exists. Usage is only inferable from the name and 'of one recording of a call'.

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 single-record read, so the description's bar is low. It adds nothing beyond that: no statement about what happens when the id does not exist (error vs empty), no authorization or scoping notes, and no indication of what an 'AI content analysis' actually contains.

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

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

A single front-loaded sentence with zero filler. Its brevity borders on under-specification rather than verbosity, but nothing in it is wasted.

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

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

There is no output schema, so the description carries the burden of explaining what comes back; it never says what fields or content an 'AI content analysis' result holds. For a tool whose whole value is returning a structured analysis, that is a material gap even though the call mechanics are simple.

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 0%, but there is only one trivially typed string parameter, and 'by id' does confirm the parameter identifies a content-analysis result rather than, say, a call. The description adds no format, sourcing, or error semantics (e.g., where the id comes from), so it does not fully compensate for the coverage gap.

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 ('Get'), a specific resource ('content-analysis result'), and the scope ('one ... by id'), which cleanly separates it from the sibling list_content_analysis and list_call_content_analysis. It stops short of explicitly naming those siblings, so a reader must infer the routing from the singular/plural contrast.

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

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

The phrase 'by id' implies the tool is only usable when an analysis id is already known, which hints that enumeration belongs to the list siblings. There is no explicit statement of when to use this versus list_content_analysis or list_call_content_analysis, and no mention of what to do if the id is unknown.

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 description does not need to re-state safety. It adds that directory entries can be users, teams, or devices, which is useful context. It does not describe what happens when an entry is not found, permission requirements, or the shape of the returned entry.

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

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

The description is a single, front-loaded sentence with zero wasted words. It is appropriately sized for a simple one-parameter retrieval tool.

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

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

For a simple getter with annotations covering read-only safety, the description is minimally adequate: an agent knows to supply an entry id and expects one directory entry back. It is missing usage boundaries against sibling tools and any error/not-found context, leaving clear gaps.

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 0% for entryId, so the description must compensate. It only says the lookup is 'by entry id,' which essentially restates the parameter name and does not explain format, source, or whether entryId corresponds to user/team/device identifiers.

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

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

The description states a specific verb (Get), a specific resource (one directory entry), and enumerates the entry types (user, team, or device). This distinguishes it from a bulk list operation, though it does not explicitly contrast with sibling getters like spokephone_get_user or spokephone_get_phonebook_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?

Usage is implied by the phrase 'by entry id' — the tool is for retrieving a single entry when its id is known. However, there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as spokephone_list_directory or type-specific getters.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered by structured data, and the description adds essentially nothing beyond it. It does not state what happens when the id does not exist, whether the result is cached, or any permission requirements. With annotations carrying the only real behavioral signal, the description contributes little.

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 short sentence with zero filler, and the key phrase is front-loaded. It is efficient, though the brevity edges into under-specification rather than true conciseness.

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 and only a readOnlyHint annotation, the description leaves the agent without knowing what a 'location' object contains or what a missing id returns. For a fetch tool in a large sibling set, more context would be needed to call it confidently.

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 0% for the single locationId parameter, so the description must compensate and it only contributes the phrase 'by id'. That confirms locationId is a lookup key, but it adds no format, source, or example detail (e.g. where to obtain a valid id). Marginal value over the schema.

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

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

The description gives a specific verb and resource ('Get one location'), and 'one' signals single-item retrieval versus the sibling list_locations. However, it offers no differentiation from the other dozen-plus 'get_*' siblings (get_user, get_trunk, get_phonebook, etc.), so an agent gets no help disambiguating beyond the resource noun in the tool 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?

There is no when-to-use guidance, no mention of list_locations as the alternative for browsing, and no prerequisites or error context. The agent must infer usage entirely from the name and schema.

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

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

The annotations already declare readOnlyHint=true, so the description is not required to establish that this is a safe read. It usefully notes that the reply embeds a page of contacts, which is more than the annotations provide. However, it does not describe ordering, error behavior, or whether the page is of the phonebook's full contact set.

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

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

The description is two compact sentences with no filler. The core operation is stated first, and the id dual-purpose caveat follows immediately. Every sentence adds 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 read tool with no output schema, the description conveys the return shape (phonebook plus a page of contacts) and the id semantics. It omits any mention of the search parameter's behavior and how to advance pages. That leaves an agent to infer some of the usage from 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 coverage is 50%. The description adds real meaning for the id parameter: it may be either a phonebook id or a user's email address for a personal phonebook. That id field has no schema description, so this is valuable. It says nothing about the undocumented search parameter (minLength 3), and next/limit rely on their schema descriptions.

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?

Uses a specific verb and resource: 'Get one phonebook and a page of its contacts.' This clearly distinguishes a single-record fetch from the sibling list tool spokephone_list_phonebooks. It does not explicitly name the retrieval of individual contacts (spokephone_get_phonebook_contact), but the 'page of contacts' phrasing is distinctive enough.

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

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

The intended use (fetch a single phonebook) is only implied by the contrast with the list tool. The description offers no guidance on when to prefer this over spokephone_get_phonebook_contact or spokephone_list_directory. It also does not explain prerequisites such as required permissions or what an invalid id returns.

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, but the description adds nothing beyond restating the title. It says nothing about behavior on a missing contact, permissions, or response shape, which is the extra context this tool should supply.

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

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

A single short, front-loaded sentence with no filler. It is efficient, though its brevity borders on under-specification rather than tightness.

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 two-parameter read tool with annotations and no output schema, the description is minimally viable. It omits the meaning of one required parameter and any note on missing-contact behavior, which a caller would want.

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

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

Schema description coverage is only 50%: 'id' is documented as the phonebook id, but 'contactId' has no description. The description implies a two-level lookup (contact within a phonebook) but never clarifies what contactId actually identifies, so it only partially compensates for the gap.

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 one contact of a phonebook'), which cleanly separates it from the list-style siblings like spokephone_list_phonebooks. It does not explicitly differentiate from spokephone_get_phonebook or the save/delete contact siblings, but the singular 'one contact' makes the scope clear.

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

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

There is no guidance on when to use this instead of spokephone_list_phonebooks, spokephone_get_phonebook, or spokephone_get_directory_entry, nor any stated preconditions. The agent must infer selection from the name alone.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds no behavioral context beyond that: it does not state what happens when the id is not found, whether the transcript may be empty or incomplete, or what the retrieval 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?

The description is a single short sentence with no filler and the retrieval condition is front-loaded. However, its extreme brevity leaves substantial gaps that a slightly longer sentence could have closed, making it minimally adequate rather than well-structured.

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?

This is a simple one-parameter read tool with annotations covering safety, but there is no output schema, so the description should describe what a transcript result contains or its shape. It also omits error/not-found behavior, leaving the agent without enough information about the outcome of the 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 description coverage is 0% for the single required id parameter, so the description must compensate and does not. 'By id' merely restates that the parameter identifies a transcript; it adds no format, source, or validity details beyond what the schema's type and required field already convey.

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

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

The description states a specific verb and resource ('Get one transcript') and specifies single-item retrieval 'by id', which implicitly distinguishes it from list_transcripts. It does not explicitly differentiate itself from the closely related spokephone_get_transcript_segments sibling, so it falls short of a 5.

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

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

The phrase 'by id' implies the tool is used when a transcript id is known, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as get_transcript_segments or list_transcripts. An agent must infer the selection criteria entirely.

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 that results are per-speaker segments of a single transcript, which is useful context beyond the annotation. It doesn't mention ordering, pagination, empty cases, or what happens if the transcript has no diarization.

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 with no waste. Very short, though at the cost of any usage or behavioral detail.

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 one-param read tool with annotations and no output schema, this is minimally adequate. Still, the description gives no hint of return shape (speaker labels, timestamps, text), which an agent needs since there is no output schema to consult.

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 'id' with 100% schema description coverage ('Transcript id.'), so the schema carries the semantics. The description merely implies the id identifies a transcript but adds no format or provenance detail. 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) and resource (per-speaker segments of one transcript), which distinguishes it from spokephone_get_transcript (whole transcript) and spokephone_list_transcripts. However, it doesn't explicitly name those siblings or clarify whether segments are the same as diarized speaker turns, leaving the distinction implicit.

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

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

No guidance on when to use this versus spokephone_get_transcript or spokephone_list_transcripts. An agent must infer that this is for speaker-level detail rather than the full transcript.

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 non-destructive read, and 'Get' is consistent with that. However, the description adds nothing behavioral beyond the annotation: no statement of what happens when the id does not exist, whether the trunk config is returned in full, or any auth/scope requirement.

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 short sentence with no filler and the retrieval verb front-loaded, which is efficient. But the brevity crosses into under-specification rather than tight, information-dense writing.

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, no parameter descriptions, and only a readOnly hint, the description is the sole carrier of semantics and provides almost none. For a simple get-by-id tool a short description can suffice, but this one leaves the return shape and error behavior entirely undefined.

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 0%, so the description must carry the burden of explaining trunkId, but 'by id' only restates the field name. It does not say whether the id is a numeric trunk id, a SIP trunk sid, or where to obtain 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 ('Get') and resource ('SIP trunk') plus the singular-by-id scope, so an agent can distinguish it from a list operation without opening the schema. It does not explicitly name spokephone_list_trunks as the alternative, keeping it 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?

There is no when-to-use guidance, no prerequisite (e.g. having obtained a trunkId from spokephone_list_trunks), and no mention of exclusions or alternatives. Usage must be inferred entirely from the name.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description needn't restate safety. It adds one useful piece of context — that availability data comes back — but says nothing about error behavior for unknown ids or what the user object contains.

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

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

A single front-loaded sentence with no filler. It is arguably over-compressed for a tool whose return shape is undocumented, but nothing is wasted.

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

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

For a one-parameter read with no output schema, the description covers the essential lookup and hints at the payload. It stops short of describing the returned user fields or failure modes, leaving modest gaps an agent would have to discover by calling.

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 0%: the lone 'id' parameter has no description in the schema. The description partially compensates by identifying it as a user id (not a location or contact id), but gives no format guidance (numeric vs UUID-style).

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 one Spoke user') and adds the scope 'one' plus the return payload ('with availability'), which cleanly separates it from spokephone_list_users and spokephone_list_location_users. It doesn't name a sibling explicitly, but the singular/plural distinction is clear.

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

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

The phrase 'by user id' implies you must already know the id, which nudges toward list_users for enumeration, but no alternative or precondition is stated outright. Usage is inferable rather than prescribed.

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 description carries a lower burden, but it adds nothing beyond that: no statement about error behavior for unknown or deleted ids, no auth or rate-limit context, and no indication of what a webhook subscription record contains.

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

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

A single short sentence with the resource and lookup key front-loaded; nothing redundant. It is nearly the minimum viable statement and wastes no words.

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 getter with readOnly annotations this is close to adequate, but with no output schema the description gives no hint at the shape of the returned webhook object or what happens when the id is not found.

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 0%, so the description must compensate. It does clarify that the lone 'id' parameter identifies the webhook subscription (rather than a call, user, or other resource), but it adds no format, prefix, or validity detail beyond that.

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

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

States a specific verb ('Get') and resource ('one webhook subscription'), with scope limited to a single item via 'by id'. This implicitly contrasts with the sibling spokephone_list_webhooks, though it never names that alternative.

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

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

The phrase 'by id' implies the tool is only for the case where an id is already known, but there is no explicit when-to-use, when-not, or pointer to spokephone_list_webhooks for discovery.

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 only needs to add context beyond that. It adds almost none: no note on pagination behavior, what an empty result means, whether artifacts are filtered by type, or what the returned items look like. The parenthetical "(summaries etc.)" is the only added signal.

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

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

A single front-loaded sentence with no filler; the verb, the data domain and the per-call scope are all in the first few words.

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?

The schema is fully documented and the tool is a simple paginated read, but with no output schema the description should say what a result entry is, and the overlap with the sibling get_content_analysis / list_content_analysis tools is left unresolved. Adequate but with clear gaps.

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 id, next, limit and artifact are all documented in the schema, making 3 the baseline. The description touches on the 'one call' scope and 'summaries' (related to the artifact param) but adds no syntax or usage 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 (List) and resource (Enlighten AI content-analysis results) scoped to one call, which is clearer than the title alone. It does not, however, distinguish itself from the sibling spokephone_get_content_analysis or spokephone_list_content_analysis, so the agent must infer which one returns per-call artifacts.

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?

"stored for one call" implies this is the per-call variant, giving implied guidance for when to pick it over the global list. But there is no explicit when/when-not statement and no mention of the alternative sibling tools (get_content_analysis, list_content_analysis).

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 then adds value with the default sort direction, the returned payload shape { meta: { next }, calls }, and the fact that recording URLs are included by default and in-progress calls are excluded. It omits any note on rate limits or whether includeActive changes result volume, which keeps it below 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: what it lists, how to control ordering and filtering, and what comes back. The default-ordering caveat is front-loaded because it is the most likely source of agent error.

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 nine-parameter read tool with no output schema, the description supplies the return envelope and the key defaults, and the schema covers the rest. It is slightly thin on pagination flow (next/limit interplay) but an agent has enough to call it correctly.

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

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

With 100% schema description coverage, the schema already documents every parameter including the sortOrder enum semantics and cursor usage. The description mostly restates the schema's ordering and filtering facts rather than adding format or edge-case 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?

It states a specific verb and resource ("List call records") and enumerates the returned fields (caller, direction, duration, assigned user/team, recording URLs), which clearly separates it from spokephone_get_call. However, it never names a sibling tool or says explicitly that single-call retrieval belongs to get_call.

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?

"pass sortOrder descending for the latest calls" and "Filter by time window or the external party's number" give concrete usage context for the two main axes (ordering and filtering). No when-not guidance or alternative tool routing is offered, but the usage 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main contribution is the entitlement gate, which is genuinely useful and not in the schema or annotations. It says nothing about pagination defaults, result ordering, or what a page of results looks like beyond the schema's own next/limit hints.

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

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

Two short sentences: the operation and its entitlement gate first, then the available filter axes. No restatement of the title and 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 read-only paginated list with no output schema, the definition covers the operation, the access prerequisite, and the filter surface, which is most of what an agent needs. The remaining gap is the unmentioned contactNumber parameter and any hint about what a content-analysis result contains, but neither blocks a correct 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 63%, and the description adds a semantic grouping ('filter by time, source, participant or artifact name') that maps loosely onto since/before, sourceId, participantId and artifact. It does not mention contactNumber at all, nor how the time window relates to recording vs. transcript start, so the uncovered parameters stay covered by neither source.

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 AI content-analysis results') that an agent can act on immediately. However, the sibling set contains both spokephone_list_call_content_analysis and spokephone_get_content_analysis, and the description makes no attempt to distinguish this tool from either, leaving the agent to guess which listing is appropriate.

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?

'Needs the Enlighten entitlement' is a real prerequisite that prevents a failed call, and the filter dimensions hint at how the tool is scoped. But there is no statement of when to prefer this over list_call_content_analysis or get_content_analysis, so the routing decision is left implicit.

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

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

The readOnlyHint annotation already establishes safety, and the description adds useful behavior beyond that: live availability, mutual-exclusivity rules for lookup identifiers, and the response shape { meta: { next }, entries }. It does not contradict 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?

The description is three tight sentences with no filler. It front-loads the main purpose, then the lookup constraint, then the return shape.

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 seven-parameter read-only listing tool without an output schema, the description supplies the return shape and a key parameter constraint. The main remaining gap is that the two boolean filtering parameters are undocumented in both schema and description.

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 71%, and the description adds a crucial semantic rule not captured by the schema: exactly one of extension, phoneNumber, or ivrKey may be used for lookup. It does not explain includeSuspendedUsers or includeHiddenCallGroups, but it substantially improves understanding of the core lookup parameters.

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

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

The description clearly states the verb and resource: list or search the unified Spoke directory covering users, teams, and devices, including extensions and live availability. It differentiates itself from narrower list_users/list_teams siblings, but does not explicitly point to get_directory_entry as the alternative for single-entry retrieval.

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 gives an important lookup constraint: exactly one of extension, phoneNumber, or ivrKey may be used to look up an entry. However, it does not explicitly say when to use this tool versus get_directory_entry or the narrower list_user/list_team tools, leaving usage guidance mostly implied.

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

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

readOnlyHint=true already declares the safety profile, so the description's only added value is the organisational scoping ('of the organisation'). It says nothing about pagination, result ordering, or whether inactive locations are included — relevant because the schema exposes cursor paging.

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

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

A single short sentence with the resource front-loaded and no filler. It is arguably over-terse rather than padded, so conciseness itself is not a problem.

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

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

For a simple read-only list with an annotated safety profile and fully described parameters, the essentials are covered, but an agent gets no hint that results are paginated or how the org-wide scope interacts with other location-related tools. That gap keeps it at minimum-viable completeness.

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

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

Schema description coverage is 100%: both 'next' (cursor semantics, first page) and 'limit' (default 100, max 1000) are fully documented in the schema. The description adds no parameter meaning beyond that, which matches the baseline.

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

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

States a specific verb and resource ('List the locations'), and the singular sibling spokephone_get_location makes the plural/list nature distinguishable. It does not explicitly contrast itself with siblings such as get_location or list_location_users, so it stops short of a 5.

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

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

No guidance on when to use this versus spokephone_get_location (single location) or spokephone_list_location_users. Usage is only implied by the verb 'List'; there are no prerequisites, exclusions, or alternatives named.

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 safe read profile, so the description carries little burden there. It adds the assignment concept (users 'assigned to' a location, which hints at member records rather than user entities) but says nothing about pagination behavior, result ordering, or whether inactive users are included.

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

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

A single compact sentence with no filler, and the scoping qualifier sits right next to the verb. Nothing to trim, though nothing is front-loaded beyond the purpose itself.

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

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

For a simple read-only list tool with only three parameters and a readOnly annotation, this is close to sufficient, but with no output schema the agent gets no hint of what a user record contains or how paging metadata is returned.

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 67% — cursor and limit are fully documented in the schema, while locationId has no description but is self-explanatory and reinforced by the description's 'assigned to one location'. Baseline 3 applies; the description adds no syntax or format detail.

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 users') plus a scoping constraint ('assigned to one location'), which distinguishes it from the unfiltered spokephone_list_users without naming it. Clear, but the sibling differentiation is only implicit.

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

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

Usage is implied by the 'one location' scoping — an agent can infer it should use this instead of the global list tool when a locationId is known. However, no alternatives are named and 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?

readOnlyHint=true already covers the safety profile, so the description's job is to add behavior it doesn't. It does: it discloses that contacts are returned nested by default (an expensive detail an agent would otherwise not anticipate) and offers the limit 0 escape hatch to avoid that cost. It omits pagination/truncation behavior beyond the schema's page-size note.

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, no filler, and the core operation plus the parenthetical definition come first with the special-case tip second. Every clause carries information an agent needs.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers what is returned ("each with its contacts") and the main cost-control lever. It could say slightly more about result shape or default ordering, but nothing essential to calling 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 coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: the schema says limit has a minimum of 0 and a default of 100 without explaining what 0 does, and the description fills that gap. The interaction between search and excludeEmpty (search narrows contacts, excludeEmpty drops phonebooks left empty) is left to infer.

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 shared phonebooks") and even defines the domain concept ("CRM contact containers used for caller ID"), so an agent knows exactly what it gets back. It does not explicitly distinguish itself from the get_* siblings (get_phonebook, get_phonebook_contact), relying on the list/get convention instead of naming the boundary.

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 limit 0 to list phonebooks without contacts" is a genuine usage instruction, but only for one narrow calling pattern. There is no guidance on when to choose this over spokephone_get_phonebook, or on how search/excludeEmpty interact when browsing versus filtering.

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's real contribution is disclosing that each team carries its members and availability. That is useful beyond the annotations, but it says nothing about result set size, pagination behavior (despite a cursor param), or what availability means operationally.

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

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

A single sentence with no filler, front-loading the verb and resource and then the payload. Nothing in it could be cut without losing 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 read-only, zero-required-param list tool with a fully documented schema and no output schema, this covers purpose and returned fields adequately. The only real gap is that pagination is never mentioned in prose, so an agent must read the schema to learn results are paged.

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%: both params are documented with the cursor source (meta.next) and the page-size default and max, so the schema does the heavy lifting. The description adds no parameter detail of its own, which is the expected baseline case.

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 Spoke teams") and disambiguates the term by equating teams with call groups, plus names the data included (members, availability). It does not explicitly contrast with siblings such as list_users or list_location_users, which an agent might otherwise consider for people-related queries.

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 one-line hint that members and availability are returned implies this is the browsing tool rather than a per-user lookup, but there is no explicit when-to-use, no exclusions, and no prerequisite or permission guidance. Usage is inferable 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 that results cover both call and voicemail transcripts, which is useful scoping context, but says nothing about pagination behavior or result ordering beyond what the schema's next/limit fields imply.

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

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

Two short sentences with the resource up front and the filtering note second. No filler, though it's terse enough that it leaves gaps rather than being optimally structured.

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 6 optional params, no output schema, and no annotations beyond readOnlyHint, the description is minimally adequate. It doesn't clarify what a transcript object contains or how sourceContextId aligns with sourceId, leaving a gap an agent would have to guess at.

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 67%, with since/before/limit/next well documented in the schema. The description only loosely maps 'time window' and 'source' to those params and adds nothing for sourceContextId or the millisecond-timestamp format, so it's baseline-equivalent to the schema rather than additive.

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 call and voicemail transcripts'), which distinguishes it from the singular get_transcript and get_transcript_segments siblings. It doesn't explicitly name those siblings, but the plural/list framing makes the distinction inferable.

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?

'Filter by time window or source' hints at when the filters are useful but gives no explicit when-to-use vs. when-to-call-get_transcript guidance. The alternative and its selection condition are left implicit.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, so the description's main job is to add context beyond that. It does not describe the return structure, pagination behavior, authorization needs, or any listing constraints, leaving behavioral details almost entirely to structured fields.

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

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

The description is a single front-loaded sentence with no filler, which is appropriate for a simple list tool. The trailing domain phrase is slightly ambiguous but does not significantly harm structure.

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 low-complexity read-only list tool with fully documented parameters, the description is minimally adequate. However, with no output schema and no mention of pagination or return shape, it leaves some context an agent might want before invoking 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?

Schema description coverage is 100%, and both parameters include clear inline documentation for the cursor and page size. The description adds no additional parameter meaning beyond what the schema already provides, which matches the baseline for fully documented schemas.

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

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

The description uses a clear verb, 'List', and a specific resource, 'SIP trunks', so the agent can identify the operation. It does not explicitly distinguish the tool from the sibling 'spokephone_get_trunk', and the qualifying phrase about overlaying a legacy PBX adds domain flavor but not operational 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 description gives no guidance on when to use this tool instead of related tools such as spokephone_get_trunk or the other list endpoints. It also does not mention pagination usage, even though the schema exposes cursor and page-size parameters.

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 value by disclosing that results reflect live availability and that only active users are returned, though it says nothing about result volume, pagination, or ordering.

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

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

Two short sentences, zero filler, and the core purpose plus live-availability trait are front-loaded before the optional filter detail.

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

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

For a simple read-only list with one optional parameter and annotations covering safety, the description is nearly sufficient. The only gap is that, with no output schema, the shape of the returned user objects and the 'availability' field is never described.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Return only the user with this email address', so the failure mode the description must cover is small. The description's 'filter by email address' restates the schema rather than adding format or matching semantics (exact match vs partial).

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 active Spoke users') plus the distinguishing detail that results carry real-time availability. It does not explicitly contrast with siblings like spokephone_get_user or spokephone_list_location_users, so the boundary is inferred rather than stated.

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

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

'List active Spoke users' implies inactive users are excluded, and 'Optionally filter by email address' hints at the narrowing path, but there is no explicit when-to-use guidance or routing to spokephone_get_user for single-lookup cases.

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 a safe read, so the description only adds the account-level scope. It says nothing about pagination behavior (cursor-based, default 100) or whether results are ordered/filtered, which is the kind of context that would earn a higher score.

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

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

A single front-loaded sentence with no filler; nothing is wasted. It is, however, too terse to carry any routing or behavioral detail.

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

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

For a simple read-only list tool with pagination documented in the schema and no output schema, the description is minimally sufficient. It omits any hint of the returned webhook fields or whether an empty list is possible, leaving gaps an agent might want 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 coverage is 100% and both parameters (next cursor, limit with max 1000) are fully documented in the schema. The description adds no parameter meaning beyond that, 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 webhook subscriptions') plus the scope ('of the account'), which separates it from spokephone_get_webhook (single fetch). It does not explicitly name the sibling, so a 4 rather than 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?

There is no when-to-use guidance, no mention of the alternative get_webhook for single lookups, and no prerequisites such as needing webhooks configured. The agent must infer that this is the enumeration tool from the name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is known; the description adds the crucial scope of that destructiveness ('replacing any contact with the same contactId, other contacts are untouched') and the downstream effect ('contacts feed caller ID'). It stops short of permission/auth or rate-limit details, but that is a minor gap given 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?

Three short sentences, front-loaded with the WRITE marker and the destructive scope, then the id convention, then the purpose, then the endpoint. Nothing is redundant and the most decision-critical fact comes first.

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

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

For a 9-parameter destructive write with no output schema and no annotations beyond hints, the description covers the essential behavior: upsert semantics, blast radius, phonebook id aliasing, and caller-ID impact. What remains thin is the undocumented optional fields and any statement of what the call returns.

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

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

Schema coverage is only 44% with 9 parameters, so the description needs to compensate; instead it largely restates what the schema already says (phonebookId as email, contactId reuse for replacement) and never mentions the name, company, jobTitle or emails fields. The majority of parameters remain undocumented in both places.

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 ('add a contact to a phonebook') and immediately qualifies it with upsert semantics ('REPLACING any contact there with the same contactId'), which distinguishes it from the get/delete phonebook-contact siblings. The PUT endpoint reference reinforces the exact resource addressed.

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

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

The description implies when to use it (adding or replacing a contact) and notes that the phonebook id can be a user email for a personal phonebook, which is a useful routing hint. However, it never says when to prefer this over siblings or states any prerequisites/exclusions for a destructive upsert.

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 non-readOnly, openWorld and non-idempotent, but the description adds the crucial business consequence: a real message leaves the system and lands in the Spoke conversation record. It also discloses the SMS-enabled-number prerequisite and the human-confirmation gate. Remaining gaps are cost, per-message rate limits, and delivery failure 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?

Four short sentences, front-loaded with the write marker and the side effect, then prerequisites. The trailing "POST /conversationMessages" is transport detail an agent does not need and is the one element not earning 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 9-parameter outbound-send tool with no output schema, the description covers the essential mental model: what physically happens, who sends, what must be confirmed, what infrastructure is required. It is nearly complete, missing only reply-routing and notification semantics that a caller must currently infer from the stub enum names in 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 coverage is 78%, so the schema already explains `to`, `body`, `confirm`, and the fromNumber/fromUserEmail alternative. The description reinforces the group-MMS consequence of multiple recipients but says nothing about `routingAction`, `notificationMode` (which has no schema description at all), or `conversationName`. That leaves the two enum parameters unexplained in both places.

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

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

Opens with an explicit verb+resource marker ("WRITE: send a real SMS") and states scope precisely: single number or group MMS, from a company number or a user's conversation number. No sibling tool does anything comparable, so the boundary is unambiguous from the first clause.

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?

"Confirm the recipient and text with the user first" and "Needs an SMS-enabled number" give concrete preconditions for invocation, which is more than most mutation tools offer. It stops short of saying when NOT to use it (e.g. internal-only notifications, unsolicited outreach), so it is clear context without exclusions.

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