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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real context beyond them: the creation side effect and the fact that `shared` discloses the contact to corporate members. That visibility consequence is exactly the kind of detail annotations cannot express.

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

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

Three short, front-loaded sentences covering purpose, input constraints, and side effects with no filler. The 'Side effects:' fragment is slightly clipped but still readable.

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

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

With annotations, a full schema, and an output schema present, the description covers everything needed to call the tool correctly. Only minor gaps remain, such as duplicate-handling behavior or permission/plan prerequisites.

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 nine parameters are already documented, including the group-names-not-IDs constraint. The description repeats the E.164 requirement and the groups rule, adding emphasis but no new semantic information, so baseline 3 applies.

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

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

States a specific verb (Create) and resource (contact in Fax.Plus address book), which clearly separates it from list-contacts, update-contact, and delete-contact. It stops short of explicitly naming the sibling boundary, but the operation 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 description gives the required fields and a format constraint (groups must be names, not IDs), which implies when the tool applies. It never states when to prefer it over update-contact, create-contact-group, or share-contacts, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds real value beyond that: it discloses the write side effect explicitly and warns that the optional 'shared' flag exposes the group to corporate members — a consequence not encoded in any structured field.

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

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

Three short, front-loaded statements: purpose, integration rule, side effects. No filler, and the most decision-relevant information (the name-not-id rule) appears early.

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?

An output schema exists, so return values need no explanation. Combined with annotations covering the safety profile and the description covering side effects and the name-vs-id rule, an agent has enough to invoke it correctly; only parameter validation details are missing.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains the effect of 'shared' (disclosure to corporate members), which is the least obvious parameter, but leaves 'name' and 'notes' unelaborated (e.g., uniqueness constraints, length limits, whether notes are visible to other members). Partial compensation only.

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 ('Create a contact group') and clarifies the domain concept by equating it with a 'Fax.Plus tag' used to organize contacts, which distinguishes it from sibling tools like update-contact-group or set-contact-groups.

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

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

Gives a concrete downstream usage rule — when assigning contacts via set-contact-groups / create-contact / update-contact, pass the group's name rather than its id — which names the exact sibling tools involved. It stops short of saying when to create a group versus when to reuse an existing one via list-contact-groups, but the guidance is clear and actionable.

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

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

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the trailing 'Side effects: none (read-only)' largely restates structured data. The real added value is the eventual-consistency warning that a 404 right after an upload means visibility lag rather than a failed send — a behavioral trait the annotations cannot express.

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 purpose and followed by the highest-value caveat. The 'Side effects: none (read-only)' line is redundant against the annotations and is the only wasted text.

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

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

An output schema exists, so return values need no explanation, and both parameters are fully documented in the schema. For a simple read-only single-record fetch, the only material omission is a note on when to choose this versus the outbox/report variants.

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

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

Schema description coverage is 100%, with both fax_id and user_id documented including the 'Default: self' behavior, so the baseline of 3 applies. The description adds nothing about parameter format, ID source, or the implication of supplying user_id on behalf of another user.

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

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

States a specific verb and resource: 'Get details for a specific fax record.' An agent can tell this is a single-record fetch rather than a list operation. It does not, however, distinguish itself from close siblings like get-outbox-fax or get-fax-report, which an agent must resolve from names alone.

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

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

The 404-after-send caveat gives genuine timing guidance tied to send-fax-uploaded, which is useful. But there is no statement of when to prefer this over get-outbox-fax, get-fax-report, or list-faxes, so sibling selection is only implied by the resource name.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower; the description still adds real value by disclosing that the URL is short-lived and that the result is a URL plus expiration_seconds rather than file bytes. 'Side effects: none (read-only)' is redundant with the annotations, which keeps this from a 5.

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

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

Front-loaded with the core fact (URL for the PDF), followed by compact handling instructions; no rambling. The explicit 'Side effects: none (read-only)' line restates annotations and is the only sentence that doesn't fully earn its place.

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

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

For a two-parameter read tool with full schema coverage, an output schema, and annotations covering safety, the description supplies exactly the missing context: the return type (URL, not bytes), its short lifetime, and the required handling. Nothing needed to call or use it correctly is absent.

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

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

Schema description coverage is 100%, so fax_id and user_id (with its 'default: self') are already documented. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return a short-lived URL for the fax confirmation report (PDF)') and immediately clarifies the return artifact, which separates it from siblings like get-fax or get-file that return metadata or bytes. An agent can tell what this tool yields without opening the schema.

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

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

