Fax.Plus

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

The description's 'Side effects: modifies multiple fax records' adds a clear statement of mutating behavior, but this largely restates the destructiveHint=true annotation. It does not disclose additional behavioral traits such as whether the operation is reversible, whether comments overwrite or append, or whether partial failures are possible.

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 readable. The second sentence on side effects is somewhat redundant with the destructiveHint annotation but still serves as a useful explicit reminder and 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 mutation tool with rich annotations, a fully described input schema, and an output schema present, the description covers the essential what and the key side effect. The main missing piece is explicit routing guidance relative to sibling bulk-update and single-update tools, but the schema and annotations carry 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 the schema already documents payload and user_id. The description adds a small amount of semantic context by naming is_read and/or comment as the updatable fields, but it does not significantly enrich the parameter meaning beyond what the schema provides.

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

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

The description states a specific action and resource: 'Update multiple fax records in one request', with the two relevant fields (is_read and/or comment). It is clear what the tool does, but it does not explicitly distinguish this from the sibling bulk-update-outbox-faxes, relying on the tool names to carry that distinction.

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

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

The phrase 'Update multiple fax records in one request' implies this tool is for batch updates rather than single-record updates, and the sibling update-fax suggests a single-fax alternative. However, there is no explicit guidance about when to prefer this tool over bulk-update-outbox-faxes or update-fax, and no exclusions are mentioned.

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

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

Annotations already mark this tool as destructive and non-idempotent, so the safety profile is covered structurally. The description adds an explicit 'Side effects: modifies multiple outbox records' line, which is consistent but mostly restates the update operation and the destructiveHint. No additional context about irreversibility or permissions is provided.

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 the core action front-loaded and the side-effect note immediately following. There is no filler, repetition of the title beyond what is useful, or unnecessary qualification.

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 input schema, output schema, and annotations cover most of what an agent needs to invoke the tool correctly. The description covers the operation and side effects, though it could be slightly more explicit about constraints such as whether only queued faxes are eligible or how invalid IDs are handled.

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 payload, ids, comment, and user_id. The description's mention of 'multiple' and 'comment' only reinforces the ids/comment fields and does not add meaningful new parameter-level 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 names a specific verb ('Update'), a specific resource ('outbox faxes'), a field ('comment'), a cardinality ('multiple'), and a batching characteristic ('in one request'). This distinguishes it clearly from the single-item sibling 'update-outbox-fax' and from the broader '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 gives clear context: use this tool when you need to change comments on several queued outbox faxes at once. It stops short of naming the alternative single-update tool or stating when not to use it, so it lacks explicit exclusion guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=true, and the description reinforces the mutation by noting 'Side effects: creates contact.' It does not add much beyond that or provide additional behavioral context such as permissions, idempotency, or duplicate handling, 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 compact, with the main purpose stated first and constraints following. The 'Side effects: creates contact' line is somewhat redundant with the first sentence, but the overall structure is efficient and easy to scan.

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

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

Given the 100% schema coverageinches and the presence of an output schema, the description covers the essential behavioral constraints: required fields, E.164 format, and group-name semantics. It could add when to choose this over update-contact, but that is a minor omission for a straightforward create 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 description coverage is 100%, so the schema already documents all 9 parameters. The description repeats the required fields and E.164/group-name constraints but does not add meaning beyond what the schema provides.

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

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

The description opens with 'Create a new contact in Fax.Plus address book' — a specific verb, resource, and service scope. It clearly distinguishes the tool from siblings like update-contact, delete-contact, list-contacts, 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?

The description explicitly states required fields (name and fax_number) and important constraints like E.164 format and group names vs IDs. It does not explicitly name update-contact as the alternative for modifying an existing contact, but the use case is unambiguous from 'Create a new contact'.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation behavior is covered. The description adds a useful behavioral note about using the group's name instead of its id when assigning contacts, which is beyond annotation scope. 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?

The description is concise, with two sentences plus a side-effect line. It front-loads the primary purpose and includes a practical tip. No unnecessary words.

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

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

Given the existence of an output schema, return values don't need explanation. However, the description lacks parameter explanations and does not mention any constraints or related tools (e.g., check existing groups). For a tool with zero schema coverage, this is insufficient for confident 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 0%, so the description must explain parameters. It does not explain the meaning of 'notes' or 'shared', nor does it clarify that 'name' is a string and required. This leaves agents guessing about parameter semantics, which is a significant gap.

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

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

The description clearly states the verb 'create', the resource 'contact group', and the purpose 'to organize contacts'. It also differentiates from related tools by explaining how the group's name is used when assigning contacts, which helps distinguish it from set-contact-groups or update-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?

The description implies usage for creating a new group and gives specific guidance on how to reference the created group when assigning contacts, which is helpful. However, it does not explicitly contrast with alternatives like update-contact-group or list-contact-groups, so it's somewhat implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds important context: it explicitly states 'requires explicit confirmation' and lists the side effect 'deletes contact.' This goes beyond the annotations by clarifying the confirmation requirement and the exact effect, giving the agent full awareness of the operation's 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 exceptionally concise: two short sentences that are front-loaded with the core purpose, followed by critical safety notes. Every word earns its place, with no fluff or redundancy. It is well-structured and easy to parse quickly.

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 delete operation with a complete schema, annotations covering safety, and an output schema present, the description covers everything an agent needs: the action, the destructive nature, the confirmation requirement, and the side effect. 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 both parameters (contact_id and confirmation_text) are already described in the schema. The description does not add any additional parameter-level meaning beyond what the schema provides. Since the schema fully documents the parameters, 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 and resource: 'Delete a contact.' This distinguishes it from sibling tools like create-contact and update-contact. It also explicitly marks the operation as destructive and requiring confirmation, which adds specificity.

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 (when you need to remove a contact) and highlights the need for explicit confirmation. While it doesn't explicitly name alternatives or exclusion conditions, the tool's name and clear destructive nature make the usage context obvious. It provides adequate guidance without being verbose.

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

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

