DialMyCalls MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's real contribution is 'Calls already placed are not undone' — a precise disclosure of partial irreversibility that the annotations cannot express. It stops short of stating error behavior for finished broadcasts or any permission requirements.

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

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

Two short sentences, zero waste, with the scope constraint front-loaded and the irreversible-effect caveat second. Nothing to trim.

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 destructive tool with full annotation coverage and no output schema, the description covers what gets destroyed and what does not. A minor gap remains around the outcome when the target broadcast is already finished or the ID is invalid.

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 documented with a UUID pattern, so the schema carries the burden. The description adds no format or lookup guidance beyond what the schema provides, making the baseline 3 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 (cancel) plus resource (call broadcast) and narrows scope to 'outgoing or scheduled ... that has not finished.' The call-vs-text split against the sibling dialmycalls_cancel_text is unambiguous from the resource name 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?

'That has not finished' implies the applicable state, but the description never routes the agent to alternatives (e.g., dialmycalls_cancel_text for text broadcasts) or states what to do when the broadcast is already complete. Usage is inferable rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context beyond those flags by stating that texts already sent are not undone, clarifying the blast radius of the cancellation.

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

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

Two short sentences, front-loaded with the action and immediately followed by the key caveat. 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 single-parameter mutation with safety annotations and no output schema, the description covers the key behavioral detail (already-sent texts remain sent). It does not describe the response or what happens if the broadcast has already finished, but those gaps are minor.

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

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

There is only one parameter, and the schema documents it at 100% coverage ('The text broadcast id'). The description adds no additional meaning about the id format or source, so this is the baseline score for a fully documented 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 names a specific verb and resource ('Cancel a text broadcast') and scopes it to outgoing or scheduled broadcasts that have not finished. This lets an agent distinguish it from dialmycalls_cancel_call and dialmycalls_send_text without opening either schema.

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

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

It states a clear precondition for use: the broadcast must not have finished. It does not explicitly name alternatives such as dialmycalls_cancel_call, but the call-vs-text distinction is self-evident from the tool names.

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, idempotentHint=false and destructiveHint=false, so the mutation profile is known. The description adds one genuinely useful trait beyond that - no message is dispatched to the new contact. It omits what happens on a duplicate phone number, which matters given idempotentHint=false.

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 clauses, both front-loaded: the core action with its hard requirement first, then the no-side-effect assurance. 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 7-parameter creation tool with no output schema and adequate annotations, the essentials are covered: what it creates, what is mandatory, and that nothing is sent. The remaining gap is duplicate handling and whether an id is returned for later update 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 57%, and the description confirms phone is required and group_ids optional, matching the schema. It adds no format or placement detail for email, firstname, lastname or extra1, relying on the schema and self-explanatory names for those.

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 ('Add a contact ... to the contact list') and flags the required field (phone) plus optional group membership. It is clear enough to separate from dialmycalls_update_contact and dialmycalls_send_text, though it never names a sibling explicitly.

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

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

'Sends nothing to the contact' implicitly tells the agent this is a data-only operation rather than a messaging one, which is useful routing context. However, there is no explicit guidance on when to create versus update an existing contact, nor any stated prerequisites such as valid group ids.

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 flag this as a non-read-only, non-destructive, non-idempotent mutation. The description adds real value with 'Sends nothing' (no messages dispatched) and 'empty' (no contacts added), but omits that repeated calls create duplicate groups and says nothing about the returned group identifier.

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

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

Two short sentences, front-loaded with the action, with zero filler. Every clause ('empty', 'Sends nothing') carries distinct meaning.

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

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

A simple one-parameter creation tool with full schema coverage, so little is required. Still missing is what an agent gets back (a group ID is presumably needed to add contacts later) and whether names must be unique.

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

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

Only one parameter (name) and schema coverage is 100%, so the schema fully documents it. The description adds no constraint information such as name uniqueness or length beyond what the schema already 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 the specific verb and resource (create a contact group) and clarifies it starts empty, which distinguishes it from dialmycalls_create_contact. The phrase 'Sends nothing' separates it from the send_call/send_text siblings, though no sibling is named explicitly.

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

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