Explicitly tells the agent to save the URL to disk immediately, avoid pasting report bytes into the conversation, and open the PDF only when the user wants to view it — clear operational usage. It lacks an explicit comparison to alternatives (e.g., get-fax for metadata vs. this tool for the confirmation report), so it falls short of a 5.

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

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?

Annotations already declare read-only, idempotent and non-destructive, so the safety profile is covered; the description goes further by disclosing that the URL is short-lived (expires), that the response is url plus expiration_seconds rather than bytes, and that it works for both sent and received faxes. These are behavioral traits an agent cannot get from the annotations or schema and materially change how it should handle the result.

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

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

Front-loads what is returned, then gives the imperative handling steps, then the side-effect caveat. Every sentence is actionable and there is 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?

An output schema exists so return values needn't be spelled out, yet the description still flags the return shape (url, expiration_seconds) and the short-lived nature that drives the save-immediately instruction. Combined with the 100%-covered schema and read-only annotations, an agent has everything needed to call and handle this 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%, so all three parameters (fax_id, format, user_id) are already documented in the schema, and the description adds no format syntax or defaulting nuance beyond it. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb and resource: 'Return a short-lived URL for a sent or received fax file (pdf or tiff)'. It also implicitly separates itself from metadata tools like get-fax by clarifying it returns a URL, not file bytes. However, no sibling tool (get-file-page, get-fax-thumbnail, get-fax) is named as the alternative, so differentiation requires inference.

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 concrete operating instructions: save the URL to disk immediately, don't paste file bytes into conversation, open the saved file when the user wants to view it. What's missing is when to choose this over get-file-page (paged content) or get-fax-thumbnail, which are the most plausible confusions among 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still earns credit for disclosing the short-lived URL and expiration_seconds, and for stating that the tool returns a URL rather than file bytes—context that drives how the agent must handle the result.

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?

Five short sentences, purpose front-loaded, with no filler. The handling instructions are dense with value, though the phrasing is slightly prescriptive/repetitive around saving versus viewing.

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

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

For a read-only single-page fetch with a full schema and an output schema, everything the agent needs is present: what comes back, that it expires, and what to do with it. Nothing essential is left to inference.

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 fax_id, user_id, and page_num are all documented in the schema, including the 1-based indexing and the 'default: self' for user_id. The description adds no parameter-level detail beyond 'one fax page', so the baseline 3 applies.

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

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

The description names a specific verb and resource—'Return a short-lived URL for one fax page as a one-page PDF'—and pins down both the returned artifact (URL, not bytes) and the format (one-page PDF). That is enough to separate it from get-file, get-fax, and get-fax-thumbnail without opening any schema.

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

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

It gives concrete operational direction: save the URL to disk immediately, don't paste page bytes into the conversation, and open the saved PDF when the user wants to view it. What's missing is an explicit routing rule—when to reach for this instead of get-file or get-fax-thumbnail—so the agent still has to infer the alternative.

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, idempotentHint, non-destructive and closed-world behavior, and the description's 'Side effects: none (read-only)' merely restates them without adding context. Nothing is said about error behavior for unknown numbers, permissions, or what fields the lookup returns.

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

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

Two short, front-loaded lines with no filler. The second line is redundant with the annotations, which keeps it from a 5.

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

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

Output schema exists, parameters are fully documented, and annotations cover safety, so the minimum an agent needs is present. However, for a lookup tool among many siblings (list-numbers, get-user, get-fax), the description gives no hint of what is returned or when this lookup is the right entry point.

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

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

Schema description coverage is 100% — both 'number' (E.164 format with example) and 'user_id' (default: self) are documented in the schema. The description adds no parameter detail, so baseline 3 applies.

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

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

States a specific verb ('Get information') and resource ('a specific fax number'), which distinguishes it from list-numbers (listing) and update-number (mutation). It does not explicitly name those siblings, but the singular-resource framing makes the intent 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?

Usage is only implied by the resource name; there is no explicit when-to-use or when-to-prefer-list-numbers/update-number guidance. An agent can infer the read-lookup scenario but must do the routing itself.

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=false, so 'side effects: none (read-only)' earns no credit and is redundant. The real addition is the eventual-consistency warning that a 404 right after send-fax-uploaded may mean the record is not yet visible rather than a failed send — behavior an agent could not infer from 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?

Front-loaded with the core purpose in one clause, followed by the timing caveat. The final 'Side effects: none (read-only)' sentence is wasted space given annotations already say this.

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?

An output schema exists and parameters are fully described, so the description only needs to orient the caller — which it does, including the one non-obvious failure mode. Only the explicit relation to get-fax and list-outbox-faxes 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%; both user_id (default self) and outbox_fax_id are already documented in the schema. The description adds no format, ID source, or defaulting detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Get details of a fax scheduled for sending (outbox)'), and the parenthetical '(outbox)' distinguishes it from the sibling get-fax, which returns sent faxes. It never names get-fax explicitly, so the differentiation is implied rather than stated.

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

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