The description adds the explicit confirmation requirement ('requires explicit confirmation') and reiterates destructiveness, which goes beyond the annotations that already declare destructiveHint=true. It also states 'Side effects: deletes contact group,' which is redundant but harmless. It provides useful behavioral context for the confirmation_text parameter.

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, front-loaded with the action and side effects. Every word adds value, and it is concise without being under-specified.

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 delete operation, the description covers the core purpose, side effects, and confirmation requirement. It does not detail error handling or return values, but the output schema exists and the tool is straightforward. The lack of explicit alternative guidance is a minor gap.

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

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

The input schema already describes both parameters (group_id and confirmation_text) with 100% coverage. The description does not add any extra meaning about the parameters themselves; it only mentions that confirmation is needed, which is already implied by the schema's description of confirmation_text. 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 and resource: 'Delete a contact group (Fax.Plus tag).' It is specific and not a tautology. However, it does not differentiate from sibling tools like 'delete-contact' or 'delete-fax', so a slight deduction for lack of distinction.

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

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

The description notes that the action is destructive and requires explicit confirmation, which is a usage caution, but it does not specify when to use this tool versus alternatives or provide any context for when it is appropriate. No mention of alternatives or conditions.

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

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

Annotations already mark destructiveHint=true, so the description adds marginal value by stating the operation is destructive and requires explicit confirmation. The 'Side effects: deletes fax record' line only restates the main action and adds no new behavioral detail beyond the annotation.

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

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

The description is short and front-loaded with the core action, which is good. However, the second sentence 'Side effects: deletes fax record' is redundant with the first sentence and does not earn its place, making the structure slightly 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?

For a simple delete operation with full schema coverage, an output schema, and destructiveHint annotation, the description covers the essential behavioral caveat: explicit confirmation is required. It is complete enough to invoke correctly, though it would benefit from naming the outbox variant as the alternative for outbox faxes.

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 coverage is 100%, so the baseline is 3. The description's mention of 'explicit confirmation' gives slight context for the confirmation_text parameter, but it does not explain fax_id, user_id, or the exact confirmation semantics beyond what the schema already states.

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

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

The description states a clear verb and resource: 'Delete a fax record.' It is not a tautology, but it does not explicitly differentiate from the sibling tool delete-outbox-fax, so the agent must infer the distinction from the tool name rather than the description.

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

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

The description gives no guidance on when to use this tool versus alternatives such as delete-outbox-fax or update-fax. The warning that the operation is destructive and requires explicit confirmation is safety guidance, not usage context.

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

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

Annotations already declare destructiveHint=true, and the description reinforces that, adding the explicit confirmation requirement and stating the side effect directly. This gives useful behavioral context beyond what the annotation alone provides, though some of it duplicates schema fields.

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

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

The description is short and front-loaded with the core action. The 'Side effects' sentence is somewhat redundant with the first sentence, but the overall size is appropriate 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?

The tool is a simple destructive delete with a complete input schema, an output schema, and annotations that already mark it destructive. The description covers the essential safety requirement and side effect, making it sufficient without needing extensive additional detail.

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 describes outbox_fax_id, confirmation_text, and user_id. The description adds no additional parameter-level meaning, 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 names a specific verb ('Delete a queued outbox fax record') and identifies the exact resource being acted on. It stands apart from sibling delete-fax by explicitly saying 'outbox fax', so an agent can distinguish the target without opening the schema.

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

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

The description gives no explicit when-to-use guidance, exclusions, or alternatives among siblings such as delete-fax, bulk-update-outbox-faxes, or get-outbox-fax. It mostly restates the action rather than explaining the conditions for choosing this tool over siblings.

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

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

Annotations already mark it readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description echoes that with 'Side effects: none (read-only).' It goes further by disclosing the race-condition behavior where an immediate 4xx is expected unless wait_seconds=30 is passed, and it instructs the agent on presenting status to the user in everyday language rather than raw fields. These are valuable 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?

The description is compact and front-loaded with purpose, then the critical timing caveat, then the user-facing output guidance, then side effects. There is some redundancy with the schema's wait_seconds description, but each sentence earns its place and the structure is logical.

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 and annotations covering the safety profile, the description covers the essential usage nuance (the 4xx race condition), the read-only nature, and the required user-facing formatting. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the wait_seconds semantics and adds the expected-4xx caveat, but the schema already documents the exact same 'pass 30 on first check, omit or 0 for later polls' behavior. No additional meaning is added for fax_id or user_id.

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 'Get details for a specific fax record,' a clear verb+resource action that identifies this as a single-record getter. It doesn't explicitly distinguish it from siblings like get-outbox-fax or get-fax-report, but the resource is specific enough that an agent can tell what it does.

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 concrete workflow guidance: after send-fax-uploaded, pass wait_seconds=30 on the first check, then omit or use 0 for later polls. It also warns that an immediate 4xx is expected without the wait. It stops short of naming alternatives or exclusions, so it isn't a full when/when-not guide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explicitly stating 'Side effects: none (read-only)' and disclosing that the return is a base64 PDF in structured output, which is behavioral context beyond the annotations. 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 sentences with zero waste. The core action and format are front-loaded, and the side-effect note is concise. 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?