Usage is only implied: create a group presumably to later add contacts and send to it. There is no explicit statement of when to use this versus dialmycalls_create_contact or how it pairs with send tools.

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

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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive create operation. The description adds useful behavioral context by confirming that no call is placed and nothing is sent, which is beyond what the annotations state.

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

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

Two compact sentences, front-loaded with the action and clarified immediately with scope limits. There is no wasted text.

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 description covers what the tool creates and what it does not do, which is sufficient alongside a fully documented input schema and annotations. It could optionally mention what the create operation returns, but no output schema exists and this is not a major 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 four parameters and their enums are already documented. The description adds no parameter-specific details, which is acceptable given the schema's completeness.

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: create a text-to-speech voice recording. It also distinguishes this from sibling send/call tools by clarifying that it makes no call and sends nothing, and situates the result as something a broadcast can play.

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 clear usage context: this prepares a recording for later playback by a call broadcast. The explicit 'makes no call and sends nothing' rules out confusing it with send_call or send_text, though it does not name those alternatives directly.

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 safety profile, so the description only needs to add context. It adds the useful domain fact that credits are consumed by calls and texts, but says nothing about response shape, error/empty states, or rate-limit behavior for a metered account endpoint.

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

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

A single sentence, front-loaded with the verb and resource, with the two returned values enumerated in a compact parenthetical. No filler and nothing to trim.

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 0-param read-only getter with no output schema, the description does the essential work by naming the fields the response contains. It stops short of describing the full response envelope, but an agent has enough to call it and expect account credits and creation date.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description's mention of credit and creation-date fields is a useful hint at the payload without competing with any schema documentation.

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

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

Specific verb+resource ('Get the account') plus a concrete statement of the two returned facts: credit balance and creation date. It is clearly distinct from the contact/group/call/text siblings, which all operate on other resources, though it does not explicitly say so.

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: the parenthetical that 'calls and texts spend credits' hints this should be checked before sending, but there is no explicit when-to-use statement or exclusion. For a zero-param read-only getter this is tolerable but thin.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses what the response contains (name, recipients, credit cost, send time, pending_cancel), which matters since there is no output schema, but it says nothing about not-found behavior or whether missing ids error out.

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

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

A single self-contained sentence with the operation front-loaded and no filler; every clause earns its place by naming the returned 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 single-parameter lookup with no output schema, listing the key returned fields makes it essentially callable as-is. Only the lack of error/not-found semantics and sibling routing keeps it from a 5.

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

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

Only one parameter and the schema documents it at 100% coverage, including the UUID pattern, so the schema carries the weight. The description adds no syntax or sourcing detail beyond "by id" — baseline 3 applies.

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

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

States a specific verb and resource ("Get one voice call broadcast by id") and enumerates the notable returned fields. It is distinguishable from dialmycalls_list_calls (plural listing) and dialmycalls_get_text, though it never names those siblings explicitly.

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

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

There is no explicit guidance on when to use this versus dialmycalls_list_calls or dialmycalls_list_call_recipients, and no statement of prerequisites (e.g. that the id must come from a prior list call). The "by id" phrasing only weakly implies single-record lookup versus listing.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds almost no behavioral context beyond restating the name: no note on what happens for an unknown id, no error semantics, no indication of response shape. Annotations carry nearly all the weight here.

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

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

A six-word, front-loaded sentence with no filler. It is efficient, though its brevity borders on under-specification rather than optimal compression.

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, the essentials are covered. Still, nothing is said about the lookup failing or what the caller receives, which leaves a small gap given there is no output schema.

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

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

Schema description coverage is 100% and the single id parameter is fully specified with a UUID pattern in the schema. The description's 'by id' adds no syntax or format detail 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 ('Get') and resource ('contact') with the singular scope ('one contact by id'), which implicitly distinguishes it from the sibling list_contacts. It is clear, though it does not name the sibling explicitly.

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

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

The phrase 'one contact by id' implies you need an id and want a single record rather than a list, but there is no explicit when-to-use guidance or mention of alternatives such as dialmycalls_list_contacts. Usage 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?