The 404-after-send-fax-uploaded note gives a concrete usage context tied to a named sibling, which is genuinely helpful. However, it does not tell the agent when to prefer this over list-outbox-faxes or update-outbox-fax, and offers no 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?

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?

"Side effects: none (read-only)" merely restates readOnlyHint/destructiveHint from the annotations, adding no new information. "Returns paginated results" is mild behavioral value, but pagination mechanics (limit/offset/cursor) are already in the schema and the output schema covers the response. Nothing about permissions, per-user scoping semantics, or the default-to-self behavior is explained.

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 action, no filler prose. The safety line is the only expendable sentence given the annotations already carry it.

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

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

A 15-parameter filtered-list tool with an output schema and full schema coverage is adequately served by its structured fields, so the description need not enumerate filters. But it omits the one thing structured data cannot convey: the inbox/sent/spam category scoping that separates this from the outbox sibling, leaving a real ambiguity.

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

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

Schema description coverage is 100%, so every one of the 15 parameters (filters, ordering, date bounds, page counts) is already documented at the field level. The description adds nothing beyond that, which is acceptable but not additive; baseline 3 applies.

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

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

States a specific verb and resource ("List fax records for a user") so the operation is unambiguous. However, it never distinguishes this from the sibling list-outbox-faxes, which is the most likely source of misfires. Clear but not sibling-differentiated.

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

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

No guidance on when to use this versus list-outbox-faxes, get-fax, or get-fax-report. The only implied routing signal is the required `category` enum in the schema, which the description never mentions. An agent must infer scope from schema 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, 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 declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered; the description's 'Side effects: none' is partly redundant. What it does add beyond the annotations is the pipeline sequencing constraint and the instruction not to prompt the user for a selection, which is genuine behavioral context.

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

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

Front-loads the purpose, then the workflow constraint, then the side-effect note — a sensible order with little waste. The ordering sentence is somewhat dense with parentheses, but nothing is meaningfully superfluous.

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

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

With an output schema present, return values need no explanation, and the description covers the workflow placement that matters most. The only gap is the lack of any note on result shape or what an empty list means, which is minor given the output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented, including pipeline_id's format and passthrough rule. The description only echoes that pipeline_id is optional and tied to pipeline_start, adding 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?

States a specific verb and resource ('List your purchased or assigned phone numbers'), which cleanly separates it from the singular get-number and the mutating update-number siblings. An agent can identify the operation 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?

Gives explicit ordering guidance ('always call this after pipeline_start ... before request-file-from-user') and an explicit behavioral directive ('Do not ask the user to pick a number'). This is exactly when-to-use guidance tied to a concrete workflow, not just a vague context hint.

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 and openWorldHint=false, so the line 'Side effects: none (read-only)' merely restates structured data. The description adds no behavioral context beyond annotations — nothing about pagination, ordering, or what pending states are included.

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

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

Two short lines, front-loaded with the core purpose and no filler. The remaining line is redundant with annotations but costs almost nothing in length.

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 complete annotation coverage, plus a fully described optional parameter, the description is close to sufficient. Slight gap: no statement of ordering/limits on the returned list, which an agent might need.

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

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

Schema description coverage is 100% and the single user_id parameter ('Default: self') is fully documented in the schema. The description adds no meaning about the parameter, which is acceptable at baseline when the schema does the work.

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

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

States a specific verb and resource ('List faxes in the outbox') plus a qualifying scope ('waiting to be sent'), which clearly separates it from list-faxes (sent faxes) and get-outbox-fax (single item). It never names a sibling explicitly, so distinction relies on the reader inferring from scope.

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 'waiting to be sent' implies when you'd call it (checking pending items), but there is no explicit when-to-use guidance and no mention of alternatives such as get-outbox-fax for a single item or list-faxes for sent history. Usage is only inferable.

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?

It adds real context beyond the annotations: a short-lived fax-scoped token is minted, the UI uploads and sends only on user click, the UI does not post a chat message but injects the fax ids into context, and file bytes must never be read or passed. It still does not say what happens if the user closes the panel, whether the token expires, or whether a partially completed upload can be retried -- meaningful gaps for an operation annotated destructive.

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?