Given the tool's simplicity, the annotations cover safety, the schema covers parameters, and the output schema exists, the description is nearly complete. The only minor gap is not explaining when to use this over get-fax or get-fax-thumbnail, but the output schema and annotations fill most contextual needs.

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. The description does not add extra meaning about fax_id or user_id beyond what the schema provides, but it does not need to; the baseline of 3 applies because the schema 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 ('Retrieve') and resource ('fax confirmation report (PDF)'), clearly distinguishing it from siblings like get-fax, get-fax-thumbnail, and list-faxes. The parenthetical format note adds precision without ambiguity.

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

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

The description implies usage context (retrieving a confirmation report for a fax) but does not explicitly state when to prefer this over get-fax or get-fax-thumbnail, nor does it mention any exclusions. The read-only note and PDF format hint at the use case, but no explicit alternatives or conditions are given.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces this with 'Side effects: none (read-only)' while adding the concrete return type (base64 image bytes). It does not contradict any annotation, and the extra output detail goes beyond what the annotations alone 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 short sentences with no redundant filler; the core purpose is stated first and the side-effect/output note adds useful information. 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 read-only retrieval with a strong annotation set and an output schema, the description covers the action, resource, side-effect profile, and return format. Nothing essential for an agent to select and call this 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 both fax_id and user_id are already documented in the schema. The description adds no parameter-specific detail, which is acceptable when the schema 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 uses the specific verb 'Retrieve' and names a concrete resource, 'fax thumbnail image', which is distinct from sibling tools like get-fax or get-file. An agent can immediately understand the tool's scope without opening the schema.

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

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

The description implies the tool is for fetching a preview image but gives no explicit when-to-use guidance or alternatives. The intended use is inferable from the resource name, but no exclusions or sibling comparisons are provided.

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

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

The description explicitly states 'Side effects: none (read-only)' and 'returns base64 file bytes in structured output', adding useful behavioral context beyond the annotations. It is consistent with the readOnlyHint, idempotentHint, and destructiveHint annotations, with 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 two short sentences with the primary action front-loaded and the side-effect/output note in a clearly separated second sentence. There is no filler or redundant 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?

Given the rich input schema, output schema, and safety annotations, the description is sufficient for an agent to invoke the tool correctly. It does not discuss alternatives like thumbnails or pages, but those are not required to make the call.

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

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

Schema description coverage is 100%, with fax_id, format, and user_id all documented in the input schema. The description adds no parameter-specific meaning beyond what the schema already provides, 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 uses the specific verb 'Download' and identifies the resource as 'a sent or received fax file', which clearly states what the tool does. It does not explicitly name sibling tools like get-fax-thumbnail or get-file-page to differentiate them, but the full-file download meaning 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 provides no explicit guidance on when to use this tool versus alternatives such as get-fax-thumbnail or get-file-page. An agent must infer the appropriate use case from the tool name and sibling names, which is not enough guidance for a tool with several file-related siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description restates 'Side effects: none (read-only)' and adds the return format ('base64 TIFF page in structured output'), which adds some value. However, most behavioral safety context is already in the annotations, and the return format is likely covered by the existing 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?

The description is short and front-loaded with the core purpose. The side-effects sentence is slightly redundant with the annotations, but it does not hurt. Overall it is efficient and easy to consume.

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 strong annotations, complete input schema, and presence of an output schema, the description is sufficient for a simple read-only tool. It could improve by explicitly naming sibling tools for full-file or thumbnail downloads, but it is not critically incomplete.

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 all three parameters are already documented. The description does not add parameter-specific meaning beyond what the schema provides, such as clarifying fax_id or user_id semantics or page_num bounds.

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 specific resource ('single page from a fax file'), and the format ('TIFF'). It clearly distinguishes this tool from siblings like get-file (whole file) and get-fax-thumbnail (thumbnail) by focusing on a single page.

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 a single page is needed, but it does not explicitly contrast with alternatives such as get-file or get-fax-thumbnail, nor does it state when not to use this tool. The usage context is clear but relies on inference rather than explicit guidance.

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

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

The only behavioral statement, 'Side effects: none (read-only)', merely restates the readOnlyHint annotation and does not add context such as error behavior, authorization requirements, or rate limits. The description is not contradictory, but it contributes no behavioral information beyond what the annotations already encode.

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 purpose is front-loaded in the first sentence and the side-effect note is a separate short line. There is no filler, making the description appropriately sized for a one-parameter 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 low-complexity lookup, the description, full parameter schema, output schema, and annotations together give an agent enough to call the tool correctly. The only missing piece is guidance on when to choose this tool over sibling member/user tools.

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

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

The single parameter member_user_id is already described in the input schema with 100% coverage, so the description does not need to add much. The mention of 'corporate member' hints at the expected resource type but does not add syntax or constraints 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 names a specific resource and outcome: it retrieves a corporate member's role and faxing quota. This is clearer than the generic title, but it does not explicitly differentiate this tool from siblings like get-user or list-members.

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 usage context is provided: the description does not say when to prefer this tool over get-user or list-members, nor does it mention prerequisites such as needing a corporate member ID. With over thirty sibling tools, the agent must infer routing from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'Side effects: none (read-only)' which reinforces but doesn't expand beyond annotations. It doesn't add context about response format or pagination, but output schema exists. 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?

Two sentences with zero waste. The core purpose is stated first, and the read-only note is separate, contributing to clarity.

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 low complexity (2 params, simple read), the description is mostly sufficient. The output schema exists, so return values are documented elsewhere. Minor gap: no mention that 'user_id' can be used to access another user's numbers, but the schema covers 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?