readOnlyHint=true already declares the safety profile, so the description's added value is the return shape ('name, contacts_count'), which is genuine context since no output schema exists. It says nothing about not-found behavior or error handling.

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 resource, the identifying key, and the returned fields all appear immediately.

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-by-id tool with rich schema coverage, annotations, and no output schema, the definition covers input, output preview, and safety profile adequately. Only failure/empty-result behavior is left unstated.

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

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

There is one parameter with 100% schema coverage, including a UUID pattern and description, so the schema carries the semantics. The description's 'by id' merely restates the parameter's role without adding format or constraint 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 ('Get') and resource ('one contact group') with the key lookup key ('by id'), and previews the returned fields. It does not explicitly contrast itself with dialmycalls_list_groups, but 'one' versus a list is a readable distinction.

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

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

Usage is only implied: 'by id' signals this is the lookup path when an id is already known, while dialmycalls_list_groups or list_contacts_in_group cover enumeration. Neither alternative is named, so the agent must infer the routing.

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

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

The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds no behavioral context beyond restating the action, such as error behavior or any retrieval constraints.

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

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

The description is a single short sentence with no wasted words and immediately front-loads the action and resource.

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-parameter read tool with full schema coverage and a readOnly annotation, the definition is minimally adequate. However, with no output schema, it could say more about what the single incoming text record contains 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 100%, and the schema documents the required id parameter with a UUID pattern. The description only repeats that the lookup is 'by id' and adds no format or semantic 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?

The description states a specific verb and resource: get one incoming text message by id. It clearly distinguishes fetching a single incoming text from list_incoming_texts, though it does not explicitly mention the related get_text 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?

The phrase 'by id' implicitly signals that this tool is used when the caller already has a specific incoming text id, but there is no explicit guidance on when to use this versus list_incoming_texts or get_text.

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 goes further by disclosing the shape of the response — an audio file URL and a processed/ready flag — which matters for a caller deciding whether the recording can be used yet. It stops short of describing error behavior for an invalid or nonexistent id.

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

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

One sentence, front-loaded with verb and resource, with the return-value parenthetical as the only added clause. Nothing is wasted or buried.

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 tool with no output schema, the description covers the essential contract: single-record lookup keyed on id, and the two return fields an agent would act on. A note about invalid/missing ids would close the last 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?

There is a single parameter with 100% schema description coverage plus a UUID pattern, so the schema already carries the full burden. The description's 'by id' adds no format or sourcing detail beyond it, making baseline 3 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 and resource ('Get one voice recording by id') and scopes it to a single item, which implicitly separates it from dialmycalls_list_recordings. It does not explicitly name the sibling it is not, so differentiation 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?

The phrase 'by id' implies the tool is for direct lookup once an id is known, but the description never says where to obtain an id (list_recordings) or what to do when the id is unknown. No when-not guidance or explicit alternative is offered.

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 safety profile, so the description is free to add value — and it does, enumerating the returned fields (name, recipients, credit cost, send time, pending_cancel), which no annotation conveys. It stops short of noting behavior for an unknown id or whether pending_cancel reflects live state.

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 the verb and scope front-loaded and no filler. The parenthetical field list is dense, useful information rather than padding.

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

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

With no output schema, the field enumeration is a meaningful stand-in for return-value documentation, so an agent knows roughly what comes back. Marginally incomplete on id provenance and failure behavior, but nothing essential is missing for a simple read-by-id 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 the id parameter is documented with a UUID pattern, so the schema carries parameter meaning fully. The description only echoes the id requirement and adds no format or sourcing detail beyond it.

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

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

States a specific verb and resource ('Get one outgoing text broadcast by id') and scopes it to a single item, which distinguishes it from dialmycalls_list_texts and dialmycalls_get_incoming_text without ambiguity. The parenthetical field list further pins down what 'get' returns.

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?

'by id' implies the retrieval use case versus the list tool, but the description never explicitly says when to use this over dialmycalls_list_texts, nor where the id comes from. 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful domain context — caller IDs carry an approval state that gates broadcasts — which is not in the annotations. It says nothing about ordering, whether unapproved IDs are included, or pagination behavior beyond what the schema states.

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, with the resource scope front-loaded and the returned fields in a compact parenthetical. Every clause carries information.

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

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