Individual sentences are purposeful and rules are stated imperatively rather than padded, but the whole thing arrives as one undifferentiated block with no opening statement of purpose and no separation between ordering rules, parameter rules, and mode handling. Front-loading the three-mode branching (Apps / unconfirmed / agentic) would make it far easier 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 seven parameters, a required ordering protocol, three client-capability modes, and an output schema, the description covers everything an agent needs to invoke it correctly: what to gather first, what to pass, which modes exist and what to do in each, and where to go next once a fax_id is known.

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 defines to/from/numbers/contacts/pipeline_id/start_file_upload, including the array item shapes; the description largely restates those rules. It does add the sequencing constraint that numbers and contacts must be passed through from the listing calls unchanged and that to/from are prefill-only, which is modest value on top of 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 conveys the specific resource and action -- it collects sender numbers, contacts and pipeline_id so the UI can upload a file and send a fax, and it explicitly separates itself from upload-file and send-fax-uploaded. It never states a single front-loaded purpose sentence, though, and the name (request-file-from-user) is never reconciled with the behavior described (a fax-send orchestration step).

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 an explicit call order (pipeline_start, then list-numbers and list-contacts, then this tool), states what must not be re-done inside the tool, and names the alternatives it forbids in Apps mode (send-fax-uploaded, upload-file) versus the one it requires in agentic mode. When-to-use and when-not-to-use are both spelled out.

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

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

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?

Annotations already flag destructive/openWorld/not-idempotent, but the description adds the crucial async semantic that annotations cannot express: 'Success means queued/submitted only—not delivered,' plus the note that paths can be reused across sends. The 'Side effects' line confirms outbound queueing for delivery, matching rather than contradicting 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?

Front-loaded with the action and its precondition, then constraints, then success semantics — a good ordering with no filler sentences. Minor redundancy: 'to must be an array' and path reuse duplicate what the schema already says, costing a little tightness in an otherwise efficient paragraph.

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, nested-object, non-idempotent mutation tool, the description covers the whole operator journey: where files come from, what not to pass, that only queueing is confirmed, and how to poll status. With a full schema and an output schema present, no additional detail is required 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 coverage is 100%, so the baseline is 3; every parameter including nested cover_page/options is already documented in-schema. The description only adds marginal operator guidance — 'to must be an array' and 'same paths may be reused for multiple sends' — which largely restates the schema's array/E.164 notes.

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 — 'Queue a new outbound fax using storage paths' — and immediately scopes it to a particular input mode (storage paths, not bytes or local paths). It distinguishes itself from the MCP Apps UI flow and points to get-fax/get-outbox-fax for status, so an agent can separate it from resend-fax and the widget path without opening a schema.

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

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

Gives explicit preconditions ('after an agentic request-file-from-user curl ... or after upload-file'), an explicit exclusion ('Do not call this after the MCP Apps UI flow — the widget already sent'), and a negative constraint ('Do not pass local filesystem paths or file bytes'). The follow-up path is also named: check status with get-fax or get-outbox-fax using the returned id.

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?

Goes well beyond the annotations: discloses that assignments are overwritten (consistent with destructiveHint=true), that a mistyped group ID is silently resolved to a name, and that `shared` discloses associations to corporate members. That is real behavioral context an agent could not infer from the flags alone.

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

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

Three tight sentences plus a labeled side-effects line; the critical constraint (names, not IDs) and the overwrite warning are both front-loaded. No filler.

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

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

For a destructive, non-idempotent mutation with an output schema, the description covers the mutation semantics, the overwrite risk, the sharing implication, and the ID pitfall. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value beyond the schema by giving a concrete group-name example, reinforcing the name-vs-ID distinction, and clarifying the shared/personal scope. The ID-resolution fallback is behavior the schema does not express.

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 ('Assign contacts to contact groups') and immediately names the domain concept (Fax.Plus tags), distinguishing it from create-contact-group by warning that group names, not IDs, are required. An agent can tell exactly what this tool does 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?

Gives clear operative guidance: pass group names (e.g. Vendors), not IDs, and warns that prior assignments are overwritten. It doesn't explicitly contrast with sibling mutators like update-contact or share-contacts, so the when-not-to-use side is weaker.

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 'Side effects: shares contact groups to corporate scope' line adds real context that annotations cannot convey — the operation widens visibility organization-wide rather than just mutating a record. However, annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description says nothing about whether sharing can be undone, what permissions are required, or what happens to already-shared 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?

Two short lines, front-loaded with the action and scope, plus the clarifying '(tags)' gloss. The side-effects line earns its place; nothing is padded, though the phrasing is slightly terse for the risk involved.

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?

An output schema exists, so return values need no explanation, and the tool takes a single required parameter. The remaining gap is modest: no note on reversibility of sharing or restrictions on which groups are eligible, which matters for an openWorld, non-idempotent visibility change.

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

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