Schema description coverage is 100%, so parameters are well documented in the schema. The description adds no extra semantics beyond what the schema provides. 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 'Get information about a specific fax number', which is clear as a verb+resource. The name 'get-number' is accurately reflected. It doesn't explicitly distinguish from sibling tools like 'list-numbers' or 'get-fax', but the specificity of 'fax number' helps.

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 querying information about a fax number, but does not explicitly state when to use this instead of 'list-numbers' (for multiple numbers) or 'get-fax' (for fax transmissions). The 'side effects' line is about behavior, not usage guidance.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior, but the description adds valuable non-obvious context: the record visibility timing and the expected 4xx without wait_seconds. This goes beyond schema and annotations, helping the agent interpret errors correctly. The explicit 'Side effects: none (read-only)' reinforces the read-only 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 compact, front-loaded with the purpose, then gives parameter workflow, then side effects. However, it partially repeats the schema's wait_seconds explanation, which introduces slight redundancy. Overall, every sentence earns its place, but the duplication with the schema prevents a perfect score.

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 an output schema, the description does not need to explain return values. It covers purpose, workflow, expected errors, and side effects. With only one required parameter and full schema coverage, the description is complete enough for correct invocation and interpretation.

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 repeats the wait_seconds default and usage pattern already present in the schema, adding no new semantic information. It does not introduce any parameter meaning beyond the schema, so a baseline score 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?

Description states a specific verb ('Get details') and resource ('fax scheduled for sending (outbox)'), which clearly indicates the tool's scope. While it doesn't explicitly name a sibling, the 'outbox' qualifier distinguishes it from similar tools like get-fax. It is clear and unambiguous, though it could have explicitly contrasted with related 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?

Provides concrete workflow guidance: after send-fax-uploaded, pass wait_seconds=30 on the first check, omit for later polls, and treats immediate 4xx as expected. This is strong when-to-use guidance, but it does not mention alternatives or explicitly state when not to use this tool. The instructions are actionable and sufficient for the intended flow.

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

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

Annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false. The description only repeats the read-only aspect ('Side effects: none (read-only)') without adding any new behavioral context such as authentication requirements, rate limits, or error behavior. With annotations present, the description adds no value beyond a redundant statement, so the score is low.

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: one purpose sentence plus a side-effect note. It is front-loaded with the core purpose, contains no fluff, and every word earns its place. The structure is optimal for a simple read-only 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?

Given the tool's simplicity (one optional parameter, no required fields), the presence of an output schema, and annotations covering safety, the description is largely complete. It states the purpose and side effects. Minor gaps include not mentioning potential error conditions or the behavior when the user_id is invalid, but these are not critical for a read-only informational tool with schema-defined outputs.

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 has full schema description coverage (100%) with a clear explanation and default. The tool description does not mention parameters at all, but since the schema already documents them completely, the description doesn't need to compensate. The baseline of 3 applies because the 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 action ('Get') and resource ('plan'), and specifies the returned information (plan type, admin/owner flags). It is clear and unambiguous, though it doesn't explicitly distinguish from sibling tools like get-user or get-token-info. The purpose is evident enough for an agent to select it when plan information is needed.

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. There are many get-* sibling tools, and no mention of conditions under which this tool is preferred (e.g., when needing plan-specific data vs. general user details). No exclusions or alternative recommendations are given, leaving the agent to infer context from the name and parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds a redundant 'Side effects: none' statement, which is consistent but provides no new behavioral detail beyond the annotations. It does not contradict any 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 with no filler. It front-loads the core purpose and then states the side-effect-free nature. Every sentence earns its place.

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

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

For a zero-parameter, read-only token-info tool with an output schema, the description covers everything needed: what it does, its safety profile, and the fact that it returns metadata. No further detail 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?

The tool has zero parameters, so there is nothing to explain. The schema is empty and fully documented. Baseline of 4 is appropriate given no parameters exist.

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 retrieves metadata about the current access token, listing specific attributes (type, scopes, expiration). It uses a specific verb ('get') and resource ('token information'), and no sibling tool serves this purpose, so it is unambiguous.

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

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

The context of use is clear (retrieve token metadata), and the description implicitly signals this is for inspection rather than modification. However, it does not explicitly mention alternatives or when not to use it, so it lacks explicit exclusions.

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

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

The description states 'Side effects: none (read-only),' which directly duplicates the readOnlyHint and destructiveHint annotations. It adds no new behavioral context like authentication requirements, rate limits, or what the response contains. Since annotations already declare the safety profile, the description contributes no incremental 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 two sentences, concise and front-loaded with the primary purpose. However, the second sentence 'Side effects: none (read-only)' is redundant with the annotations and could be removed without loss. It is still appropriately sized for the tool's simplicity.

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 operation with one optional parameter, an output schema, and annotations covering safety, the description is adequate. It lacks usage guidance (scored separately) and does not describe return values, but the output schema likely covers that. The description does not miss any critical information needed to invoke the tool.

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

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

Schema coverage is 100% with the user_id parameter fully described as 'Fax.Plus user ID. Default: self.' The description does not elaborate on this parameter beyond the schema. With full schema coverage, the description adds no additional meaning, 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 'Get account information for a user,' identifying a specific verb and resource. It differentiates from sibling tools like get-member-details and get-token-info by focusing on account-level info, though it doesn't explicitly name alternatives. The default 'self' is implied by the parameter schema but not stated in the description.

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 such as get-member-details or get-token-info. There is no mention of prerequisites, exclusions, or scenarios that would make this tool the appropriate choice. The description leaves usage decisions entirely to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description's 'Side effects: none (read-only)' merely restates those annotations and adds no new behavioral context such as result-scope semantics, sharing behavior, or pagination implications. No contradiction exists, but no value is added beyond the structured hints.

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

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