With no output schema, the description compensates by naming the four returned fields, and paging is covered by the schema. Minor gaps remain (does the list include unapproved IDs, what is the default ordering) but an agent can call this correctly as written.

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%: limit and start are fully documented, including the next_start paging convention. The description adds no parameter meaning and does not need to, so the baseline 3 applies.

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

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

Names a specific verb (List) and resource (caller ID phone numbers on the account) and even enumerates the fields returned (id, name, phone, approved). It is unmistakable against siblings like list_contacts or list_groups because the resource noun is unique, though it never explicitly contrasts with 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?

"A call broadcast needs an approved caller ID" gives the agent a concrete reason to call this before dialmycalls_send_call, which is real when-to-use context. It stops short of exclusions or of naming send_call as the downstream consumer, so it is clear context without full routing guidance.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuine context by enumerating the result values (answered, voicemail, busy, no answer) and the 100-per-page behavior. It omits other behavioral facts an agent would want, such as ordering of results, whether results are available before the broadcast finishes, or retention 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?

One sentence, front-loaded with the core action, and the parenthetical status list and page size are the only extras – each earns its place with no filler.

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

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

For a simple read-only list tool with full schema coverage, no output schema and no nested objects, this is close to sufficient: the agent knows what it retrieves and the page size. Only minor gaps remain (result availability timing, relationship to sibling get/list tools).

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 id, limit and start all documented, including the helpful 'use next_start from the previous reply' note in the schema itself. The description's '100 per page' largely restates the limit default rather than adding new meaning, 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 recipients of a call broadcast') and adds what each row contains ('result per number'), which implicitly separates it from dialmycalls_list_text_recipients. It never names that sibling or dialmycalls_get_call explicitly, so differentiation is implied 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?

Usage is only implied: you call it to inspect per-number delivery outcomes for a broadcast. There is no explicit when-to-use, no note that the id comes from dialmycalls_list_calls or send_call, and no guidance on when to prefer dialmycalls_get_call or dialmycalls_list_text_recipients instead.

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 the returned field set and page size, but says nothing about ordering, account scoping, or whether the payload includes pagination metadata beyond the schema's next_start hint.

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 field list is compact although the parenthetical enumeration is slightly terse.

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

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

No output schema exists, so the description must convey the return shape; it partially does by listing fields, but omits sort order and total/pagination result details an agent would want before 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 100% with both parameters fully documented, so baseline is 3. The description's '100 per page' merely restates the limit default rather than adding new meaning.

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

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

States a specific verb (List) and resource (voice call broadcasts) and enumerates the fields returned. It implicitly distinguishes itself from dialmycalls_list_texts by saying 'voice call', but never names the sibling explicitly.

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

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

Provides no when-to-use guidance and no alternatives; it does not tell the agent when to pick this over dialmycalls_get_call (single broadcast) or dialmycalls_list_call_recipients. Usage is only inferable from the 'List' verb.

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. It does disclose the page size ('100 per page') and the shape of each record, but says nothing about total counts, pagination metadata, 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?

One front-loaded sentence with no filler; the resource, returned fields, and page size all appear immediately.

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 a fully documented schema and a readOnly annotation, the description covers purpose, returned fields, and page size—enough to call it correctly. It could mention that pagination continues via next_start, but the schema already says so.

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 limit and start (including the next_start chaining tip) are already fully documented in the schema. The description's '100 per page' largely restates the limit maximum rather than adding new parameter meaning, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List contacts in the account') and even enumerates the fields returned (name, phone, email, groups). It does not distinguish itself from close siblings such as list_contacts_in_group, list_do_not_contacts, or get_contact, 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?

Usage is only implied: this appears to be the general 'list all contacts in the account' call, which implicitly excludes group-scoped or do-not-contact listings, but the description never says so or names those alternatives. Nothing states prerequisites or when a single get_contact lookup would be preferable.

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 burden is light. It adds a page size mention ('100 per page') but that duplicates the schema's limit maximum/default rather than disclosing new behavior, and says nothing about what the response returns beyond 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 front-loaded sentence that identifies the action, the scope, the dependency (list_groups) and the page size without any filler.

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

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

