Send and receive faxes from any MCP-compatible AI assistant using the Fax.Plus API
Scored across 53 tools
Tools are mostly organized around distinct resources and actions; the fax/outbox-fax and contact/contact-group variants help separate operations. A few workflow-heavy tools like request-file-from-user, upload-file, and send-fax-uploaded create mild ambiguity that is only resolved by reading their long descriptions.
The overwhelming majority follow a clear verb-noun pattern with hyphenated lowercase names, and the plural list- vs singular get- distinction is consistent. The exceptions—pipeline_start using an underscore and request-file-from-user being a phrase rather than a verb-noun pair—are minor deviations.
53 tools is far above the recommended range for an MCP server and will make selection harder for agents. While the domain is broad, many subtools could have been consolidated, so the surface feels over-fragmented even though most endpoints are individually legitimate.
The tool suite covers the major workflows well: sending, retrieving, updating, deleting, and bulk-managing faxes, plus contacts, numbers, members, webhooks, and account data. Gaps like webhook updates, canceled number release, and single-contact fetch are minor and can be worked around without breaking core flows.
Delete multiple fax records in one request. This is destructive and requires explicit confirmation.
Side effects: deletes multiple fax records.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_ids | Yes | Fax IDs to delete (1..50). | |
| user_id | No | Fax.Plus user ID. Default: self. | |
| confirmation_text | Yes | Must be exactly BULK_DELETE_FAXES. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's "destructive" claim adds no new information. It does add useful context about requiring explicit confirmation, but the "Side effects" line merely restates the destructive behavior already covered by annotations and the first sentence.
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 short and front-loaded with the core action, but the "Side effects" line is redundant with both the first sentence and the destructiveHint annotation. It contains roughly one sentence of wasted content.
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 bulk operation with full schema coverage and an output schema, the description covers the essential action, the destructive nature, and the confirmation requirement. It could be more complete by noting whether this applies to regular faxes only versus outbox faxes, but nothing critical for invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents fax_ids, user_id, and confirmation_text. The description does not add parameter-level meaning, but the baseline of 3 is appropriate because the schema already carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Delete multiple fax records in one request." It clearly distinguishes itself from single-delete tools like delete-fax by emphasizing the bulk nature, though it does not explicitly differentiate from the sibling bulk-delete-outbox-faxes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when multiple fax records need deletion, but provides no explicit guidance about when to choose this tool over delete-fax, delete-outbox-fax, or bulk-delete-outbox-faxes. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple outbox fax records in one request. This is destructive and requires explicit confirmation.
Side effects: deletes multiple outbox fax records.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. | |
| outbox_fax_ids | Yes | Outbox fax IDs to delete (1..10). | |
| confirmation_text | Yes | Must be exactly BULK_DELETE_OUTBOX_FAXES. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the burden on the description is low. Yet the description mostly restates structured data: 'This is destructive' duplicates the annotation, 'requires explicit confirmation' duplicates confirmation_text's schema description, and the 'Side effects' line repeats the first sentence verbatim. It adds no genuinely new behavioral context (e.g., irreversibility, partial-failure behavior, or what happens to related resources). No contradiction with 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 short and front-loaded with the core action, which is good. However, the third sentence ('Side effects: deletes multiple outbox fax records') is a near-verbatim duplicate of the first, and the confirmation/destructive statements duplicate the schema and annotations; one redundant sentence is present, undermining the 'every sentence earns its place' bar.
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 multi-record mutation, the description compensates minimally thanks to strong external structure: annotations cover the safety profile, the schema describes every parameter at 100% coverage, and an output schema exists. The main gap is that the description itself contributes essentially nothing toward correct invocation (e.g., it does not flag that deletion is irreversible or how results of partial failures are returned), which is modest given how much structure already exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (including the exact confirmation constant and the 1..10 id constraint). The description's phrase 'multiple outbox fax records' weakly reinforces outbox_fax_ids semantics but adds no detail beyond the schema, which is the baseline case for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Delete multiple outbox fax records'), and the phrase 'outbox fax records' distinguishes this from any tool operating on regular faxes, helping separate it from bulk-delete-faxes. However, it never explicitly names or contrasts the closest siblings (delete-outbox-fax, bulk-delete-faxes), leaving the agent to infer the distinction 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?
No guidance is provided on when to use this tool versus delete-outbox-fax (single) or bulk-delete-faxes (different resource). 'In one request' implies a batch use case but there is no explicit when-to-use/when-not-to-use statement, no prerequisites, and no mention of the 1..10 limit beyond what the schema already provides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple fax records in one request (is_read and/or comment).
Side effects: modifies multiple fax records.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Bulk update payload with ids plus is_read and/or comment. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation nature. The description adds that it modifies 'multiple' records and happens 'in one request', which is extra context beyond annotations. No contradiction; it reinforces safety expectations but adds little beyond scale.
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. The primary action and scope are front-loaded, and the side-effect note is brief. Every word 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 bulk update with a nested payload and an output schema present, the description covers the core action and scale. It doesn't mention error handling or prerequisites, but those are not required for a straightforward mutation tool. It is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters are described inline. The description repeats the 'is_read and/or comment' fields but adds no new syntax, constraints, or usage nuance. Baseline 3 is appropriate since schema does the heavy lifting.
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 ('Update') and resource ('multiple fax records') and lists the exact fields ('is_read and/or comment'). It clearly differentiates from siblings like bulk-delete-faxes (delete vs update) and bulk-update-outbox-faxes (outbox vs general faxes) without needing the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for updating multiple faxes but does not explicitly contrast with single-record update-fax or the outbox variant. It lacks explicit 'when to use this vs that' guidance, though the context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update comment for multiple queued outbox faxes in one request.
Side effects: modifies multiple outbox records.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Bulk outbox update payload with ids and comment. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's side-effects note adds only mild context: it modifies multiple outbox records rather than a single one. It does not disclose permissions, atomicity, or irreversibility, but it also does not contradict 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?
Every sentence is front-loaded and the whole description is only two lines. It states purpose immediately and adds a deliberate side-effect note; no filler or redundant elaboration. This is a model example of concise tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter shape and the presence of a full schema plus output schema, the description is technically entering, but for a bulk mutation it stays silent about partial failures and invalid IDs and what happens to already-sent vs queued faxes. That gap is not fixed by schema, so the description is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description merely echoes 'comment' and 'multiple' but adds no extra semantics for payload structure, user_id, or whether IDs must be queued outbox records. It does not fully compensate, but the schema already carries the burden.
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 ('update comment'), a precise resource ('multiple queued outbox faxes'), and the batching mode ('in one request'). The qualifiers 'outbox', 'queued', and 'multiple' distinguish it from sibling tools such as update-outbox-fax and bulk-update-faxes.
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 does not say when to prefer this tool over alternatives or when not to use it. It never mentions update-outbox-fax for single updates, bulk-update-faxes for non-outbox updates, or any exclusion criteria. The only hint is 'for multiple... in one request,' which is too implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new contact in Fax.Plus address book. Requires name and fax_number (E.164, e.g. +15551234567). Optional groups must be group names (e.g. Vendors), not group IDs.
Side effects: creates contact.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Contact name (required). | |
| No | Optional email. | ||
| notes | No | Optional notes. | |
| phone | No | Optional phone. | |
| groups | No | Optional group names (not IDs), e.g. ["Vendors"]. | |
| shared | No | Optional: share with corporate members. | |
| cellphone | No | Optional cellphone. | |
| fax_number | Yes | Contact fax number in E.164 form (required), e.g. +15551234567. | |
| is_telefax | No | Optional: whether the contact has a human fax operator. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| No | ||
| notes | No | |
| phone | No | |
| groups | No | |
| cellphone | No | |
| is_shared | No | |
| fax_number | No | |
| is_telefax | No | |
| creation_date | No | |
| modification_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent mutation. The description adds an explicit side effect ('creates contact') and the target context (address book), but it does not discuss duplicate behavior or whether existing contacts are affected. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and skimmable. The only minor redundancy is the final 'Side effects: creates contact' line, which repeats the first sentence.
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 tool with full schema coverage and an output schema, the description covers the required inputs and the likely confusion point (group names vs IDs). It omits duplicate/permission details, but those are not essential given the annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema. The description merely emphasizes the required fields and the groups-vs-IDs gotcha, both of which are already present in the 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?
The description opens with a specific verb and resource: 'Create a new contact in Fax.Plus address book.' This clearly differentiates it from siblings like update-contact, delete-contact, and create-contact-group.
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 necessary prerequisites: name and fax_number are required, and groups must be group names rather than IDs. It does not explicitly name alternatives like update-contact or delete-contact, but the create intent and required fields make the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a contact group (Fax.Plus tag) to organize contacts. When assigning contacts via set-contact-groups / create-contact / update-contact, pass this group's name, not its id.
Side effects: creates contact group.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| notes | No | ||
| shared | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| notes | No | |
| is_shared | No | |
| creation_date | No | |
| modification_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the statement 'Side effects: creates contact group,' which explicitly discloses the non-read-only nature. Annotations already set readOnlyHint=false and destructiveHint=true, so the description does not contradict them (though 'destructive' is a misnomer for creation). The description provides no additional behavioral context like permissions, reversibility, or impacts on existing data, so it offers only minimal value beyond 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 two sentences plus a side-effect note, with zero waste. The purpose is front-loaded in the first sentence, the critical usage nuance follows immediately, and the side effect is stated separately. Every sentence earns its place, making it highly concise and 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?
The tool has an output schema, so return values are covered. However, with three parameters and no parameter descriptions in the schema, the description is incomplete for full correct usage—it omits what 'notes' and 'shared' mean and any constraints on 'name.' The name-vs-id note is valuable but does not address these gaps. Overall, it covers the core purpose but leaves significant parameter semantics uncovered, making it partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meanings. It only indirectly clarifies the 'name' parameter by noting that the group's name is used for assignments, but it does not explain 'notes' or 'shared' at all. Since these parameters are undocumented in both schema and description, an agent has no guidance on their purpose or constraints. The description fails to carry the burden of explaining 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 action ('Create a contact group (Fax.Plus tag)') and its purpose ('to organize contacts'). It also distinguishes this tool from siblings like update-contact-group and delete-contact-group by the explicit note that when assigning contacts via set-contact-groups / create-contact / update-contact, the group's name (not id) must be passed. This is a specific differentiator that an agent can act on.
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 a concrete usage instruction: when assigning contacts, use the group's name rather than its id. This implies when the created group will be consumed and provides a key step for correct integration. However, it does not explicitly state when to use this tool versus alternatives (e.g., list-contact-groups for lookups) or when not to use it. The guidance is useful but incomplete for full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook subscription for a fax event and target URL. Optionally pass numbers (E.164, e.g. ["+17154578872"]) to fire only for those fax numbers; omit numbers to receive events for all numbers.
Side effects: creates webhook subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | Event to subscribe to: fax_received, fax_sent, or fax_page_received. | |
| target | Yes | HTTPS (or HTTP) URL that will receive webhook callbacks. | |
| numbers | No | Optional E.164 fax numbers to filter on (JSON array). Example: ["+17154578872"]. Omit to receive events for all numbers. Empty list is invalid. |
| Name | Required | Description |
|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that the tool mutates state and is not idempotent, and the description adds a clear 'Side effects' line stating that it creates a webhook subscription. It does not go deeper into duplicate creation, replacement, or confirmation behavior, but it does not contradict 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?
The description is short, front-loaded with the core operation, and includes a separate side-effects line with no wasted words. The optional-number behavior is explained in one clear sentence with an example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and schema coverage is 100%, the description covers all decisions an agent needs to invoke the tool correctly. It could add duplicate-handling or idempotency details, but the annotations already signal idempotentHint=false, so the remaining gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful behavioral nuance beyond the schema: it explains the filtering effect of passing numbers and the all-numbers behavior when omitted. This helps an agent choose parameter values correctly even beyond the schema fields.
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 action, resource, and inputs: create a webhook subscription for a fax event and target URL. It also explains the optional number-filtering behavior, making the tool's scope unambiguous and distinguishing it from webhook deletion/inspection tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance for when to provide numbers vs. omit them: pass E.164 numbers to filter to specific fax numbers, or omit to receive all events. It does not name alternative sibling tools, but the create operation is self-selecting and this guidance resolves the main conditional decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a contact. This is destructive and requires explicit confirmation.
Side effects: deletes contact.
| Name | Required | Description | Default |
|---|---|---|---|
| contact_id | Yes | Contact ID to delete. | |
| confirmation_text | Yes | Must be exactly DELETE_CONTACT. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| contact_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already set destructiveHint=true and readOnlyHint=false, so 'this is destructive' adds no new information. The description does add the useful caveat that explicit confirmation is required before deletion, though 'Side effects: deletes contact' largely restates the purpose. No contradiction with 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 first sentence repeats the tool title, the second repeats destructiveHint, and the final 'Side effects' line repeats the first sentence. Only 'requires explicit confirmation' is non-redundant, so the description does not satisfy the requirement that every sentence earn 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 two-parameter, destructive operation with a rich input schema, an output schema, and safety annotations, the description is nearly sufficient: it identifies the action and the key precondition of explicit confirmation. It does not need to explain return values because an output schema exists; only minor edge-case context is absent.
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 contact_id and confirmation_text are already documented with clear descriptions, including the exact required value for confirmation_text. The tool description adds no parameter-level detail beyond those structured definitions.
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 the exact action and resource ('Delete a contact'), which is unambiguous against siblings like delete-contact-group and delete-fax. It does not explicitly contrast those siblings, but the resource term is specific enough that the tool's purpose 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 description implies the intended use—when a contact must be removed—and warns that explicit confirmation is required. It does not state when not to use this tool or mention any alternative deletion/update tool, so the agent must infer selection choices from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a contact group (Fax.Plus tag). This is destructive and requires explicit confirmation.
Side effects: deletes contact group.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | Contact group ID to delete. | |
| confirmation_text | Yes | Must be exactly DELETE_CONTACT_GROUP. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| group_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the explicit confirmation requirement and a side-effects statement, which goes beyond the annotations and reinforces the destructive nature. The side-effects line is somewhat redundant but still provides clear behavioral framing.
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 short and front-loaded with the purpose. The 'Side effects: deletes contact group' line is somewhat redundant with the first sentence and the destructiveHint annotation, so there is minor waste. Overall, it is efficient and easy to parse.
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 delete tool with a full input schema, an output schema, and clear destructive annotations, the description is nearly complete. It communicates the required confirmation and the destructive side effect. It could additionally mention irreversibility or that contacts in the group are unaffected, but these are minor omissions.
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%, with both parameters already clearly documented: group_id and confirmation_text. The description adds no new parameter-level detail beyond saying confirmation is required, which the schema already captures. Baseline 3 is appropriate because the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Delete a contact group (Fax.Plus tag).' The clarification that a contact group is a Fax.Plus tag helps distinguish this from delete-contact and update-contact-group. It is unambiguous and directly aligned with the tool's name and title.
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 conveys that this is destructive and requires explicit confirmation, which gives the agent a clear operational constraint. However, it does not explicitly mention when not to use it or suggest alternative tools such as update-contact-group for non-destructive changes. Usage is implied rather than fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a fax record. This is destructive and requires explicit confirmation.
Side effects: deletes fax record.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax ID to delete. | |
| user_id | No | Fax.Plus user ID. Default: self. | |
| confirmation_text | Yes | Must be exactly DELETE_FAX. |
| Name | Required | Description |
|---|---|---|
| fax_id | Yes | |
| deleted | Yes | |
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds the explicit-confirmation requirement, which is useful beyond the structured data. However, 'This is destructive' and 'Side effects: deletes fax record' mostly restate existing information.
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 short and front-loaded with the main action, but the 'Side effects: deletes fax record' line is redundant with the first sentence and adds no informative value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema, full param descriptions, and destructive annotations, the tool is largely self-contained. The key gap is scope clarification: it does not specify that this tool deletes a regular fax record as opposed to an outbox fax, which is a real ambiguity given the sibling list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not enrich parameter meaning beyond the schema; the confirmation_text constraint is already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a fax record' with a clear verb and resource. It is unambiguous about the primary action, though it does not explicitly distinguish from sibling tools like delete-outbox-fax or bulk-delete-faxes.
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 is given on when to use this tool versus alternatives such as delete-outbox-fax or bulk-delete-faxes. The mention of 'requires explicit confirmation' is a prerequisite for invocation, not a selection guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a queued outbox fax record. This is destructive and requires explicit confirmation.
Side effects: deletes outbox fax record.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. | |
| outbox_fax_id | Yes | Outbox fax ID to delete. | |
| confirmation_text | Yes | Must be exactly DELETE_OUTBOX_FAX. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| user_id | Yes | |
| outbox_fax_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. The description adds the explicit confirmation requirement and a side-effects note, but the side effects line is redundant with the first sentence. No other behaviors (auth, rate limits, irreversibility) are disclosed, though annotations cover the destructive nature.
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 short sentences plus a side-effect line, keeping it concise. However, the side-effect line ('deletes outbox fax record') repeats the action stated in the first sentence, adding minor redundancy. Still, it is well-structured and front-loaded with the core purpose.
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 destructive delete with confirmation, the description, schema, and annotations are mostly adequate. It lacks guidance on prerequisites (e.g., fax must be queued) or error scenarios, but given the output schema exists and the operation is straightforward, it is minimally sufficient. The confirmation requirement is highlighted, which is essential.
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 descriptions cover all three parameters at 100% coverage. The description does not add any additional meaning or elaboration about the parameters beyond what the schema already provides, so it meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a queued outbox fax record' with a specific verb and resource. It clearly distinguishes from siblings by focusing on 'outbox fax' vs. general 'fax' deletion tools, and the singular 'a' implies single-item operation versus bulk variants.
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 is provided on when to use this tool versus alternatives like bulk-delete-outbox-faxes or delete-fax. The description only mentions confirmation requirements, not selection criteria, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook subscription by ID. This is destructive and requires explicit confirmation.
Side effects: deletes webhook subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| hook_id | Yes | Webhook ID to delete. | |
| confirmation_text | Yes | Must be exactly DELETE_WEBHOOK. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| hook_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds that explicit confirmation is required and notes the side effect of deleting the subscription. This provides useful safety context beyond the structured annotations and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core purpose. The side-effect line is somewhat redundant with the first sentence, but the overall structure is efficient and easy to parse.
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 tool with a fully descriptive schema, output schema, and safety annotations, the description covers everything an agent needs: what is deleted, how it is identified, and that confirmation is required.
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 parameters well. The description adds little parameter detail beyond mentioning deletion by ID, meeting the baseline without needing extra compensation.
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?
Description states a clear verb ('Delete'), a specific resource ('webhook subscription'), and the key identifier ('by ID'). It is easily distinguishable from sibling tools like create-webhook and get-webhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting an existing webhook by ID and requires explicit confirmation, but it does not explicitly contrast with alternatives such as create-webhook or get-webhooks. Usage context is clear but not fully elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your Fax.Plus shop account balance.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| amount | Yes | |
| currency | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description's 'Side effects: none (read-only)' repeats this without adding new context like auth requirements or rate limits. Minimal added value, so a 3 is appropriate.
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 short lines, front-loaded with the purpose and redundant side-effect note. Every word earns its place; no fluff.
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 no-parameter read tool with an output schema, the description fully covers what an agent needs. Return format is handled by the output schema, so nothing 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?
With zero parameters, the baseline is 4. The description correctly omits parameter details, and the schema confirms no inputs. No additional parameter meaning is needed.
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) and resource (account balance) with clear scope ('your Fax.Plus shop'). It is distinct from sibling getters like get-plan or get-user, so an agent can identify it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit alternatives are needed since no sibling tool retrieves balance. The description clearly implies its use for checking the shop balance. It lacks explicit exclusions, but the purpose is unambiguous, earning a high score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a specific fax record. wait_seconds is optional (default 0). After send-fax-uploaded, pass wait_seconds=30 on the first check so the record can become visible; omit it or pass 0 for later polls. Immediate 4xx without that wait is expected, not a lost job. Tell the user status in everyday words (preparing, sending, sent, failed); do not paste raw fields, costs, or client metadata unless they ask for a support reference.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax record ID. | |
| user_id | No | Fax.Plus user ID. Default: self. | |
| wait_seconds | No | Optional. Seconds to wait before calling Fax.Plus (default 0, max 60). After send-fax-uploaded, pass 30 on the first status check. Omit or 0 for later polls. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| to | No | |
| cost | No | |
| file | No | |
| from | No | |
| pages | Yes | |
| header | No | |
| status | Yes | |
| comment | Yes | |
| is_read | No | |
| is_spam | No | |
| duration | No | |
| owner_id | Yes | |
| direction | No | |
| file_name | No | |
| max_retry | No | |
| cover_page | No | |
| start_time | No | |
| description | No | |
| last_update | No | |
| retry_delay | No | |
| submit_time | No | |
| cost_details | Yes | |
| scheduled_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Side effects: none (read-only).' It adds valuable behavioral context about the expected 4xx response on first poll and instructs how to present status in everyday words, going beyond what annotations provide.
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 few sentences long but every sentence earns its place: purpose, parameter guidance, error expectation, and user communication instructions. It is front-loaded with the core purpose and efficiently structured. Slightly long but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown), the description need not explain return values. It covers the main usage scenario, error handling, and how to communicate results. It doesn't mention authentication prerequisites, but those are likely implicit for all tools in this set. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions, so baseline is 3. The description adds meaningful context for wait_seconds (the recommended value after send-fax-uploaded and behavior for later polls), which is beyond the schema. For user_id and fax_id, it adds nothing new, but the existing schema descriptions are sufficient.
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 action and resource: 'Get details for a specific fax record.' This is specific and unambiguous, and the tool name reinforces it. While it doesn't explicitly contrast with siblings like get-outbox-fax, the purpose is so clear that an agent can distinguish it without further explanation.
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 explicit usage context for the wait_seconds parameter, including when to pass 30 (after send-fax-uploaded) and when to omit it (later polls). It also warns about expected immediate 4xx errors. However, it doesn't mention when to choose this tool over get-outbox-fax or other siblings, though the tool name and context make that reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a fax confirmation report (PDF).
Side effects: none (read-only); returns base64 PDF report in structured output.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax record ID. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| data_base64 | Yes | |
| content_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds one useful detail beyond that: the return value is a base64 PDF in structured output. This is genuinely non-trivial and helps an agent interpret the result, but there is no additional behavioral depth (e.g., errors, auth requirements), so with annotation coverage already in place, a mid-score is appropriate.
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 with no waste. The primary purpose is stated up front, and the side-effect and return-format note follows without redundancy. 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?
The tool is a simple read-only endpoint with 2 parameters and an output schema that presumably describes the base64 PDF. The description covers the essential purpose and return format, the annotations cover safety, and the schema covers parameters and output. Nothing needed 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 the input schema already documents 'fax_id' and 'user_id' (including the default for 'user_id'). The description adds nothing about parameters, but this is fine because the schema fully captures meaning. Baseline 3 is therefore 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?
The description clearly states a specific verb ('Retrieve'), a specific resource ('fax confirmation report'), and adds the format '(PDF)'. It is immediately distinguishable from siblings like get-fax and get-fax-thumbnail because it fixes the confirmation report document rather than fax metadata or a preview image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool must be called when a fax confirmation report PDF is needed. However, there is no explicit mention of when to prefer this over get-fax or get-fax-thumbnail. The sibling names are self-explanatory, but the description itself doesn't provide this guidance, so a small deduction is made relative to the highest standard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a fax thumbnail image.
Side effects: none (read-only); returns base64 image bytes in structured output.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax record ID. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| data_base64 | Yes | |
| content_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false; the description adds explicit side-effect disclosure ('none (read-only)') and the return format (base64 image bytes in structured output), which helps the agent know what to expect beyond the schema. No contradictions.
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 core action first and the side-effect/return information in a compact second sentence. 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 thumbnail retrieval with a full output schema and fully documented parameters, the description is sufficient. Side effect and return format are included, and nothing else is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema documents both parameters with 100% coverage. The description does not add further parameter-level semantics, so baseline 3 applies. It does not include detail beyond 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?
Description states a specific verb (Retrieve) and resource (fax thumbnail image), distinguishing it from siblings like get-fax (full fax record) and get-file (generic file). The word thumbnail makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance, but the description clearly implies the tool is for thumbnail image retrieval, leaving the agent to infer it should be selected when image bytes, not full fax data, are needed. It does not name exclusions or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a sent or received fax file.
Side effects: none (read-only); returns base64 file bytes in structured output.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax record ID whose file should be downloaded. | |
| format | No | 'pdf' (default) or 'tiff'. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| data_base64 | Yes | |
| content_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already signal read-only/idempotent behavior, and the description adds a useful behavioral trait by stating the result is base64 file bytes in structured output. This is consistent with the annotations, so no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose. The 'Side effects: none (read-only)' clause largely duplicates the readOnlyHint annotation, so not every sentence adds unique value, preventing a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, full schema coverage, and output schema, an agent has enough to invoke this tool correctly. It lacks explicit sibling differentiation and usage alternatives, which keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a meaningful description. The tool description itself adds no additional parameter-level semantics, so the baseline score of 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?
The description states a clear action ('Download') on a specific resource ('sent or received fax file'), which conveys the tool's primary purpose. However, it does not explicitly distinguish this from sibling download/preview tools like get-file-page or get-fax-thumbnail, so it falls just 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 guidance on when to use this tool instead of related file-retrieval tools, nor any exclusions or prerequisites. The phrase 'sent or received' describes scope but does not give the agent decision criteria among the large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a single page from a fax file (TIFF).
Side effects: none (read-only); returns base64 TIFF page in structured output.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax record ID. | |
| user_id | No | Fax.Plus user ID. Default: self. | |
| page_num | Yes | 1-based page index. |
| Name | Required | Description |
|---|---|---|
| data_base64 | Yes | |
| content_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false stanchion. The description adds value by explicitly stating 'Side effects: none (read-only)' and specifying the return type as a base64 TIFF page in structured output, which is useful 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, no wasted words. The main action is front-loaded, and the side-effect note is separated clearly. 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 simple, well-typed download operation with full schema coverage, annotations, and an output schema, the description is nearly complete. The only missing context is explicit guidance about choosing between this and sibling file-retrieval tools, which is a minor gap given the low complexity.
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%: fax_id, user_id, and page_num are all documented in the schema. The description adds no further parameter detail; baseline of 3 is appropriate because the schema already carries the full load.
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 ('Download'), a precise resource ('a single page from a fax file (TIFF)'), and the output format. This clearly distinguishes it from siblings like get-file (whole file) and get-fax-thumbnail (thumbnail image).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—when you need just one page of a fax—but does not explicitly mention alternatives or when-not-to-use. With many sibling download tools (get-file, get-fax-thumbnail, get-fax), explicit routing guidance would improve this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a corporate member's role and faxing quota.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| member_user_id | Yes | Fax.Plus member user ID. |
| Name | Required | Description |
|---|---|---|
| role | No | |
| quota | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Side effects: none (read-only)', which matches the readOnlyHint, idempotentHint, and destructiveHint annotations, so there is no contradiction. However, it adds little beyond what the annotations already disclose.
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 short sentences with no filler: one states the purpose, one states side effects. It is front-loaded and perfectly sized for a simple getter.
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 tool with a fully documented input schema, an output schema, and complete annotations, this description is sufficient. 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%, and the only parameter member_user_id is clearly described in the schema. The description adds no substantive parameter-level detail, but none is needed.
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 ('Get') with an exact resource ('corporate member') and names the targeted fields ('role and faxing quota'). This clearly distinguishes it from siblings like list-members or update-member-details.
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 explicit when-to-use guidance or alternative routing is provided. The wording implies a single-member lookup, but an agent must infer the distinction from list-members and update-member-details on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a specific fax number.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Fax number in E.164 form, e.g. +1234567890. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| number | Yes | |
| status | Yes | |
| owner_id | Yes | |
| assigned_to | Yes | |
| is_canceled | No | |
| acquired_date | Yes | |
| notifications | No | |
| expiration_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the read-only behavior already declared by annotations (readOnlyHint=true, destructiveHint=false) without adding any new behavioral context. It does not disclose response characteristics, authorization needs, or other constraints beyond what annotations and schema already provide.
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 first sentence is direct and front-loaded. However, the second sentence merely restates annotation data, so it does not earn its place; the description is short but slightly redundant given the available annotations.
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 retrieval tool, the description, fully documented schema, and presence of an output schema give an agent enough to select and invoke it correctly. It lacks alternative-routing guidance, but that gap is minor for a one-resource lookup.
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 input schema already provides full descriptions for both parameters, including the E.164 format for 'number' and the default for 'user_id'. Since schema coverage is 100%, the description does not need to add parameter detail and offers none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation: retrieving information about a single fax number. The qualifier 'specific' distinguishes it from list-oriented siblings like list-numbers and from mutating tools like purchase-number or revoke-number.
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 explicit when-to-use or when-not-to-use guidance is provided. The phrase 'specific fax number' implies use for a single-number lookup rather than a list operation, but the description does not name alternatives or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a fax scheduled for sending (outbox). wait_seconds is optional (default 0). After send-fax-uploaded, pass wait_seconds=30 on the first check so the record can become visible; omit it or pass 0 for later polls. Immediate 4xx without that wait is expected, not a lost job. Summarize for the user in plain language; do not expose raw API fields unless needed for support.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. | |
| wait_seconds | No | Optional. Seconds to wait before calling Fax.Plus (default 0, max 60). After send-fax-uploaded, pass 30 on the first status check. Omit or 0 for later polls. | |
| outbox_fax_id | Yes | Outgoing fax (outbox) record ID. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| ip | No | |
| to | No | |
| src | No | |
| uid | Yes | |
| files | No | |
| retry | No | |
| status | Yes | |
| comment | No | |
| options | No | |
| send_time | No | |
| cover_page | No | |
| extra_info | No | |
| page_count | No | |
| submit_time | No | |
| contact_name | No | |
| file_changes | No | |
| designated_src | No | |
| initiated_from | No | |
| should_enhance | No | |
| status_changes | No | |
| last_updated_status_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavior: the wait_seconds timing, the 4xx expectation, and the style guidance for summarizing results. Consistent with annotations, no contradiction.
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 concise and well-structured: purpose first, then operational guidance, then a note about 4xx, then user-facing behavior. The side-effects line is redundant with annotations but short. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered. The description addresses purpose, timing, error expectations, and user presentation. For a simple read tool with annotations already covering safety, nothing an agent needs 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 baseline is 3. The description adds meaning beyond the schema by explaining the wait_seconds usage in context (first check vs later polls), which helps the agent decide values. It doesn't explain all params, but the schema does.
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 'Get details of a fax scheduled for sending (outbox)' — a specific verb and resource with clear scoping to outbox, distinguishing it from get-fax (for sent/received) and list-outbox-faxes (for listing). No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage context: 'After send-fax-uploaded, pass wait_seconds=30 on the first check' and explains the expected 4xx behavior. It doesn't explicitly contrast with sibling get-fax or list-outbox-faxes, but the scenario is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the plan type and admin/owner flags for a user.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| is_admin | Yes | |
| is_owner | Yes | |
| plan_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'Side effects: none (read-only)', which is redundant with the annotations. It doesn't add other behavioral context like auth requirements or rate limits, but given the annotations cover safety, the bar is met.
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 extremely concise: two sentences with no wasted words. The core purpose is front-loaded, and the side-effect note is a natural follow-up. This is an exemplar of efficient, scannable documentation.
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 tool is simple: one optional parameter, an output schema exists (not shown but present), and annotations cover safety. The description fully conveys what an agent needs to know to call it correctly. Nothing is missing for this read-only, idempotent operation.
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% – the user_id parameter is documented in the schema. The description adds no additional parameter semantics. With full schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the specific resource: 'plan type and admin/owner flags for a user'. This distinguishes it from siblings like get-user (user details) and get-balance (account balance), making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly name alternatives, the description is specific enough that an agent can infer when to use this tool (when plan type and flags are needed). It provides clear context without being misleading, and the purpose is self-evident among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata about the current access token (type, scopes, expiration, etc.).
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| scopes | Yes | |
| preview | No | |
| last_used | No | |
| token_type | Yes | |
| created_date | No | |
| expiration_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly notes 'Side effects: none (read-only),' which is helpful, but this largely repeats the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). No additional behavioral traits are disclosed beyond what structured metadata already provides.
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?
Extremely concise: one sentence states the core purpose, and a second sentence covers side effects. Every word earns its place and the main action 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?
Given zero parameters, existing annotations covering read-only and idempotent behavior, and a present output schema, the description is fully sufficient for an agent to select and invoke the tool correctly. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there is no parameter documentation burden. The description adds no parameter-specific details, but none are needed; the baseline of 4 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: retrieving metadata about the current access token, with concrete examples (type, scopes, expiration). This clearly distinguishes it from sibling get-* tools, which target other resources such as faxes, users, or balances.
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 case is clear from the description: when an agent needs details about the current token. It does not explicitly name alternatives or exclusions, but the tool's unique scope among siblings makes the usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get account information for a user.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| uid | Yes | |
| name | No | |
| Yes | ||
| phone | No | |
| status | Yes | |
| lastname | No | |
| settings | No | |
| member_of | No | |
| account_data | No | |
| account_type | Yes | |
| creation_date | Yes | |
| notifications | No | |
| profile_image | No | |
| last_password_modification_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats 'read-only' side effects, but this is already fully captured by annotations (readOnlyHint, idempotentHint, destructiveHint). No behavioral context is added beyond the structured annotations, such as permission requirements, rate limits, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose and with no filler. It is appropriately sized for such a simple 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 one-parameter, read-only tool with a full output schema and strong annotations, the description is almost complete. The main gap is the absence of any sibling differentiation, but the agent has enough schema and annotation context to invoke 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?
The input schema already documents the single user_id parameter with its default ('Default: self'), and schema description coverage is 100%. The description adds no extra parameter semantics, so the baseline score of 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?
The description clearly states the action ('Get') and resource ('account information for a user'), so an agent can understand the basic purpose. It does not explicitly differentiate from siblings like get-member-details or get-token-info, but the scope is still reasonably specific.
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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only additional sentence is about side effects, which does not help with tool selection or usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List webhooks currently registered for a given webhook event type. If event is omitted, returns webhooks for all supported events.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| event | No | Webhook event type. Optional: when omitted, lists all supported events. |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Side effects: none (read-only),' but this mostly restates what the annotations already provide (readOnlyHint, idempotentHint, destructiveHint: false). It adds the 'currently registered' and event-filtering behavior, but doesn't disclose additional behavioral details such as pagination or response characteristics, which are partly covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences present the core operation first, then the optional filter behavior, then the side-effect note. There is no unnecessary padding, and the most important information 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?
This is a simple one-parameter read-only tool, the output schema exists, and the annotations and description together cover safety and behavior. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the event parameter already has a full enum and explanation of the omitted behavior. The description adds little beyond repeating what the schema says, so the baseline of 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?
The description starts with a precise verb-resource pair: 'List webhooks currently registered for a given webhook event type.' It clearly differentiates from create-webhook and delete-webhook siblings and clarifies that omitting the event lists all supported events.
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 when to use the tool: to list webhooks for a specific event type or for all supported events if event is omitted. It doesn't explicitly name alternatives like create-webhook or delete-webhook, but the context makes the read-only listing use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite people to your corporate Fax.Plus account by email (max 10 per call). Pass emails as an array, e.g. ["user@example.com"]. If an address is already on Fax.Plus, the API returns a conflict — use resend-invitations for pending invites that have not joined yet. Manual invites are for orgs that do not provision users via SCIM/SAML; identity-provider-managed orgs should invite from the IdP instead.
Side effects: sends invitation emails.
| Name | Required | Description | Default |
|---|---|---|---|
| emails | Yes | Email addresses to invite (JSON array). Example: ["user@example.com"]. |
| Name | Required | Description |
|---|---|---|
| message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses side effects (sends invitation emails) and error behavior (conflict if address already exists). It clarifies the tool is for manual invites, not IdP-managed orgs. While the annotation destructiveHint=true is not explicitly explained, the description adds context that the main side effect is sending emails, which is consistent with a mutating operation. No contradiction.
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 concise and front-loaded with the core purpose. It includes usage guidance and side effects in a logical order. It avoids unnecessary repetition and is appropriately sized for the tool's complexity.
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 purpose, usage context, side effects, and error handling. Since there is an output schema, return value details are not needed. The tool has one parameter, and the description provides sufficient context for an agent to decide when and how to use it.
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 schema covers the emails parameter with description and example, and the tool description repeats the example and adds the 'max 10 per call' constraint, which is not in the schema. This adds value beyond the schema, though the schema already provides basic 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?
The description clearly states the action (invite), the resource (people to corporate Fax.Plus account), and the method (by email). It specifies a limit of 10 per call and explicitly names resend-invitations as an alternative, distinguishing its purpose from siblings.
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 provides explicit guidance: use resend-invitations for pending invites that have not joined, and use the IdP for identity-provider-managed orgs. It states that manual invites are for orgs not using SCIM/SAML, so the agent knows exactly when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List areas (regions) where numbers can be purchased for a given country.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| country_code | Yes | ISO 3166-1 alpha-2 country code, e.g. US. |
| Name | Required | Description |
|---|---|---|
| areas | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description restates 'Side effects: none (read-only)', which adds no new information and is redundant. It is consistent but does not go beyond annotations to describe behavioral nuances like auth requirements or response format.
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 brief, with the purpose statement front-loaded. However, the second sentence about 'Side effects: none (read-only)' duplicates information already available in annotations, making it slightly redundant. The overall length is appropriate but could be tightened.
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 tool is simple with one parameter and an output schema, so the description's scope is sufficient. It does not need to detail return values since an output schema exists. The only minor gap is a lack of explicit guidance on when to use this tool versus siblings, but the purpose is clear enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so country_code is fully documented in the input schema. The description merely echoes 'for a given country' without adding any new semantic detail, so it meets the baseline without enhancing understanding.
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 ('List'), a precise resource ('areas (regions)'), and the exact scope ('where numbers can be purchased for a given country'). It clearly distinguishes from sibling tools like list-countries and list-numbers by specifying the purpose and required input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring a country_code, but does not explicitly explain when to prefer this tool over alternatives such as list-countries or list-numbers. There is no exclusion guidance or mention of scenarios where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contact groups (Fax.Plus tags) with optional pagination and filters.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Optional list of contact group IDs (max 50). | |
| group | No | Optional group name search term. | |
| limit | No | Page size 1..50 (default 25). | |
| offset | No | Pagination offset (default 0). | |
| shared | No | If true: shared/corporate groups; if false: personal groups. |
| Name | Required | Description |
|---|---|---|
| records | No | |
| total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description's 'Side effects: none (read-only)' restates that rather than adding new behavioral detail. It adds the useful context that contact groups are Fax.Plus tags, but no further behavioral traits are disclosed.
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 short and front-loaded, with the core purpose in the first sentence. The second sentence is redundant with the annotations but does not create significant bloat.
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 operation with a full output schema and 100% schema-described parameters, the description covers the essential purpose and confirms no side effects. It could be improved by explicitly routing between this and sibling list tools, but nothing critical is missing for invoking 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?
Schema description coverage is 100%, with all five optional parameters documented in the schema. The description only refers generically to 'optional pagination and filters' and adds no semantic information beyond the schema, 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 uses a specific verb ('List') and a specific resource ('contact groups'), and the parenthetical '(Fax.Plus tags)' clarifies domain terminology. This distinguishes it from sibling tools like create-contact-group, delete-contact-group, and 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 tool's purpose as a read-only list operation is clear, so when to use it is implied. However, the description does not explicitly mention alternatives or exclusions, such as using list-contacts for contacts rather than groups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts with optional filters (name, fax_number, groups, note), pagination, sorting, and shared/personal filter. Use name=Jane (or fax_number=...) to filter; do not list everything and filter client-side. When sending a fax, always call this after pipeline_start and list-numbers (optional pipeline_id; use limit 20) before request-file-from-user. Do not ask the user for a contact. Response groups are group names (API stores IDs; this tool resolves them).
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Optional list of contact IDs (max 50). When set, other filters are ignored. | |
| name | No | Filter contacts by name (e.g. Jane). | |
| note | No | Filter contacts by note/comment. | |
| sort | No | Sort by: name, creation_date, modification_date. | |
| limit | No | Page size 1..50 (default 20). | |
| groups | No | Filter contacts by group name. | |
| offset | No | Pagination offset (default 0). | |
| shared | No | If true: shared/corporate contacts; if false: personal contacts. | |
| direction | No | Sort direction: asc or desc. | |
| fax_number | No | Filter contacts by fax number. | |
| pipeline_id | No | Returned by pipeline_start. Pass it back unchanged. |
| Name | Required | Description |
|---|---|---|
| records | No | |
| total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces this with 'Side effects: none (read-only).' It also discloses a non-obvious behavior: response groups appear as names even though the API stores IDs, because the tool resolves them.
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 compact, well-organized, and front-loaded with the core purpose and filters. The workflow sentence earns its place because it encodes critical ordering constraints, and the side-effect note is short and reassuring despite being partially redundant with annotations.
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 an 11-parameter read-only list tool with a full input schema and an output schema, the description covers the essential operational context: filtering, pagination, sorting, shared/personal scope, fax workflow ordering, group-name resolution, and the explicit no-side-effects guarantee. An agent has everything needed to invoke 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?
The schema already covers all 11 parameters at 100%, so the baseline is 3. The description adds value beyond the schema by showing example filter syntax (name=Jane), recommending limit 20 in fax workflows, and explaining that groups are resolved from IDs to names in the response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List contacts' and immediately enumerates the available filters, pagination, sorting, and shared/personal modes. It is unambiguous and clearly distinguishable from contact-group or fax-list sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: use filters like name=Jane rather than client-side filtering, and in fax workflows always call this tool after pipeline_start and list-numbers but before request-file-from-user. It also instructs the agent not to ask the user for a contact, which is a concrete exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List countries where you can purchase fax numbers. is_available=false means the country is not enabled for purchase via the API - not that numbers are out of stock. Do not tell the user "no numbers in stock"; say purchase is not available for that country, or list countries with is_available=true.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| countries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description redundantly notes 'Side effects: none (read-only).' However, it goes beyond annotations by explaining the semantics of is_available=false (not enabled for purchase, not out of stock) and prescribing user-facing phrasing, which is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences deliver purpose, a key clarification, and side effects with zero filler. The most important information is front-loaded, and the guidance about is_available is both concise and actionable.
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, parameterless tool with an output schema, the description covers everything an agent needs: what the list contains, how to interpret the availability flag, and how to communicate results to users. The output schema handles return structure, so no additional details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers inputs. The baseline for zero parameters is 4. The description adds no parameter-specific detail, but none is needed; it instead clarifies the meaning of a field in the output, which is helpful but not required for input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('List countries') and a clear domain ('where you can purchase fax numbers'). It distinguishes itself from sibling list tools (list-numbers, list-areas, etc.) by focusing on countries, and the clarification about is_available resolves any ambiguity about what the list contains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's context obvious—countries relevant to fax number purchase—and adds explicit guidance on how to interpret is_available and what to tell the user. It doesn't name alternative tools or state when-not-to-use, but given the tool's simple, unparameterized nature, the context is clear enough without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List fax records for a user. Returns paginated results. Summarize for the user in plain language (sent/failed, pages); do not dump raw API metadata.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Start datetime UTC, format YYYY-MM-DD HH:mm:ss. | |
| limit | No | Page size 1–50 (default 25). | |
| order | No | asc or desc (default desc). | desc |
| before | No | End datetime UTC, format YYYY-MM-DD HH:mm:ss. | |
| offset | No | Pagination offset (default 0). | |
| status | No | Optional status filters. | |
| is_read | No | Optional read filter. | |
| sort_by | No | One of: date, from, to, comment, pages (default date). | date |
| user_id | No | Fax.Plus user ID. Default: self. | |
| category | Yes | One of: inbox, sent, spam. | |
| max_pages | No | Optional maximum page count. | |
| min_pages | No | Optional minimum page count. | |
| to_number | No | Optional E.164 to number filter. | |
| from_number | No | Optional E.164 from number filter. | |
| in_progress | No | Set true to include in-progress incoming faxes (default false). |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| limit | Yes | |
| offset | Yes | |
| records | Yes | |
| has_more | Yes | |
| next_offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it states 'Side effects: none (read-only)' which aligns with the readOnlyHint and destructiveHint annotations, and it instructs the agent to summarize results in plain language and avoid dumping raw API metadata. This is valuable guidance on how to present output, exceeding what annotations convey.
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 sentences long, with the core purpose stated first and the behavioral guidance second. Every sentence earns its place—no redundancy, no fluff. It is front-loaded with the most important information, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 15 parameters and an output schema, the description is appropriately complete. It covers the essential action, scope, pagination, and presentation behavior. The schema handles parameter details, and the output schema covers return structure. The description does not need to enumerate every filter; it provides just enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 15 parameters are documented in the schema. The tool description adds no parameter-specific meaning—it only mentions 'for a user' and 'paginated', which are not tied to any individual parameter. Given the high schema coverage, a baseline score of 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?
The description clearly states the action (list) and resource (fax records) and scope ('for a user'). It also specifies that results are paginated, which adds clarity. However, it does not explicitly differentiate from siblings like list-outbox-faxes, though the distinct purpose is 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?
The description provides no guidance on when to use this tool versus alternatives such as list-outbox-faxes, get-fax, or delete-fax. It does not state prerequisites, exclusions, or conditions that would steer the agent to a different tool. The only usage hint is about output formatting, not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all corporate members in your account.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| members | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the read-only/side-effect-free behavior that is already fully declared by the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It adds no additional behavioral context such as pagination, response size limits, or account scoping details beyond what annotations already provide.
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 short sentences, front-loads the core action and resource, and includes a clear side-effects note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with a rich output schema and full annotation coverage, the description is complete enough for an agent to select and invoke it correctly. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parametersasi and the schema covers 100% of what is needed (an empty object). The description doesn't need to explain parameters, so the baseline of 4 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 clearly states the action ('List') and the resource ('all corporate members in your account'). It is specific enough to distinguish from other list tools like list-contacts or list-faxes, but it does not explicitly differentiate from get-member-details, which is a close sibling for member-related operations.
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 the tool: whenever the agent needs the full set of corporate members in the account. However, it provides no explicit guidance about when not to use it or which sibling tool might be better for individual member details or member management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your purchased or assigned phone numbers. When sending a fax, always call this after pipeline_start (optional pipeline_id) before request-file-from-user. Do not ask the user to pick a number.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. | |
| pipeline_id | No | Returned by pipeline_start. Pass it back unchanged. |
| Name | Required | Description |
|---|---|---|
| numbers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'Side effects: none (read-only)', which reinforces but does not extend beyond the annotations. No contradiction, but no additional behavioral detail like pagination or filtering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus a short side-effect note. It is front-loaded with the primary purpose, then gives targeted usage guidance. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and strong annotations, the description covers the core purpose and a critical workflow dependency. The only gap is not differentiating from list-shop-numbers, but that is a minor omission given the overall clarity.
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 have descriptions in the schema. The description adds context about pipeline_id (used after pipeline_start) but this is already implied by the schema. It does not add significant new meaning beyond the schema, so 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?
The description clearly states the verb 'List' and the resource 'purchased or assigned phone numbers', which distinguishes it from list-shop-numbers (shop numbers) and get-number (single number). The purpose is unambiguous, though it does not explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance for the fax-sending workflow: 'always call this after pipeline_start (optional pipeline_id) before request-file-from-user' and instructs not to ask the user to pick a number. However, it does not cover when not to use this tool or compare with list-shop-numbers, so it's not fully comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List faxes in the outbox that are waiting to be sent. Translate statuses for the user (submitted/converting → preparing; scheduled_for_sending/sending → sending). Do not dump raw status timelines or internals.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| records | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds behavioral details beyond those: it translates statuses (submitted/converting → preparing, etc.) and explicitly instructs not to dump raw status timelines or internals. This is valuable context not covered by annotations. The side-effect note is consistent with 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?
The description is concise and front-loaded, leading with the primary purpose, then adding behavioral notes. Every sentence earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's function, status handling, and read-only safety. It does not mention pagination, output format, or error handling, but an output schema exists to cover return structure. For a read-only list tool with one optional parameter, this is adequately 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?
The single parameter user_id is fully documented in the schema (including a default value), and the description adds no additional parameter-specific information. With 100% schema coverage, the baseline of 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?
The description states the tool lists outbox faxes that are waiting to be sent, a specific verb+resource with a clear condition. This distinguishes it from list-faxes and other fax-related tools. It also mentions status translation, further clarifying the tool's function.
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 clearly implies when to use this tool (to view pending outbound faxes) but does not explicitly mention alternatives or exclusions. It provides enough context for an agent to infer the appropriate scenario, though it stops short of naming sibling tools or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for purchasable fax numbers in a specific country and area (calling) code.
Side effects: none (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| channel | No | 'random' (default) or 'custom'. | random |
| contains | No | Digits the number must contain (only used with channel='custom'). | |
| calling_code | Yes | Area / calling code for the region. | |
| country_code | Yes | ISO 3166-1 alpha-2 country code. |
| Name | Required | Description |
|---|---|---|
| numbers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description repeats the read-only nature ('Side effects: none (read-only)') but adds no new behavioral context such as reservation status, pagination, or relationship to purchase-number. It does not contradict 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?
The description is two sentences and front-loads the core purpose. The second sentence about side effects is redundant with annotations, but it is brief and does not clutter the description. Overall it is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, full parameter descriptions, and annotations, the description is sufficient for an agent to call the tool correctly. It could have explicitly differentiated from list-numbers, but that is already a minor usage-guidance gap already reflected in that score.
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 documents all parameters. The description adds no meaning beyond naming 'country and area (calling) code', which is already captured by the parameter descriptions. No extra details about channel or contains behavior are offered.
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 action ('Search'), a specific resource ('purchasable fax numbers'), and a clear scope ('specific country and area (calling) code'). This distinguishes it from the sibling list-numbers (likely owned numbers) and purchase-number (the actual purchase).
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 clearly implies the use case: finding numbers available for purchase in a specific location. It doesn't explicitly mention alternatives or exclusions, but the word 'purchasable' provides enough context for an agent to know when to choose this over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a new pipeline and returns its pipeline_id. Call this first when sending a fax; pass the returned id to every subsequent pipeline tool, and optionally to list-numbers / list-contacts.
Side effects: none (mints a handle; writes no state).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| pipeline_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a clear side-effect statement: none, beyond minting a handle and writing no state. This supplements the readOnlyHint and destructiveHint annotations, which align with the described behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and uses a separate line for side effects. Every sentence adds operational value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, clear sequencing instructions, and side-effect disclosure, an agent has everything it needs to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema covers everything. The description does not need to document inputs; mentioning the returned pipeline_id is sufficient for invoking subsequent tools.
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 action ('Starts a new pipeline'), identifies the resource, and names the key output (pipeline_id). The fax context and 'call this first' framing clearly distinguish it from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this first when sending a fax, pass the returned id to every subsequent pipeline tool, and optionally use it with list-numbers/list-contacts. This provides exact sequencing and routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purchase a Fax.Plus number by item ID. This has billing impact and requires explicit confirmation.
Side effects: charges account and purchases number.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Fax number item_id to purchase. | |
| confirmation_text | Yes | Must be exactly PURCHASE_NUMBER. |
| Name | Required | Description |
|---|---|---|
| number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the side effects: 'charges account and purchases number.' This goes beyond the annotations (destructiveHint: true, idempotentHint: false) by clarifying the financial impact and the definitive nature of the action personal. There is no contradiction with 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 extremely concise yet effective. The main purpose is stated in the first line, followed by a clear callout of side effects and confirmation requirement. Every sentence earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (billing impact) and that it has an output schema (implicitly, since has_output_schema is true), the description covers all critical contextual aspects: it states the action, the billing impact, the need for confirmation, and the side effects. An agent has enough information to decide and execute 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?
The schema description coverage is 100%, so both parameters are well-documented in the schema. The description adds no extra detail about parameters beyond what's in the schema, but it does emphasize the confirmation requirement, which is a crucial semantic hint. For coverage this high, 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?
The description clearly states the action (purchase) and the resource (Fax.Plus number by item ID). It also distinctively highlights billing impact and explicit confirmation, setting it apart from siblings like revoke-number or update-number, which are about other operations.
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 explicitly notes that this operation has billing impact and requires explicit confirmation, which clearly guides when to use it (when the user intends to purchase a number and has confirmed). It also implies that it should be used only after user consent, distinguishing it from read-only or management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call pipeline_start first, then list-numbers and list-contacts (limit 20), then this tool — always that order. Pass pipeline_id here unchanged. Pass numbers from list-numbers and contacts from list-contacts on this call so the UI can show pickers. Do not re-list inside this tool. Do not ask the user for a sender or destination. Pass optional to/from only if the user already named a number or contact (prefill); omit them otherwise. Prefill to is an array of {number, optional name}; include name when the destination is a contact. from is a number only. Never ask the user to attach the file in chat, and never expect the document to arrive as a chat attachment. NEVER read file contents and NEVER pass base64 or file bytes. Always pass start_file_upload=true and the same pipeline_id. Returns one of three chat payloads. MCP Apps (no mode): widget token in structuredContent; the UI uploads and sends. Do not call send-fax-uploaded or upload-file. mode=unconfirmed: client did not announce Apps support. Relay the user notice, continue as if the UI is present, and use the curl recipe in the same payload only after the user confirms no panel appeared. mode=agentic: client has no Apps support. Follow the curl recipe (POST fax_file), then call send-fax-uploaded with the returned path. Never paste file bytes or base64. Do not call await-fax-upload (removed). Do not call upload-file for chat (automation-only). The UI does not send a chat message when it sends the fax; it adds the submitted fax ids to the conversation context. When a fax_id is known, tell the user the fax was submitted; then get-fax or get-outbox-fax with wait_seconds=30 on the first check.
Side effects: mints a short-lived widget access token; opens the upload UI when the client supports MCP Apps.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Optional destinations. Pass only if the user already named numbers or contacts. Each item is number plus optional contact name. Prefills the UI. Do not ask the user for them. | |
| from | No | Optional sender fax number in E.164. Pass only if the user already named this number. Prefills the UI. Do not ask the user for it. Number only — no name. | |
| numbers | Yes | Sender numbers from the list-numbers result. Pass them through so the UI can offer a from picker. Do not omit after listing. | |
| user_id | No | Optional Fax.Plus user ID. Omit for self. Must be a UUID (dashed or 32-hex) or 24-char ObjectId (not a phone number). | |
| contacts | Yes | Contacts from the list-contacts result (name + fax_number). Pass them through so the UI can offer a to picker. Do not omit after listing. | |
| pipeline_id | Yes | Returned by pipeline_start. Pass it back unchanged. | |
| start_file_upload | Yes | Always pass true so the confirmation request is not empty. Ignored by the server. |
| Name | Required | Description |
|---|---|---|
| mode | No | |
| token | No | |
| method | No | |
| message | Yes | |
| numbers | No | |
| prefill | No | |
| contacts | No | |
| endpoint | No | |
| expiresAt | No | |
| field_name | No | |
| instructions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as non-read-only, non-idempotent, and destructive, and the description adds substantial behavior: it mints a short-lived widget token, opens the upload UI, never receives file bytes/base64, and behaves differently in unconfirmed, agentic, and MCP Apps modes. It also explains what happens after the UI sends the fax and how to follow up. No contradiction with the annotations; the description strengthens behavioral transparency.
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 information-dense and front-loaded with the critical call order, but it is also verbose and somewhat repetitive. Examples include saying twice not to paste file bytes/base64 and repeating the instruction not to call upload-file. A tighter structure with explicit mode sections would make it easier to process while retaining the important caveats.
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 is complete for a complex interactive tool: it covers the required predecessor calls, parameter pass-through, all three client modes, the exact next actions after upload, output payload expectations, and side effects. The presence of an output schema further reduces the need to describe return values. An agent has enough information to invoke this tool correctly in any of the stated modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context: pass pipeline_id unchanged, pass list-numbers and list-contacts results through as picker sources, only prefill to/from when the user already named them, and never ask for them. It clarifies the relationship between parameters and the surrounding workflow rather than merely restating schema field types.
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 makes clear that this tool is the step after pipeline_start, list-numbers, and list-contacts, and that it drives the upload UI rather than actually sending or uploading a file. It distinguishes itself from siblings by explicitly saying not to call send-fax-uploaded or upload-file. However, it never opens with a crisp one-sentence statement of the tool's core purpose ('requests a file from the user'), instead relying on the tool name, title, and surrounding workflow instructions.
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 explicit ordering requirements: call pipeline_start first, then list-numbers and list-contacts, then this tool. It also says when not to use it, names the alternatives not to call, and explains the three client modes with conditions. This is exactly the guidance an agent needs to decide when and how to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a new outbound fax by reusing an existing fax file reference via from_fax. to must be an array of destination numbers.
Side effects: queues outbound fax for delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination fax numbers as a JSON array of E.164 strings, e.g. ["+15551234567"]. Never a bare string. | |
| from | Yes | Sender fax number in E.164 form, e.g. +15559876543. | |
| comment | No | Optional comment to set for the fax job. | |
| options | No | Optional send options. | |
| user_id | No | Optional Fax.Plus user ID. Omit for self. Must be a UUID (dashed or 32-hex) or 24-char ObjectId (not a phone number). | |
| send_time | No | Optional scheduled send time, format YYYY-MM-DD HH:mm:ss +HHMM. | |
| cover_page | No | Optional fax cover page payload. | |
| resolution | No | Optional resolution: fine or superfine. | |
| return_ids | No | Optional return scheduled fax IDs flag. | |
| from_fax_id | Yes | Existing fax session ID to reuse as source document. | |
| from_fax_user_id | No | Optional owner user ID for from_fax. Omit for self. Must be a UUID (dashed or 32-hex) or 24-char ObjectId. |
| Name | Required | Description |
|---|---|---|
| ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the side effect: 'queues outbound fax for delivery.' This is consistent with the destructiveHint=true annotation, which already warns of side effects. The description adds a bit of context by naming the specific side effect, but it does not go beyond to mention costs, rate limits, or the fate of the original fax. Given that annotations already flag destructiveness, this adds marginally useful context without contradiction.
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 exactly two sentences, with no filler. The first sentence delivers the core purpose and method, and the second adds the side effect. It is front-loaded and every word 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?
The tool has 11 parameters with full schema coverage and an output schema (has output schema: true). The description covers the essential purpose and side effect, which is sufficient for an agent to decide when to invoke it. It could mention explicit differences from send-fax-uploaded, but that is not essential given the clarity of the core action. Overall, it provides adequate context for a correctly specified tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented in the input schema. The description adds a minor clarification that 'to must be an array of destination numbers' and reinforces the role of from_fax, but does not add significant meaning beyond the schema. Since the schema handles the heavy lifting, a baseline of 3 is appropriate per the rubric.
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 clear verb ('Queue') and resource ('new outbound fax') along with the specific method ('reusing an existing fax file reference via from_fax'). This distinguishes it from siblings like send-fax-uploaded, which likely sends a new fax from an uploaded file, so an agent can immediately understand the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you want to resend an existing fax by referencing its file via from_fax. It does not explicitly name alternative tools, but the phrase 'reusing an existing fax file reference' and 'Queue a new outbound fax' clearly set the context. While it doesn't say 'use send-fax-uploaded instead for new documents', the purpose is unambiguous enough for an agent to infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resend pending corporate member invitations by email (max 10 per call). Only works for addresses that were invited but have not joined yet. Pass emails as an array, e.g. ["pending@example.com"].
Side effects: sends invitation emails.
| Name | Required | Description | Default |
|---|---|---|---|
| emails | Yes | Email addresses with pending invitations to resend (JSON array). Example: ["pending@example.com"]. |
| Name | Required | Description |
|---|---|---|
| message | No |
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 explicit behavioral context: 'Side effects: sends invitation emails' and the max-10-per-call limit. It also clarifies the prerequisite (pending and not joined). These details go beyond the annotations and are directly useful for the agent to anticipate consequences.
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 concise, with purpose front-loaded, followed by the limit, the condition, an example, and the side effect. Every sentence earns its place, and there is no redundancy or 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 single-parameter tool with an output schema, the description covers all necessary operational aspects: the action, the limit, the condition, and the side effect. An agent has enough information to call it correctly without missing prerequisites or consequences.
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%, with the parameter already documented as 'Email addresses with pending invitations to resend (JSON array). Example: ["pending@example.com"]'. The description repeats the array format and example, adding no new semantic information beyond what the schema provides. Baseline 3 is appropriate because the schema already carries the 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?
The description states a specific verb ('Resend') and resource ('pending corporate member invitations by email'), and it distinguishes itself from sibling tools like invite-members (new invitations) and resend-fax (fax resending). The limit of 10 per call and the condition of pending/not-yet-joined add further specificity. It is clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool works: only for addresses that were invited but have not joined. This is a clear usage condition. It does not explicitly name alternatives (e.g., invite-members for new invitations), but the condition and the context of pending invitations make the intended use evident. A small gap is not mentioning when not to use it (e.g., for already-joined members).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a corporate member's assignment to a fax number (DELETE assigned_to entry). user_id is the member to REMOVE from the number — NOT the owner and NOT 'who is calling'. To unassign Dom User, pass Dom User's user ID. Using self removes YOUR own assignment (common mistake). Does not cancel the number, delete it, or change owner_id. Number cannot be revoked from the admin/owner in some cases.
Side effects: removes the named member from the number's assigned_to list (does not cancel the number).
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Fax number in E.164 form, e.g. +1234567890. | |
| user_id | Yes | REQUIRED: user ID of the member whose assignment to remove from the number. Pass the member UUID (e.g. Dom User). Use self ONLY to remove your own assignment. Do not default to self when unassigning someone else. | |
| confirmation_text | Yes | Must be exactly REVOKE_NUMBER. |
| Name | Required | Description |
|---|---|---|
| number | Yes | |
| message | Yes | |
| revoked | Yes | |
| revoked_from_user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, and the description adds valuable scoping: only the assigned_to entry is removed, the number itself is not canceled, and owner_id is untouched. It also warns about the common self-unassignment mistake and an admin/owner limitation.
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?
Core action is front-loaded, followed by essential warnings and side effects. It is a little repetitive around 'does not cancel the number', but the length is justified for a destructive operation with a subtle user_id parameter.
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 tool with 3 required parameters, the description covers all important operational details: parameter semantics, confirmation_text behavior was left to schema, the actual mutation scope, and an edge case. An output schema exists, so return-value detail is not required.
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 schema already covers all three parameters, but the description significantly clarifies user_id semantics by stressing that it is the member to remove, not the owner, not 'who is calling', and that 'self' only unassigns the current caller. This goes beyond the raw 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 clearly states the action: remove a member's assignment to a fax number via a DELETE on the assigned_to entry. It explicitly distinguishes this from canceling or deleting the number, and from changing owner_id, which sets it apart from sibling tools like update-number or purchase-number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear picture of when to use the tool: revoking a member from a number. It explicitly warns about what the tool does not do (cancel/delete/owner change) and calls out an admin/owner edge case, though it does not name alternative sibling tools for each 'not' case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a new outbound fax using storage paths. Call this after an agentic request-file-from-user curl (files = path from the files POST JSON) or after upload-file (automation). Do not call this after the MCP Apps UI flow — the widget already sent. Pass paths here with to/from and optional send_time. Do not pass local filesystem paths or file bytes. to must be an array. The same paths may be reused for multiple sends. Success means queued/submitted only—not delivered. Tell the user the fax was submitted. If you check status, call get-fax or get-outbox-fax with the returned id and optional wait_seconds=30 on that first check (omit wait_seconds later). Do not narrate tool names or HTTP details to the user.
Side effects: queues outbound fax for delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination fax numbers as a JSON array of E.164 strings, e.g. ["+15551234567"]. Never a bare string. | |
| from | Yes | Sender fax number in E.164 form, e.g. +15559876543. | |
| files | Yes | Uploaded file paths from the files POST JSON (agentic request-file-from-user) or from upload-file (typically starting with /storage). | |
| comment | No | Optional comment to set for the fax job. | |
| options | No | Optional send options. | |
| user_id | No | Optional Fax.Plus user ID. Omit for self. Must be a UUID (dashed or 32-hex) or 24-char ObjectId (not a phone number). | |
| send_time | No | Optional scheduled send time, format YYYY-MM-DD HH:mm:ss +HHMM. | |
| cover_page | No | Optional fax cover page payload. | |
| resolution | No | Optional resolution: fine or superfine. | |
| return_ids | No | Ignored; fax IDs are always returned on success. | |
| pipeline_id | Yes | Returned by pipeline_start. Pass it back unchanged. |
| Name | Required | Description |
|---|---|---|
| queued | Yes | |
| fax_ids | No | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a non-readonly, non-idempotent, destructive operation. The description adds key behavior beyond annotations: 'Success means queued/submitted only—not delivered' and 'Side effects: queues outbound fax for delivery.' This clarifies the asynchronous nature of the action. No contradiction with annotations; the destructiveHint=true aligns with 'side effects' even though the operation creates rather than deletes.
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 dense but not bloated; every clause carries operational guidance. The main action is front-loaded, followed by usage context, exclusions, success semantics, and post-call status checking. Slight redundancy between 'Success means queued/submitted only' and the 'Side effects' line, but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, nested objects, output schema present) the description covers all critical context: required prerequisites (uploaded files), prohibited inputs (local paths, bytes), status verification flow, and user-facing communication guidance. Nothing an agent needs to invoke this correctly appears 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 baseline is 3. The description goes beyond the schema by clarifying that `files` come from the 'files POST JSON' or upload-file (typically /storage), and by reinforcing that `to` must be an array and local paths/bytes are forbidden. This adds practical usage meaning not captured in the parameter 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?
The description opens with a specific verb and resource: 'Queue a new outbound fax using storage paths.' It clearly distinguishes this from related tools by defining the input type (storage paths, not bytes) and explicitly referencing sibling flows (request-file-from-user, upload-file, MCP Apps UI).
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 explicit when-to-use guidance: call after request-file-from-user or upload-file, never after the MCP Apps UI flow. It also provides exclusions ('Do not pass local filesystem paths or file bytes') and routes subsequent status checks to get-fax/get-outbox-fax with wait_seconds guidance. No inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign contacts to contact groups (Fax.Plus tags). Pass group names (e.g. Vendors), not group IDs from create-contact-group. This overwrites previous group assignments for the selected contacts. If a model passes a group ID by mistake, this tool resolves it to the group name before calling the API.
Side effects: updates contact-group associations.
| Name | Required | Description | Default |
|---|---|---|---|
| groups | No | Group names to assign (e.g. Vendors), not group IDs. Overwrites existing assignments for these contacts. | |
| shared | No | If true: shared/corporate contacts and groups; if false: personal. | |
| contact_ids | Yes | Contact IDs to update. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructive=true, and the description adds the critical detail that previous group assignments for the selected contacts are overwritten. It also discloses automatic group-ID-to-name resolution and a side-effects line, which are not present in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose, then parameter guidance, then side effects. The explicit 'Side effects' line is slightly redundant with the overwrite sentence, but it does not add meaningful bloat.
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 3-parameter mutation tool with annotations and an output schema, the description covers purpose, parameter semantics, and side effects. It does not discuss prerequisites such as whether the named groups must already exist or the behavior of the shared flag, though the schema does cover the shared flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds valuable semantic guidance beyond the schema: group names come from create-contact-group as IDs and must be converted, and a mistaken ID is auto-resolved to a name. This extra handling of the groups parameter justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Assign contacts to contact groups') and clarifies the domain ('Fax.Plus tags'). It also distinguishes itself from create-contact-group by explicitly saying group names, not group IDs from that tool, which prevents a common mix-up.
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 operational context: pass names rather than IDs, and be aware that this tool replaces prior assignments. It does not explicitly state when to prefer this tool over close siblings such as share-contact-groups or update-contact, so it misses the exclusion guidance needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update an existing contact. Omit fields you want to keep; only set fields to change. The Fax.Plus API uses PUT (full replace), so this tool loads the contact, merges your fields, and writes the full record back - omitted fields are preserved. If setting groups, use group names (e.g. Vendors), not group IDs.
Side effects: modifies contact.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Fields to change only. Omitted fields are preserved. groups must be group names, not IDs. | |
| contact_id | Yes | Contact ID. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| No | ||
| notes | No | |
| phone | No | |
| groups | No | |
| cellphone | No | |
| is_shared | No | |
| fax_number | No | |
| is_telefax | No | |
| creation_date | No | |
| modification_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the annotations: it explains that the underlying API uses PUT full-replace and that the tool loads the contact, merges fields, and writes the full record back so omitted fields are preserved. The group-name-vs-ID warning and 'modifies contact' side effect also add transparency.
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?
Every sentence earns its place: the first states the operation, the second explains the critical PUT-merge nuance, the third clarifies group input, and the final line flags the side effect. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with a nested payload and an output schema, the description fully covers what an agent needs to call it correctly: which fields to supply, how preservation works, how to format groups, and the fact that the operation mutates data. Nothing essential 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 the schema already documents contact_id and payload. The description still adds value by explaining the merge semantics behind 'omit fields to keep' and by reinforcing the group-name requirement with an example ('Vendors'), going slightly beyond the schema's wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Partially update an existing contact.' It also clarifies the partial-update behavior ('Omit fields you want to keep; only set fields to change'), making it distinct from create-contact, delete-contact, and set-contact-groups.
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 clearly establishes when to use the tool: to modify an existing contact by providing only changed fields. It does not explicitly name alternatives or exclusions, but the partial-update framing gives enough context to distinguish it from create/delete/set operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a contact group (Fax.Plus tag).
Side effects: modifies contact group.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Contact group update payload. | |
| group_id | Yes | Contact group ID. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| name | No | |
| notes | No | |
| is_shared | No | |
| creation_date | No | |
| modification_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true. The 'Side effects: modifies contact group' line reinforces that in plain language but adds little nuance beyond what annotations provide, such as partial-update behavior or effects on contacts assigned to the tag. It does not contradict 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?
The description is very short and front-loaded with the core purpose. The side-effects line is somewhat redundant with the annotations but remains concise and non-wasteful.
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 basic purpose, parameters, and safety profile are covered, and an output schema exists. However, the tool lacks explicit guidance on partial-update semantics (e.g., whether omitting name clears it) and on how it differs from set-contact-groups, leaving some ambiguity for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents group_id and the payload object with its name and notes properties. The description adds no parameter-level detail, but none is needed given the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('contact group'), and clarifies that the resource is a Fax.Plus tag. This distinguishes it from update-contact and related tools, though it mostly mirrors the tool name and title.
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 tool instead of alternatives like create-contact-group, set-contact-groups, or update-contact. An agent has to infer the use case from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a fax record's read state and/or comment.
Side effects: modifies fax record metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| fax_id | Yes | Fax ID to update. | |
| payload | Yes | Update payload with is_read and comment. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| fax_id | Yes | |
| updated | Yes | |
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that 'side effects: modifies fax record metadata', which aligns with the annotations and gives a minimal idea of what changes. It does not explain irreversible consequences, permission requirements, or whether the update is partial or complete.
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 short and front-loads the action and target. The side-effects note is useful and placed separately. No verbose or redundant text, though a one-sentence elaboration on payload requirements would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description provides a minimally viable picture: what it updates and that it has side effects. It lacks explicit guidance on when to use it versus bulk/sibling update tools paddle and on any edge cases like required read state or comment semantics for a 3-param tool with a nested payload.
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 each parameter is documented. The description names the two main updatable values (read state and comment) but does not explain the exact payload shape or the meaning of user_id beyond the schema's 'Default: self'. It adds little 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 clearly states the tool updates a fax record's read state and/or comment, naming the specific resource and the fields modified. However, it does not explicitly contrast with sibling tools like bulk-update-faxes or update-outbox-fax, so some sibling differentiation is left to the names and schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it updates a fax record's metadata)Skip earlier. It does not state when to prefer this tool over bulk-update-faxes or update-outbox-fax, nor does it mention any preconditions such as user authorization. The context of the operation is implied by the tool name and fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a corporate member's role and/or monthly fax quota.
Side effects: modifies member role/quota.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Member update payload (role and/or quota). | |
| member_user_id | Yes | Fax.Plus member user ID. |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| member_user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds specificity by stating 'Side effects: modifies member role/quota.' This clarifies exactly what is mutated, going beyond the generic destructive annotation. It does not contradict annotations and provides useful context about the impact of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The purpose is front-loaded in the first sentence, and the side effect is noted in the second. Every word earns its place, making it efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, nested payload) and the presence of an output schema (signal indicates true), the description is largely complete. It states the operation and side effects. A minor gap is that it doesn't explicitly clarify whether the update is partial (e.g., only changing one field) or resets unspecified fields, but the 'and/or' phrasing implies partial updates. Overall, adequate for the tool's complexity.
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 parameters (payload and member_user_id) have descriptions in the schema. The description adds no new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate. It mentions role and quota, but these are already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('corporate member's role and/or monthly fax quota'), which clearly identifies the tool's function. It distinguishes from sibling tools like get-member-details (read) and update-user (different resource). The scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it updates, but does not explicitly mention when to use it versus alternatives (e.g., update-user or get-member-details) or any prerequisites. There is no exclusions or routing guidance, leaving the agent to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a fax number to a corporate member (adds them to assigned_to). user_id is the number owner/account context (usually self for the admin). payload.assigned_to is the member user ID to assign TO. To remove a member's assignment, use revoke-number with that member's user_id — do not use revoke-number with self unless you intend to remove your own assignment.
Side effects: adds a member to the number's assigned_to list.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Fax number in E.164 form, e.g. +1234567890. | |
| payload | Yes | Must set assigned_to to the member user ID to assign the number TO. | |
| user_id | No | Number owner / account context. Use self for the admin who owns the number. Default: self. |
| Name | Required | Description |
|---|---|---|
| number | Yes | |
| updated | Yes | |
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal mutation (readOnlyHint=false, destructiveHint=true), and the description adds the specific side effect: 'adds a member to the number's assigned_to list.' It does not detail edge cases such as duplicate assignment or failure behavior, but it goes beyond the annotations without contradicting them.
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 compact and front-loaded: action and side effect first, then parameter clarification, then the critical revoke-number warning. No sentence is wasted and every part contributes to correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3-parameter nested payload, full schema coverage, output schema, and annotations, the description covers what remains: the exact assignment effect and the revoke alternative. An agent has enough context to call this tool correctly without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents number and payload. The description adds practical context beyond the schema, such as 'user_id is the number owner/account context (usually self for the admin)' and 'payload.assigned_to is the member user ID to assign TO', which helps an agent pick the right owner versus target.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and resource: 'Assign a fax number to a corporate member' and specifies the underlying effect ('adds them to assigned_to'). It also differentiates itself from revoke-number by naming the sibling and the opposite action, so an agent can distinguish it immediately.
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 explicit direction for when to use this tool versus the alternative: use revoke-number with that member's user_id to remove, while warning not to use revoke-number with self unless removing your own assignment. It also clarifies user_id as owner/account context, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a queued outbox fax (comment only).
Side effects: modifies outbox record metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Outbox update payload. | |
| user_id | No | Fax.Plus user ID. Default: self. | |
| outbox_fax_id | Yes | Outbox fax ID to update. |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| user_id | Yes | |
| outbox_fax_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true; the description adds the specific side effect that it modifies outbox record metadata, clarifying that it does not send or delete the fax. No contradiction with 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 short sentences with the purpose front-loaded and the side effect stated separately. Every sentence earns its place; 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 single-record metadata update, the description, complete schema, annotations, and output schema cover purpose, scope, and side effects. It lacks explicit alternative routing, but that gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents outbox_fax_id, payload.comment, and user_id. The description's 'comment only' reinforces intent but adds no new parameter-level 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 ('Update') and resource ('queued outbox fax'), and scopes the operation to 'comment only'. This clearly differentiates it from related tools like update-fax or bulk-update-outbox-faxes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a single queued outbox fax, and sibling names suggest bulk alternatives, but it does not explicitly state when to use this tool versus update-fax or bulk-update-outbox-faxes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update account profile/settings for a user (usually 'self').
Side effects: modifies user profile/settings.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Account update payload. | |
| user_id | No | Fax.Plus user ID. Default: self. |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=true, so the description's 'Side effects: modifies user profile/settings' adds little beyond what structured data conveys. It doesn't disclose important behaviors such as whether the update replaces the whole profile, whether missing fields are reset, what authentication is required, or what error cases may arise. No contradiction exists, but the added insight is minimal.
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 very short and front-loaded, with the core purpose stated in the first sentence. The second sentence ('Side effects...') is mostly redundant with the update intent and annotations, which costs it full marks, but there is no rambling or unnecessary content.
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 complex tool with a very detailed nested payload and a large output schema, yet the description gives only a high-level purpose. It lacks guidance on partial vs. full updates, required nested fields, impact on existing settings, or authorization context. While the large schema compensates somewhat, an agent calling this tool still lacks critical usage context.
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 input schema provides 100% description coverage, with both payload and user_id documented in the schema. The tool description itself adds no parameter-level meaning, but because the schema already carries the semantics, the baseline score of 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?
The description states a clear verb-resource pair: 'Update account profile/settings for a user'. It also scopes the common use case to 'usually self,' which helps orient agents. It doesn't explicitly differentiate from update-member-details, but the resource target (account profile/settings) is reasonably distinct from the many other update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites, access requirements, or when not to call it. The parenthetical 'usually self' is a mild hint for one common case but falls far short of robust usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automation-only: upload document bytes as base64 for non-chat integrations, then call send-fax-uploaded with the returned path. NEVER use this in chat — call pipeline_start, list-numbers, list-contacts, then request-file-from-user (UI or curl). File bytes must not pass through the model for chat flows. Never expect a document as a chat attachment.
Side effects: stores file for fax delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Optional file format hint: pdf or tiff. | |
| user_id | No | Optional Fax.Plus user ID. Omit for self. Must be a UUID (dashed or 32-hex) or 24-char ObjectId (not a phone number). | |
| file_name | Yes | File name to store (for example, contract.pdf). | |
| mime_type | No | Optional MIME type (for example application/pdf). | |
| pipeline_id | Yes | Returned by pipeline_start. Pass it back unchanged. | |
| file_content | Yes | Document bytes as a base64 string. Data URI format is also accepted. |
| Name | Required | Description |
|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveHint=true and readOnlyHint=false, and the description adds meaningful context beyond that: it stores the file for fax delivery and warns that file bytes must not pass through the model for chat flows. This extra behavioral context is valuable, though it could have disclosed more about storage semantics.
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 front-loaded with the primary purpose and usage restriction, then provides the alternative flow. It is slightly dense and includes some repeated warnings, but every sentence contributes practical guidance and no irrelevant content is present.
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 tool with a full output schema, complete parameter descriptions, and annotations covering mutation behavior, the description covers the remaining important context: automation-only usage, the required next step, the chat-flow alternative, and side effects. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all six parameters including pipeline_id, file_content, and user_id constraints. The description does not add much parameter-level meaning beyond the schema, which matches the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: upload document bytes as base64 for non-chat integrations, with a clear follow-up step (call send-fax-uploaded with the returned path). It also distinguishes this tool from chat-related flows, so an agent can tell it apart from request-file-from-user and pipeline_start without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Automation-only' and 'NEVER use this in chat', then names the correct chat flow: pipeline_start, list-numbers, list-contacts, then request-file-from-user. This gives both when-to-use and when-not-to-use guidance, plus the exact alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
bulk-delete-faxesbulk-delete-outbox-faxesbulk-update-faxesbulk-update-outbox-faxescreate-contactcreate-contact-groupcreate-webhookdelete-contactdelete-contact-groupdelete-faxdelete-outbox-faxdelete-webhookget-balanceget-faxget-fax-reportget-fax-thumbnailget-fileget-file-pageget-member-detailsget-numberget-outbox-faxget-planget-token-infoget-userget-webhooksinvite-memberslist-areaslist-contact-groupslist-contactslist-countrieslist-faxeslist-memberslist-numberslist-outbox-faxeslist-shop-numberspipeline_startpurchase-numberrequest-file-from-userresend-faxresend-invitationsrevoke-numbersend-fax-uploadedset-contact-groupsshare-contact-groupsshare-contactsupdate-contactupdate-contact-groupupdate-faxupdate-member-detailsupdate-numberupdate-outbox-faxupdate-userupload-file
Add one secure layer between your agents and this server.