The description is short and front-loaded: the first sentence gives the purpose and capabilities, and the second adds a safety note. It is economical, though the second sentence is somewhat redundant with the annotations. Overall it is well-structured and free of 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 simple read-only list tool with an output schema, fully described parameters, and robust annotations, the description is sufficient for an agent to invoke it correctly. It could be more explicit about result scope or the distinction between shared and personal groups, but those details already exist in the schema, so the description is not critically incomplete.

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 each of the five parameters already explained in the input schema. The description's mention of 'optional pagination and filters' is generic and does not add meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the semantic 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 clear verb and resource: 'List contact groups' and adds the domain clarification '(Fax.Plus tags)'. It also mentions optional pagination and filters, which goes beyond a bare tautology. It does not explicitly differentiate from sibling tools like list-contacts, but the resource is specific enough that the purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as list-contacts, create-contact-group, or update-contact-group. The description only lists capabilities ('optional pagination and filters') and notes read-only side effects, but does not explain when an agent should choose this tool or what exclusions apply.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond that by disclosing that response groups are group names even though the API stores IDs, meaning the tool performs resolution internally. The explicit 'Side effects: none' line is redundant with annotations, but the group-resolution detail earns credit.

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 with the core purpose, followed by filtering guidance, workflow context, and output behavior. Every sentence earns its place and there is 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 an 11-parameter read-only list tool with an output schema and strong annotations, the description covers filters, pagination, sorting, shared/personal scope, group resolution, and integration order. Nothing critical is missing for an agent 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?

Schema coverage is 100%, so the baseline is 3, but the description adds practical meaning with examples like name=Jane, clarifies pipeline_id usage in the fax workflow, and explains group-name resolution. These go beyond the schema's individual parameter descriptions without contradicting them.

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 resource (contacts) and the specific capabilities: optional filters, pagination, sorting, and shared/personal filtering. This distinguishes it from sibling list tools like list-numbers or list-contact-groups without needing to inspect 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 instructs agents to use server-side filters rather than fetching everything and filtering client-side, and provides a concrete fax-workflow ordering: call after pipeline_start and list-numbers, before request-file-from-user. It also tells the agent not to ask the user for a contact, which is a strong guardrail against tool misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: results are paginated, and the agent should summarize results in plain language rather than dumping raw API metadata. This 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 short and front-loaded with the core action, followed by pagination and user-handling guidance. Every sentence adds some value, though 'Side effects: none (read-only)' largely repeats what the annotations already state.

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 rich input schema, annotations, and the presence of an output schema, the description is sufficiently complete. It covers pagination and response presentation behavior, which are the main things not already encoded in structured metadata. A short note on when to prefer this over list-outbox-faxes would make it 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?

The input schema has 100% parameter description coverage, so the schema already documents all 15 parameters. The description adds only the high-level 'for a user' framing, which hints at user_id but does not substantially extend the schema's parameter explanations.

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 names the action and resource: 'List fax records for a user' and adds that results are paginated. This is specific enough to identify the tool's purpose, though it does not explicitly distinguish it from the sibling tool list-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 gives no guidance on when to use this tool versus alternatives such as list-outbox-faxes or get-fax. It implies usage by naming what it does, but lacks exclusion criteria, prerequisites, or alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Side effects: none (read-only)' and adds the scoping detail 'in your account.' There is no contradiction, but it provides little behavioral context beyond what the annotations already 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 short and front-loaded with the core purpose. The second sentence about side effects is somewhat redundant given the annotations, but it is not verbose and does not obscure the main instruction.

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 operation with annotations and an output schema, the description is mostly complete. It states what is listed and the account scope. It could be improved by referencing a sibling for single-member details or mentioning pagination behavior, but those are not critical for a simple list call.

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

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

The tool has zero parameters and the schema covers 100% of them, so the description carries no parameter burden. With 0 params, the baseline is 4, and no additional parameter semantics are 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 clear verb and resource: 'List all corporate members in your account.' It specifies scope and distinguishes itself from sibling get-member-details through the plural 'all corporate members' framing. It does not explicitly name the sibling it is not, 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?

The description gives no guidance on when to use this tool versus alternatives such as get-member-details or list-contacts. It implies use when you need all members, but there are no explicit conditions, exclusions, or references to sibling tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, and the description confirms 'Side effects: none (read-only).' It adds useful behavioral context about the fax pipeline and that the agent should not prompt the user, exceeding what the structured fields 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?

Three short sections: purpose, workflow instruction, and side-effect note. It is front-loaded and every sentence adds either semantics or safety/usage guidance.

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 list operation, zero required parameters, full schema coverage, and presence of an output schema, the description plus annotations cover what an agent needs to invoke it correctly, including its role in the fax flow.

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 user_id default and pipeline_id provenance/passing. The description adds only a light contextual mention that pipeline_id is optional and tied to pipeline_start, not enough to move beyond the baseline.

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

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

The description opens with 'List your purchased or assigned phone numbers,' a specific verb, resource, and scope. It clearly distinguishes from sibling tools like get-number (single number) and update-number (mutation).

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 workflow guidance: call after pipeline_start and before request-file-from-user when sending a fax, and instructs the agent not to ask the user to pick a number. This is direct when-to-use and when-not-to-behave instruction.

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

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

The description adds meaningful behavior beyond annotations: it instructs the agent to translate statuses into user-friendly categories and explicitly warns against dumping raw status timelines or internals. It also confirms read-only behavior, consistent with the readOnlyHint and destructiveHint annotations. This is useful operational 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?

The description is short and front-loaded, with the core action and scope stated first. The 'Side effects: none (read-only)' sentence is redundant with the annotations but not harmful. Each other sentence earns its place, particularly the status-translation guidance.

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 operation with an optional, fully documented parameter and an output schema present, the description covers the essential behavior: scope, status handling, and presentation constraints. Nothing critical is missing for an agent 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?