For a simple read-only list tool with a fully documented schema and annotations, the description covers what is needed; the only mild gap is that the response shape (e.g. next_start) is only implied via the start parameter's schema text.

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 group_id (UUID pattern), limit (1-100) and start ('use next_start from the previous reply') are already fully documented. The description adds no syntax or constraint beyond restating pagination, making baseline 3 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?

Specific verb (List) plus resource (contacts that belong to one contact group) with clear scope, and it points at dialmycalls_list_groups as the source of group ids, which separates it from the sibling dialmycalls_list_contacts.

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

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

The parenthetical '(from dialmycalls_list_groups)' tells the agent how to obtain the required group_id, and 'one contact group' clarifies the tool is group-scoped. It stops short of explicitly contrasting with dialmycalls_list_contacts for a flat listing.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description usefully adds that entries are opt-outs on call and text lists. However, the parenthetical '(type call or text)' is ambiguous — it implies type separation while the tool exposes no type parameter, leaving unclear whether both lists are merged in the response.

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 tight sentence with the resource and scope front-loaded and zero filler. Nothing is redundant with the title.

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

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

For a two-param read-only list with annotations covering safety and schema covering pagination, the definition is nearly sufficient. The only real gap is whether the response returns both call and text opt-out lists combined or separately, which stays ambiguous.

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 both parameters fully documented, including the next_start pagination hint, so the schema carries this dimension. The description adds nothing about limit or start, which is acceptable at this coverage level.

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 phone numbers on the account's do-not-contact lists') and clarifies what the entries represent ('these opted out'). It implicitly distinguishes itself from dialmycalls_list_contacts by scoping to opt-out lists, though it never names the 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?

No guidance on when to call this versus list_contacts or when to check these lists before send_call/send_text. The use case (compliance pre-check) is only hinted at by 'these opted out'; there are no 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results include contact counts and are paginated at 100 per page, but says nothing about ordering, total counts, or error 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?

A single front-loaded sentence with no filler; the return-value detail and pagination constraint come early. It is arguably too terse, 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 simple read-only list tool with two optional, fully documented parameters and no output schema, the description covers the essentials: what is returned and the page size. Only usage routing remains uncovered.

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

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

Schema description coverage is 100%, so both limit and start are fully documented in the schema, including the next_start pagination hint. The description's '100 per page' merely restates the schema default, adding no new semantics.

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

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

States a specific verb and resource (list contact groups) and adds a useful return-value detail (contact counts), which distinguishes it from get_group and list_contacts_in_group. It does not explicitly name siblings, 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?

There is no when-to-use or when-not guidance and no mention of alternatives such as list_contacts_in_group or get_group. The agent must infer that this is the bulk-listing 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds page size and returned fields, but does not disclose ordering, pagination metadata, or other operational details beyond what the schema and annotations already 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?

It is a single efficient sentence, front-loading the resource and scope and embedding the returned fields compactly. There is no wasted text.

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 full schema coverage, the description is sufficient: it identifies the resource, returned fields, and pagination size. The schema handles the detailed pagination parameters.

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 both limit and start clearly, including defaults and next-page usage. The description mentions 100 per page but adds no parameter semantics beyond the schema.

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

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

The description gives a clear verb and resource: listing incoming text messages sent to the account's numbers. It also names returned fields, but it does not explicitly distinguish itself from nearby siblings like get_incoming_text or list_texts.

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 'people sent to the account's numbers' implies this is for browsing incoming messages rather than retrieving a single message or listing outbound texts. However, there is no explicit when-to-use guidance or named alternative for single-message retrieval.

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

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

readOnlyHint already tells the agent this is a safe read, so the description's contribution is the domain constraint about broadcasts requiring an active keyword, which is genuinely useful context. It doesn't disclose anything further about result set size or ordering beyond what the schema's pagination fields already cover.

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 no filler: the first states the operation and its output fields, the second gives the domain constraint. Front-loaded and appropriately sized for a simple list endpoint.

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

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

For a read-only two-parameter list tool with no output schema, the description is nearly sufficient: it names the returned fields and supplies the business rule that motivates the call, while pagination is handled by the schema. Only the absence of any ordering note 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% — limit and start are fully documented including ranges, defaults, and the next_start chaining hint. The description adds no parameter meaning beyond that, so the baseline 3 for a well-described schema applies.

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

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