Only one parameter (group_ids) with 0% schema description coverage, so the description must carry the load. It helps by qualifying the IDs as belonging to *personal* contact groups (the schema merely says array of strings), but it never states whether multiple IDs are allowed per call, the ID format, or what happens with corporate/nonexistent IDs.

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

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

Specific verb + resource + direction: 'Share selected personal contact groups (tags) with corporate members in your organization,' which cleanly separates it from the sibling share-contacts (contacts, not groups) and from list-contact-groups/create-contact-group. It stops short of naming the nearest alternative explicitly, so it is clear but not fully differentiated in-text.

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

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

Usage is implied by 'personal contact groups ... with corporate members' — the agent can infer this is the group-level variant of sharing — but there is no explicit when-to-use/when-not statement and no mention of prerequisites (e.g. groups must be personal, caller must be a member/admin). No alternatives are named despite share-contacts being an easy confusion point.

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 this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds useful behavioral context by stating the side effect: contacts are shared to corporate scope. It does not cover permissions, reversibility, or rate limits, but the annotations carry much of the safety profile.

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 wasted text. The primary action is front-loaded and the side effect is clearly separated.

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?

An output schema exists, so return values need not be described, and annotations cover much of the behavioral profile. However, the tool still lacks parameter semantics and sibling differentiation for a sharing operation with a required contact_ids array, leaving notable gaps.

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

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

The only parameter, contact_ids, has zero schema description coverage and the description provides no detail about its format, accepted values, or how contacts are identified. It only says 'selected personal contacts,' which does not fully compensate for the missing parameter documentation.

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

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

The description states a specific verb and resource: 'Share selected personal contacts' with corporate members. It implies the distinction from group-sharing by specifying personal contacts, but it does not explicitly name the sibling share-contact-groups tool.

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

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

The intended context is implied: sharing personal contacts with corporate members. However, there is no explicit guidance on when to use this versus share-contact-groups, nor any prerequisites or 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 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds value beyond them by disclosing the concrete side effects: the member is added to the number's assigned_to list and is notified via email and push — exactly the consequence an agent should know before invoking. It stops short of saying how to undo the assignment or what errors occur if the member is already assigned.

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, front-loaded blocks: the operation and parameter roles first, side effects second. No filler, no restatement of the title, and the most decision-relevant information (notifications) is not buried.

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

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

With an output schema present, return values need no explanation, and annotations carry the safety profile. The description covers purpose, parameter roles, and side effects. Minor remaining gaps are failure modes (member already assigned, invalid number) and whether the assignment is reversible.

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 would be 3. The description earns more by disambiguating the easily confused pair: user_id is the account/owner context (usually self for the admin), while payload.assigned_to is the member to assign TO. That distinction is the main semantic risk in this tool and is called out explicitly.

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

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

States a precise verb+resource: assigning a fax number to a corporate member, and names the underlying mechanic (adds them to assigned_to). This tells an agent it is an assignment operation rather than a generic number edit. It doesn't explicitly contrast with bulk-update-faxes, though the singular/member framing makes the distinction inferable.

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

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

Usage is implied by the operation itself (assign a member to a number), and the note that user_id is 'usually self for the admin' gives practical guidance. However, there is no explicit when-to-use vs. the bulk-update-faxes sibling, nor any precondition such as needing the member to already exist or already own a number.

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 declare non-readonly, non-idempotent, non-destructive. The description adds a real behavioral fact — the file is persisted for fax delivery — which is useful context beyond the annotations. However, it omits size limits, format restrictions, expiration of the stored file, and any permission/auth notes, leaving meaningful gaps for a mutation tool.

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

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

Two short, front-loaded sentences with no filler: the action first, then the sequencing requirement and side effect. Nothing redundant.

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

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

For a pipeline step with full schema coverage and an output schema, the description covers the essential contract: bytes in, path out, then hand the path to send-fax-uploaded. Only auxiliary constraints (max size, supported formats, file lifetime) are missing.

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

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

Schema description coverage is 100%, so every parameter including format, mime_type, user_id and pipeline_id is already documented in the schema. The description adds no parameter-level detail beyond that, which is acceptable at baseline but earns no extra credit.

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

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

States a specific verb+resource ('Upload document bytes as base64') and names the required follow-up tool, which distinguishes it from siblings like get-file or request-file-from-user. It doesn't explicitly contrast with those siblings, but the pipeline-sequencing detail makes its role unambiguous.

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

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

The description does say what to do next ('then call send-fax-uploaded with the returned path'), which is genuine usage guidance. But it never states prerequisites (pipeline_start is only mentioned in the schema) or when not to use this versus other upload/request paths.

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