Schema description coverage is 100%: the only parameter, user_id, is fully documented with its meaning and default. The description adds no extra parameter-level semantics, 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 states a specific verb ('List') and resource ('faxes in the outbox') with a clear scope ('waiting to be sent'). This distinguishes it from siblings like list-faxes (all faxes) and get-outbox-fax (single fax). No ambiguity about what the tool does.

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 use for outbox faxes waiting to be sent, but it does not explicitly name alternatives or provide when-to-use/when-not-to-use guidance. The sibling list-faxes exists, but no routing guidance is given.

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

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

Annotations already signal read-only and non-destructive, but the description adds the side effect of 'minting a handle' and confirms it writes no state, which enriches understanding 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 concise sentences, front-loaded with the primary action and output, then a clear usage directive. No waste.

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 tool with a descriptive output schema, it covers the essential workflow context. It could mention what 'subsequent pipeline tools' are explicitly, but it lists enough to guide.

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?

Has zero parameters, so the schema is trivially complete. The description adds the critical semantic that the output is a pipeline_id to be used elsewhere, which is beyond structural schema.

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

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

States a specific verb and resource: starts a pipeline and returns an id. Distinguishes itself by tying to the fax workflow and listing sibling tools it should be used with.

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 explicit when-to-use (calling first when sending a fax) and explains how to use the output (pass id to subsequent pipeline tools, optionally to list-numbers/list-contacts), which routes the agent clearly.

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

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

Beyond the annotations, the description discloses substantial behavior: it mints a short-lived widget token, opens the upload UI, returns one of three chat payloads, never expects chat attachments, never accepts base64/file bytes, and explains how fax_ids are added to conversation context. No contradictory claims against 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 long but dense and well front-loaded with the required call order. Most sentences carry operational value, especially the mode branches and exclusions. There is some redundancy in the repeated warnings about never passing base64/file bytes and never asking for chat attachments, which 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?

Given the tool's complexity, seven parameters, output schema, and destructiveHint annotation, the description is remarkably complete. It covers sequencing, parameter pass-through, mode-specific behavior, side effects, follow-up actions after fax_id is known, and which sibling tools must not be called, leaving no major gaps for an agent invoking 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?

Schema coverage is 100% and already documents each parameter. The description adds genuinely useful semantics beyond the schema: pipeline_id must be passed unchanged, numbers/contacts must be passed through from list results, to/from are prefill-only and should be omitted unless the user named them, and start_file_upload must always be true. This exceeds the baseline, though some information duplicates 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 name and title make the core action clear, and the description strongly implies it requests a fax file from the user via a UI widget or curl recipe. However, there is no single crisp statement like 'asks the user to upload a fax file'; instead the purpose is embedded in orchestration details and mode-specific behavior. It does distinguish itself well from siblings like send-fax-uploaded and upload-file.

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 the required call order: pipeline_start first, then list-numbers and list-contacts, then this tool. It also gives direct exclusions: do not re-list, do not ask for sender/destination, do not call send-fax-uploaded, upload-file, or await-fax-upload. Mode-specific instructions for MCP Apps, unconfirmed, and agentic modes make selection unambiguous.

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

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

The description explicitly states 'Side effects: queues outbound fax for delivery', which explains why the annotations mark destructiveHint=true — a real fax will be transmitted to actual recipients. This adds specificity beyond the bare annotation and there is no contradiction with any annotation flag.

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

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

Two short sentences with no filler: the core mechanism is front-loaded, the critical parameter constraint follows, and the side effect is stated last. This is efficient and well-ordered, though the second sentence could arguably be folded into the schema note.

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 tool with nested objects, the description is thin — it explains the core concept and side effect but gives no guidance on the many optional parameters (options, cover_page, send_time, user_id) or how they interact. However, the output schema exists and schema coverage is 100%, so the schema carries most of the burden, leaving only a moderate gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it clarifies the role of from_fax_id ('reusing an existing fax file reference') and emphasizes that 'to must be an array', but both points are already well-documented in the property descriptions. It does not compensate further for the 11-parameter surface.

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 (Queue) plus resource (outbound fax) plus mechanism (reusing an existing fax file reference via from_fax), which distinguishes it from the sibling send-fax-uploaded that starts from an uploaded file. It does not name the sibling explicitly in the purpose statement, but the mechanism is specific enough for an agent to tell it apart.

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

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

The description gives no guidance on when to use this tool versus alternatives such as send-fax-uploaded or update-fax, and mentions no exclusions or prerequisites. The only usable note is the parameter-level warning that 'to must be an array of destination numbers', which is format guidance, not when-to-use guidance.

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

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

Beyond the annotations, the description reveals the key behavioral nuance that success means only queued/submitted, not delivered, and explicitly states the side effect: 'queues outbound fax for delivery.' It also clarifies that paths may be reused, which reduces unnecessary caller caution. No contradiction with annotations 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 long but every section earns its place: preconditions, exclusions, parameter cautions, success semantics, follow-up status guidance, and user-facing communication rules. The core action is front-loaded, though the operational messaging guidance could arguably be split out without losing invocation 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?

For an 11-parameter tool with nested objects and an output schema, the description is comprehensive: it covers prerequisites, invalid inputs, scheduling, result interpretation, follow-up status checks, and user messaging. The existence of an output schema relieves it from describing return values, and 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 baseline is 3, but the description adds meaning beyond the schema: it ties the files parameter to upstream responses ('files = path from the files POST JSON'), forbids local filesystem paths and file bytes, emphasizes that to must be an array, and indicates send_time is optional. These are useful semantic constraints not fully captured in individual property 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 action and resource: 'Queue a new outbound fax using storage paths.' It clearly differentiates this from upstream file-upload tools and from the MCP Apps UI flow, so an agent knows exactly what this tool does and how it fits with siblings like get-fax and upload-file.

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 says when to call this tool ('after an agentic request-file-from-user curl... or after upload-file') and when not to ('Do not call this after the MCP Apps UI flow'). It also tells the agent which tool to use next for status checks and how to pass wait_seconds on the first check.

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

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