States a specific verb+resource ('List text-message keywords') and even names the returned fields (id, keyword, status), which unambiguously separates it from siblings like list_shortcodes or list_texts. It stops short of explicitly contrasting with those siblings, but the resource is distinct enough that an agent can select it correctly.

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

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

The sentence 'A text broadcast must be tied to one active keyword' implies the use case (look up an active keyword before calling send_text), but it is framed as a domain fact rather than explicit when-to-use/when-not-to-use guidance. No alternative tool is named and no prerequisite workflow is spelled out.

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 added domain context is the differentiator: it explains what a recording represents and flags that only processed recordings are callable, which is a real behavioral constraint an agent would otherwise have to discover. It does not describe pagination or empty-result behavior, but the schema covers 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?

Two short clauses: the core action with a clarifying gloss and field list, then the one constraint that matters. No filler, and the resource identity is front-loaded.

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

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

With no output schema, the field enumeration (id, name, type, length, processed) does useful work in telling the agent what a result looks like, and the processed flag requirement is stated. What remains missing is any hint about result volume or paging from the description itself, which is minor for a simple read-only list 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 (limit, start) are fully documented in the schema, including the next_start paging convention. The description adds nothing about them, 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 voice recordings") and parenthetically defines what a recording is in this domain, plus enumerates the fields returned. It does not explicitly distinguish itself from the sibling dialmycalls_get_recording or dialmycalls_create_recording_tts, but the plural 'List' versus 'get' convention and the field listing make the intent 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?

There is no explicit 'use this when...' statement and no named alternative such as get_recording for single-record retrieval. The sentence "A call needs a processed recording" does imply the practical use case (finding a usable recording id to pass to send_call), which goes beyond a bare description but leaves the 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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It contributes the meaning of "shortcode" (a sending origin for texts) but says nothing about pagination or result volume — the pagination mechanics are instead carried by the schema. Adequate but thin given the low bar set by 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?

A single short sentence with the resource and its purpose front-loaded; nothing redundant. It is terse to the point of under-specification, but there is no filler to cut.

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 a fully documented schema, the description is enough to invoke it correctly but not enough to interpret results — it doesn't indicate whether the list is usually empty, whether shortcodes are account-scoped, or what identifying fields to expect back, and no output schema exists to fill that 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%: both `limit` (1-100, default 100) and `start` (1-based, with the next_start hint) are fully documented in the schema, and neither is required. The description adds nothing about parameters, 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+resource ("List shortcodes") and adds domain scope ("available to send texts from"), so the agent knows shortcodes are sending-origin identifiers. No sibling tool lists shortcodes, so differentiation is implicit rather than explicit.

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

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

There is no guidance on when to call this versus alternatives. The phrase "available to send texts from" hints at a relationship to dialmycalls_send_text, but the description never says to resolve a shortcode before sending or what to do if none are returned.

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

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

readOnlyHint=true already covers the safety profile, and the description usefully adds the delivery-status vocabulary and the 100-per-page cap. It does not cover pagination termination, ordering, or what happens with an invalid/unknown broadcast id.

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

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

A single front-loaded sentence with no filler; the return content and page size are packed in efficiently. Slightly dense but nothing 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 the important work of telling the agent what a row contains (status per number), and pagination is covered by the schema. Only minor gaps remain around ordering and empty/error cases for a simple read 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 coverage is 100%, so id, limit and start are already fully documented, including the next_start paging hint. The description's '100 per page' only corroborates the limit default; it adds no new parameter meaning 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 and resource ('List the recipients of a text broadcast'), plus what each row carries (delivery status per number). It implicitly separates itself from list_texts (broadcasts) and get_text (single broadcast), though it never names a sibling to make the distinction explicit.

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 resource description — you call this to inspect who received a given broadcast — but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as list_call_recipients or get_text.

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 the 100-per-page default and the returned fields, but says nothing about authentication, rate limits, or ordering of results. With annotations carrying the safety burden, this is a reasonable 3.

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 waste – verb, resource, returned fields, and page size all delivered immediately.

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 tool with a fully described two-parameter schema and no output schema, the description covers purpose, returned fields, and page size. It could note ordering or filtering constraints, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both limit and start are fully documented in the schema, including the next_start continuation pattern. The description only echoes the page size, adding no new syntax or format detail beyond what the schema provides.

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

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