The description discloses the key behavioral consequence up front: 'This overwrites previous group assignments for the selected contacts.' It also adds a separate 'Side effects' line and notes the tool will resolve group IDs to names before calling the API. These details complement the destructiveHint=true annotation without contradicting it.

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—five short sentences—and front-loads the core purpose before adding warnings and side effects. The 'Side effects' line is slightly redundant with the overwrite statement and the destructiveHint, but it is brief and clearly labeled. Overall, 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?

The description covers purpose, overwrite semantics, group-name requirement, and ID resolution, and an output schema exists, so return values need not be explained. A notable gap is the behavior when groups is omitted—since only contact_ids is required, clearing existing assignments is not documented. This leaves some ambiguity for a valid call shape.

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 adds value by warning that group IDs from create-contact-group are not acceptable and that group IDs mistakenly passed will be resolved to names. However, the groups and shared parameters are already well described in the schema, so the extra contribution is modest.

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 specific verb-object: 'Assign contacts to contact groups,' and clarifies these are Fax.Plus tags. It distinguishes itself from create-contact-group by explicitly saying to pass group names, not group IDs from that tool. This is more than enough for an agent to know what operation this performs.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance relative to sibling tools like share-contact-groups or create-contact-group. The need to assign contacts to groups is implied by the first sentence, and the 'pass group names, not IDs' warning is more about parameter format than tool selection. It therefore only implies usage rather than spelling out alternatives.

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

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

Annotations show destructiveHint=true and readOnlyHint=false, signaling mutation, but the description adds a concrete side-effect note: 'shares contact groups to corporate scope.' This gives some context beyond the annotations, though it does not explain the full consequences such as permantence, reversibility, or impact on existing corporate groups.

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 crisp sentences with no filler. The primary action is front-loaded, and the side-effect note earns its place by disclosing the scope change.

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 one required parameter and an output schema, the tool is simple, but the description still lacks direct parameter guidance and alternative differentiation. It is minimally viable but leaves an agent to infer important invocation details.

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%, and the description does not explicitly explain the group_ids parameter. The phrase 'selected personal contact groups (tags)' hints that group_ids refers to tag IDs, but this is indirect and insufficient for an agent to confidently construct correct input without further inference.

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 ('Share'), a specific resource ('selected personal contact groups'), and the target audience ('corporate members in your organization'). The parenthetical '(tags)' clarifies the meaning of contact groups, and the resource differs from sibling tools like share-contacts, making it distinguishable.

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: when you want to share selected personal contact groups with corporate members. However, it does not explicitly name alternatives or provide exclusion criteria, so an agent must infer the appropriate context rather than being told.

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

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

Annotations already declare destructiveHint: true, so the description is not solely responsible for that signal. The added side-effect line 'shares contacts to corporate scope' clarifies the scope but does not explain what makes the operation destructive (e.g., whether personal copies are removed or sharing is irreversible). This is limited added value beyond annotations, meriting a 3.

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

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

The description is only two sentences and front-loads the main action clearly. The second sentence on side effects is somewhat redundant with the first, but it is structured as a separate note and does not add unnecessary length. Slight redundancy prevents a perfect score.

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 marked as destructive, the description should explain the consequences of sharing, such as whether the contacts are moved, copied, or permanently exposed, and whether the action can be undone. It also omits any prerequisites like required permissions or membership. The output schema covers return values, but the operational context is too thin for a destructive 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?

With 0% schema description coverage, the description must compensate for the undocumented 'contact_ids' parameter. It provides some context by calling them 'selected personal contacts', but does not specify expected formats, uniqueness, or validation rules. This is adequate for a simple array-of-strings parameter but not thorough.

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 'Share' with a clear resource 'selected personal contacts' and target 'corporate members in your organization'. This distinctly differentiates it from siblings like share-contact-groups (which shares groups) and create/delete/update contact 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 implies when to use it by mentioning 'personal contacts' and 'corporate members', which hints at individual contact sharing vs. group sharing via share-contact-groups. However, it does not explicitly state when to prefer this tool over alternatives or provide any 'when not to use' guidance.

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

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

The description discloses the load-merge-write mechanism and the fact that the API is really a full replace, adding context not available from annotations alone. It also confirms the destructive side effect, matching the destructiveHint annotation without contradicting it.

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: purpose, field-omission guidance, the merge mechanism, the group-name constraint, and the side effect. It is concise while covering essential behavioral and usage details.

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 that the tool has an output schema and detailed parameter schemas, the description completes the picture by explaining the merge semantics and group-name constraint. It is sufficiently complete for an agent to select and call the 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 schema descriptions already carry the full parameter semantics, including the 'fields to change only' behavior and group name requirement. The prose description mostly echoes this information, so 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 states a specific verb and resource ('partially update an existing contact') and clarifies the partial-update scope, which distinguishes it from create/delete operations. The wording leaves no ambiguity about what the tool does.

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 actionable guidance on how to invoke partial updates and how to handle groups. It does not explicitly contrast with related tools such as set-contact-groups or create-contact, which keeps it just below the highest bar.

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

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

Annotations already declare destructiveHint: true and readOnlyHint: false. The description's 'Side effects: modifies contact group.' merely restates this without adding new behavioral context (e.g., whether it's a partial update, permission requirements, or effects on existing data). It adds no value 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?

The description is extremely concise, using two short lines with no filler. The core action is front-loaded, and the side-effect note is minimal. 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 simple update tool with an output schema present, the description is mostly sufficient. However, it does not clarify that the update is partial (only name/notes fields) or that unprovided fields remain unchanged. Given the simplicity and that the schema already conveys the fields, a 3 reflects the slight gap in behavioral nuance.

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 clear definitions for both group_id and payload. The description adds no parameter-specific details. Per calibration, baseline is 3 when schema fully documents parameters, and the description does not enhance or compensate further.

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 'Update' and the resource 'contact group', with a parenthetical 'Fax.Plus tag' to disambiguate the term. It distinguishes from create/delete/list siblings by virtue of the action, though it doesn't explicitly name them. The purpose is unambiguous and not a tautology.

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 create-contact-group or delete-contact-group. There is no mention of prerequisites, typical scenarios, or exclusions. The description merely states the action without any usage context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds 'Side effects: modifies fax record metadata,' which is mildly useful but does not disclose permissions, auth needs, or scope. 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?

Two short sentences, front-loaded with the core purpose and a clear side-effects note. No filler, though the wording could be tightened to avoid the 'and/or' ambiguity.

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?

Despite complete schema coverage and an output schema, the description omits critical usage context: the payload fields are mandatory, and the tool should be distinguished from bulk-update-faxes and update-outbox-fax. An agent cannot reliably decide between siblings from this description alone.

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%, giving a baseline of 3, but the description's 'read state and/or comment' conflicts with the schema, which requires both comment and is_read in the payload. This actively misleads agents about the required payload shape.

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 ('Update a fax record's read state and/or comment') and identifies the fields being updated. It does not explicitly differentiate from update-outbox-fax or bulk-update-faxes, but the resource and scope are clear enough.

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

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

No guidance on when to use this tool versus its siblings such as bulk-update-faxes or update-outbox-fax. The description implies single-fax updates but never states exclusions, alternatives, or prerequisites.

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

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

Annotations already mark destructiveHint=true, and the description adds precise behavioral detail: 'adds a member to the number's assigned_to list.' This goes beyond the annotation by specifying exactly what mutation occurs. It does not contradict any annotation. It does not clarify idempotency (e.g., what happens if the member is already assigned), which is a minor gap given idempotentHint=false.

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

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

Two sentences plus a side-effect note, front-loaded with the core action. Every sentence adds value: the first states the primary purpose, the second explains parameter roles, and the side-effect note discloses the mutation. 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?

The tool has 3 parameters with a nested object and an output schema. The description covers the main purpose, parameter semantics, and the side effect. It does not detail output or error cases, but the output schema exists, and the description sufficiently equips an agent to call the tool correctly. Missing idempotency details are minor.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description adds extra meaning by explaining the default for user_id ('usually self') and the relationship between user_id (owner context) and payload.assigned_to (target member). This is useful semantic context beyond what the schema provides.

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

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

The description uses the specific verb 'Assign' with a clear resource ('a fax number') and target ('to a corporate member'), and explicitly states the mechanism ('adds them to assigned_to'). It stands apart from the sibling list, which contains no other number-assignment mutation, so there is no ambiguity about what the tool does.

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

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

The description implies when to use it by stating the action and clarifying the roles of user_id and payload.assigned_to. It doesn't name alternatives, but none exist among siblings for this exact purpose. It also discloses the side effect, which helps the agent decide if this is the right tool for a destructive operation. Lacking an explicit 'when not to use' or alternative routing, but context is clear.

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

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

The description adds a side-effect disclosure ('modifies outbox record metadata') beyond the annotations. This helps clarify that the update mutates state without deleting the fax, which complements the destructiveHint=true annotation. It does not contradict any annotation.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the side-effect note earns its place as important behavioral context. Nothing unnecessary is included.

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 tool with a complete input schema, annotations, and an output schema present, the description is largely sufficient. It notes the key side effect and constraints, though it leaves alternative-tool routing unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The phrase 'comment only' reinforces the payload structure but adds little meaning beyond what the schema's payload.comment property already conveys.

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 ('Update'), names the resource ('queued outbox fax'), and narrows the operation to '(comment only)'. This clearly differentiates it from related tools like update-fax and 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 scope is implied by 'queued outbox fax' and 'comment only', which tells the agent when the tool applies, but it never names alternatives or states when not to use them. No explicit routing to update-fax, bulk-update-outbox-faxes, or delete-outbox-fax is provided.

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

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

Annotations already signal mutation (`readOnlyHint=false`, `destructiveHint=true`), and the description adds meaningful behavioral context on top: it stores the file for fax delivery, requires automation-only invocation, and forbids passing file bytes through the model in chat flows. This goes well beyond what the annotations alone 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?

Four short sentences, front-loaded with the core use case and followed by a hard exclusion. Every sentence earns its place: usage, when-not, the model-bypass constraint, and the side effect. No filler or repetition of schema 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?

The description is complete for the tool's complexity: it explains the required follow-up call (`send-fax-uploaded`), the chat-flow alternative, the side-effect behavior, and the operational constraint about model exposure. An output schema exists, so the absence of return-format detail is acceptable.

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 explains all six parameters. The description reinforces that `file_content` is base64 and that the flow returns a path, but it does not add substantial per-parameter meaning beyond schema. Baseline 3 is appropriate.

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

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

The description names a concrete action—uploading document bytes as base64 for non-chat integrations—and immediately ties it to the sibling `send-fax-uploaded` via the returned path. It clearly separates this tool from the chat-oriented flow by naming `pipeline_start`, `list-numbers`, `list-contacts`, and `request-file-from-user`, so an agent can distinguish it from siblings 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?

Usage guidance is explicit and forceful: use this only for automation/non-chat integrations, and never in chat. The description names the exact alternative sequence for chat and even states the reason—file bytes must not pass through the model—so the agent knows both when to use it and when to avoid it.

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