States a specific verb (List) and resource (outgoing text/SMS broadcasts), and enumerates the fields returned. The word 'outgoing' implicitly separates it from dialmycalls_list_incoming_texts, so an agent can distinguish it from the closest sibling without opening a 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 'List' and the paging hint, but there is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. Adequate for a straightforward list tool but leaves routing inference to the agent.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial non-redundant context: the action spends credits, phones real people, and is irreversible once sent. It also explains the confirm gate and scheduled-call cancellation path. Minor gap: no detail on partial failure or credit consumption rates.

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

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

Front-loads the verb and the high-stakes consequence, then moves through prerequisites, approval flow, and the preview fallback. Four dense sentences with no filler; capitalized warnings are proportionate to the destructive nature.

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, credit-spending broadcast tool with no output schema, the description covers the entire safety envelope: approvals, prerequisites, confirm semantics, preview behavior, and cancellation of scheduled sends. An agent has everything needed to call it safely.

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 eight parameters already carry descriptions. The description reinforces caller_id and recording prerequisites and the confirm semantics, but adds little parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource (send/schedule an automated voice call broadcast) plus the key constraint that recipients are real people. It is clearly distinguishable from dialmycalls_send_text and dialmycalls_cancel_call, which are named contextually.

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 names prerequisites (approved caller_id, processed recording) and the sibling tools that provide them, instructs the agent to get user approval before sending, and explains that confirm=false yields a preview instead of sending. It also points to dialmycalls_cancel_call for stopping scheduled sends.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description meaningfully adds that credits are spent, that a sent broadcast cannot be undone, and that a scheduled one can be stopped with dialmycalls_cancel_text. However, it does not describe the returned preview/send result or per-recipient failure behavior, so it adds useful but not rich context beyond the annotations.

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

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

Two tight sentences with the highest-stakes warning (spends credits, irreversible) front-loaded, followed by prerequisites and the approval/preview flow. 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 destructive, credit-spending broadcast tool with no output schema, the description covers cost, irreversibility, the cancel path, the keyword prerequisite, the message cap, and the confirm=false preview return. Nothing an agent needs in order to call it safely 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 every parameter (including confirm's preview semantics, send_at's timezone requirement, and message limits) is already fully documented in the schema. The description only restates the confirm=false preview and the 10-message cap, adding no syntax or constraint details the schema lacks.

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

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

States a specific verb and resource ('Send (or schedule) a TEXT MESSAGE (SMS) broadcast') and disambiguates from the sibling send_call by naming the medium explicitly. The scope (real recipients, per-broadcast message count) is clear 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 names prerequisites (active keyword via dialmycalls_list_keywords), the alternative for stopping a scheduled send (dialmycalls_cancel_text), and the approval workflow before sending. The confirm=false preview path tells the agent exactly how to run a dry run first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds critical behavior not in annotations: phone is mandatory on every update, omitted fields are preserved, and passing group_ids replaces the contact's groups. That replacement semantics is the key risk for an agent to understand.

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 tool purpose and immediately followed by the two most important behavioral rules. No wasted text.

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 update tool with no output schema, the description covers the key operational risks: required phone and group replacement. It could mention what happens with an empty group_ids array or error conditions, but it is largely 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?

With 8 parameters and 63% schema description coverage, the description compensates on the most important ones: it explains the mandatory phone parameter and the replace-all behavior of group_ids. Names like firstname/lastname lack schema descriptions, but their purpose is obvious from naming.

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

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

The description uses a specific verb and resource ("Update a contact") that clearly distinguishes it from sibling tools like create_contact or get_contact. It does not explicitly name sibling alternatives, but the update scope is unambiguous.

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

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

It gives clear usage context: phone is required on every update, omitted fields remain unchanged, and group_ids causes replacement. It lacks explicit when-to-use versus when-not-to-use guidance relative to siblings, but the operational rules are clear.

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