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

Annotations already signal that this is an idempotent, non-destructive mutation. The description adds useful behavioral context by stating that it applies to completed tasks and clears them from the task list. This goes beyond the annotations without contradicting them.

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

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

A single, front-loaded sentence with no filler. It states the action, target, and effect efficiently; 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 one-parameter, idempotent action with annotations covering mutability and destructiveness, the description is sufficiently complete. It omits return-value details, but with no output schema and this level of simplicity that is not a meaningful 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% and the only parameter is already described as an array of task IDs. The description adds only the 'completed' qualifier, which is a minor semantic refinement. Baseline 3 is appropriate.

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

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

The description names the action (acknowledge/dismiss), the target (completed tasks), and the visible effect (clear them from the task list). This lets an agent distinguish it from read-only sibling tools like list_tasks and get_task_summary.

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 about when to use this tool versus alternatives, and no explicit exclusions or prerequisites. The phrase 'completed tasks' implies a precondition, but the description leaves the selection logic 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 only indicate readOnlyHint=false and destructiveHint=false, which is minimal. The description adds that matching pattern and algorithm enable automatic document assignment, a useful behavioral clue. However, it does not disclose permissions, duplicate behavior, or side effects beyond creation.

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

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

The description is a single, front-loaded sentence. It communicates the core action and optional configuration without redundancy or filler.

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

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

With 4 flat parameters, one required, and an enum described in schema, the description plus schema is mostly sufficient. However, there is no output schema and no description of return value, duplicate handling, or whether match is required when matching_algorithm is nonzero, leaving some gaps for an agent invoking this 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 50% because name and match lack descriptions, while is_insensitive and matching_algorithm have descriptions. The description adds meaning by linking 'matching pattern and algorithm' to the purpose of automatic document assignment, but it does not explain the match parameter's format or how it interacts with the algorithm beyond what the schema already 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 verb ('Create'), a clear resource ('new correspondent'), and the optional matching features. This clearly distinguishes it from sibling tools like update_correspondent, delete_correspondent, and list_correspondents.

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 creating a new correspondent—but does not explicitly contrast it with update_correspondent or edit_correspondents_bulk. It provides no exclusions or alternative routing guidance, so usage context is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is not required to restate mutation safety. It adds useful behavioral context by specifying the mandatory currency prefix format for monetary fields, which is a constraint on accepted values beyond the schema.

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

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

A single, well-structured sentence with no redundant words. The core purpose is front-loaded and the monetary format exception is stated clearly and compactly.

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

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

The description is adequate for a simple create operation with a clear resource type. It lacks context on what custom fields are used for, whether names must be unique, or any side effects beyond creation. However, given the tool's simplicity and the clarity of the sibling set, it covers the most critical information without an 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 0%, so the description must compensate for the lack of parameter documentation. It only partially addresses data_type by listing the enum values (already present in the schema) and adds a note on monetary value formatting, but it does not explain the 'name' parameter or the purpose/usage of 'extra_data'. This is a significant gap given the zero coverage.

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

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

The description states a specific verb (create) and resource (custom field), and lists the allowed data types. It clearly distinguishes from sibling create tools (e.g., create_tag, create_correspondent) by naming the resource type explicitly.

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

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

The description implies when to use (when creating a custom field) but does not explicitly discuss alternatives or when not to use it. It offers no guidance on selecting this over other create operations, though the resource name makes the intended use obvious.

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 convey readOnlyHint=false and destructiveHint=false, and the description is consistent with both. It adds genuine value beyond annotations by clarifying behavioral scope: the note is a separate user-facing annotation that does not touch the document's searchable content field, preventing misuse (e.g., treating the note as body text). It doesn't discuss return values or repeated-append semantics, but for a simple additive operation the safety profile is well covered.

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

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

Two sentences with zero filler. The first states the core action; the second adds scope clarification and alternative routing. Every word earns its place, and the action verb is front-loaded rather than buried.

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

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

For a simple two-param tool with full schema coverage and no enums, nested objects, or output schema, the description covers the action, the boundary between notes and content, and the correct alternative. A small gap remains: it never describes what a successful call returns (no output schema exists), and it doesn't mention the related note-management siblings (list_document_notes, delete_document_note), but neither is essential for making a correct call.

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

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

Schema description coverage is 100% — both id ('The document ID') and note ('The note text to add') are already documented in the input schema. The description maps those roles (document id, note text) but adds no detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb + resource pair ('Append a user-facing note (comment/annotation) to a document') and explicitly distinguishes itself from update_document by stating that notes are separate from the searchable 'content' field. An agent can tell this tool apart from the many document-related siblings 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?

The description gives explicit routing guidance: it states what this tool is for (adding a user-facing note) and when it should NOT be used ('to change body text or other metadata fields'), naming update_document as the alternative. This is exactly the when/when-not/alternatives pattern the rubric rewards.

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 cover read-only and destructive hints, so the description only needed to add context beyond them. It adds that matching pattern and algorithm are used for automatic document classification, but it does not disclose potential side effects on existing documents or validation behavior. No contradiction with annotations exists.

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

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

The description is a single sentence that is front-loaded with the primary action and includes only meaningful detail: the resource type, the optional configuration, and the purpose. There is no repetition of schema fields or annotation information.

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

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

For a low-complexity create operation, the description plus the schema covers the essential call intent: required name, optional matching pattern, and algorithm for classification. It does not explain the exact format of 'match' or any return value, but those are minor given the absence of an output schema and the simplicity of the resource.

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

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

Schema description coverage is only 50%, and the description partially compensates by identifying 'matching pattern' for the match parameter and 'algorithm' for matching_algorithm. However, it adds no semantic detail for name or is_insensitive, and it does not fully bridge the gap left by the undocumented match parameter.

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 ('Create'), resource ('new document type'), and scope ('optional matching pattern and algorithm for automatic document classification'). It clearly distinguishes this from sibling operations like update_document_type, delete_document_type, and list_document_types.

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

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

The description implies the intended use: when a new document type needs to be created. It does not explicitly name alternatives or exclusion criteria, but the create verb and the sibling tool names make the appropriate context clear enough for an 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 state readOnlyHint=false and destructiveHint=false, so the description is not required to repeat that. It adds useful behavioral context beyond annotations: the account is inert until a rule references it, and testing is recommended. This informs the agent of side effects (none immediate) and a recommended verification step. No contradiction with annotations.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the additional context about mail rules and testing is concise and directly useful. 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 tool with 10 parameters and no output schema, the description is quite brief. It explains the tool's role in the mail pipeline but does not describe return values, error conditions, or parameter nuances beyond what the schema offers. Given the complexity, more guidance (e.g., expected response, duplicate handling) would improve completeness, but the existing context is not misleading.

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 60%, so several parameters (name, imap_server, username, owner, is_token, character_set) lack schema-level explanations. The description does not compensate for this gap; it mentions no parameters explicitly. However, the schema does document the key ones (password masking, port defaults, account_type, imap_security), so the description adds little value beyond what the schema already provides. Baseline 3 is appropriate given partial schema coverage.

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

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

The description clearly states the specific verb-resource combination: 'Create an IMAP account for Paperless to fetch mail from.' It distinguishes this from sibling operations like update_mail_account, list_mail_accounts, and test_mail_account by focusing on the creation action and the account's purpose. The mention of related tools further clarifies its role in the mail workflow.

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 clear context: it explains that no mail is fetched until a mail rule is created (create_mail_rule), and advises checking connectivity with test_mail_account first. This implicitly tells the agent when to use this tool (when setting up a new mail source) and gives a prerequisite step. It does not explicitly enumerate alternatives or exclusions, but the guidance is actionable and context-rich.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows it mutates but is not destructive. The description adds no behavioral context beyond 'Create', such as side effects, permissions, or how rules interact with existing mail processing. This falls short of the burden when annotations are minimal.

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

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

The description is a single sentence, front-loaded with the core action and resource, and communicates the essential function without waste. It is appropriately concise for a tool with a rich schema that carries parameter-level detail.

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

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

This tool has 25 parameters, no output schema, and only a two-parameter minimal requirement. A one-line description is not enough for an agent to know how to construct a valid request, what the response looks like, or what important constraints exist. The schema covers some parameters but the description does not fill the gaps for the rest.

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

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

With 52% schema description coverage, the schema already documents many parameters. However, the description's summary ('which folder and mails to consider, which attachments to import, and what to assign') doesn't map to specific parameter names or add meaning beyond what parameter names like folder, filter_from, attachment_type, and assign_* already imply. It fails to compensate for the undocumented parameters.

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

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

The description uses a specific verb ('Create') and resource ('mail rule'), and states what the rule controls (folder, mails, attachments, assignments). It clearly distinguishes from siblings like update_mail_rule or delete_mail_rule by the create verb and the high-level behavior described.

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 update_mail_rule, delete_mail_rule, or process_mail_account. The description does not mention conditions, prerequisites, or alternatives, leaving the agent to infer usage 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 indicate this is a non-read-only, non-destructive operation, and the description adds no behavioral context beyond the basic creation action. It does not mention persistence side effects, required permissions, uniqueness constraints, or any other behavior that would help an agent anticipate consequences.

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

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

One tightly worded sentence with no filler. The action, resource, and primary configuration concepts are front-loaded and every word contributes meaning.

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

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

Given six parameters, low schema coverage, no output schema, and no usage guidance, the description is too sparse for an agent to confidently invoke the tool with correct parameters. It omits the required name field and the optional boolean flags, and says nothing about what a successful creation returns.

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

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

Schema description coverage is only 17%, so the description needed to compensate for undocumented parameters. It gestures at 'filter rules and sort configuration' but does not explain the required name parameter, the filter_rules object shape, or the meaning of sort_reverse, show_in_sidebar, and show_on_dashboard.

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 ('Create') and resource ('saved view'), and adds the distinguishing content ('filter rules and sort configuration'). It is immediately clear what this tool does and how it differs from list/get/update/delete saved-view siblings.

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

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

The verb 'Create a new' implies that this tool is for creating saved views rather than updating or listing them. However, the description does not explicitly state when to prefer it over update_saved_view, list_saved_views, or get_saved_view, nor does it provide any conditions 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?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the burden for behavioral nuance. It adds the non-obvious immutability trait ('Share links can't be edited afterwards') and the delete-and-recreate workflow, which is valuable context not present in the schema. It could also mention permission requirements or that the link exposes the document, but the core mutation behavior is well-covered and nothing contradicts the annotations.

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

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

Three sentences, each with a distinct job: state the action, note optional parameters, and provide the immutability warning plus alternative routing. It is front-loaded with the primary purpose and contains no filler or redundancy.

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

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

For a three-parameter creation tool with full schema coverage, the description covers purpose, optional parameters, the no-edit behavioral constraint, and the correct alternative for multi-document ZIP links. The only gap is that, with no output schema, the agent is not told what the response returns (e.g., the share link URL), but this is a minor omission given the clear tool semantics.

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%: each parameter (document, expiration, file_version) is already documented with types, ISO format, null handling, and the default 'archive'. The description's mention of 'expiration date and file version (archive or original)' restates the schema without adding new semantics, so 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?

Opens with a specific verb and resource ('Create a share link for a document') and explicitly distinguishes itself from the sibling create_share_link_bundle, which is for 'several documents as one ZIP link'. An agent can tell exactly what this tool does and which sibling it is not, even without reading 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?

Directly names the alternative create_share_link_bundle and the condition that selects it (sharing several documents as one ZIP link). It also gives actionable guidance for the no-edit case: to change the expiry, delete and recreate, which tells the agent the correct workflow instead of searching for a nonexistent update tool.

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 asynchronous nature of the operation: the ZIP is built in the background, the bundle starts as 'pending', and becomes usable only after get_share_link_bundle reports 'ready'. It also mentions the slug identifying the link. This adds valuable behavioral context beyond the minimal annotations (readOnlyHint: false, destructiveHint: false).

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the async behavior is explained immediately after. 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?

While the async flow is well explained, the description does not explicitly state what the function returns (e.g., a bundle ID or slug). Since there is no output schema, this is a notable gap. The mention of 'slug' implies it's part of the result but leaves the immediate response structure ambiguous.

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

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

Schema coverage is 100%: each parameter (document_ids, file_version, expiration_days) already has a description. The tool description adds no additional parameter-specific meaning beyond what the schema provides, so 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 action: 'Create ONE public share link for a ZIP of several documents.' This is specific (verb + resource) and distinguishes it from sibling tools like create_share_link (presumably single-document) and the get_share_link_bundle polling 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 description implies the appropriate use case—sharing multiple documents as a single ZIP bundle—and mentions the need to poll get_share_link_bundle. However, it does not explicitly state when NOT to use it or name alternatives like create_share_link for single documents.

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 only state readOnlyHint=false and destructiveHint=false, which are generic. The description does not disclose any behavioral traits beyond the fact that it creates something. It omits side effects, idempotency, whether an existing name is rejected, auth requirements, or response behavior. For a mutation tool with minimal annotations, the description carries the burden and fails to provide meaningful 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 a single, focused sentence of about 16 words. It front-loads the action ('Create a new storage path') and includes all essential elements without filler. Every word contributes to understanding the tool's basic function.

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 5 parameters, 2 required, and no output schema, the description is too thin for an agent to call the tool correctly. It does not mention matching rule semantics, uniqueness constraints, what the response contains, or any validation rules. The schema fills some gaps but the overall definition lacks essential context for reliable 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 60% (path, is_insensitive, matching_algorithm have descriptions; name and match do not). The description adds grouping by calling match-related fields 'optional matching rules,' which signals their optional nature. However, it does not explain what 'match' is or how matching_algorithm values behave, leaving the undocumented params only marginally clarified.

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 ('Create') and resource ('storage path'), and lists the key fields (name, path template, optional matching rules). This clearly distinguishes it from sibling operations like update_storage_path, delete_storage_path, or test_storage_path, leaving no ambiguity about the tool's role.

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 instead of alternatives. It does not mention that this is for creating new storage paths only, nor contrast it with update_storage_path or test_storage_path. An agent gets no context about prerequisites or conditions that would select 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 convey readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds no new behavioral traits: no mention of return values, error handling, duplicate-name behavior, authentication requirements, or side effects beyond 'create a new tag'. It restates the obvious mutation without enriching the behavioral model.

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

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

The description is a single, concise sentence with the primary action front-loaded ('Create a new tag'). It lists the optional features without unnecessary detail, making it efficient to parse. It earns a 4 rather than 5 because it could more explicitly mention the required name field or the hierarchical 'parent' option in the same space.

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

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

For a tool with 6 parameters, no output schema, and only two generic annotations, the description is thin. It fails to mention that 'name' is required, what the tool returns (e.g., the created tag or ID), or any side effects like automatic matching configuration. The schema carries some parameter explanations, but the description does not fill the missing behavioral and output context.

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

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

With 50% schema description coverage, the description adds some meaning: it labels 'match' as a 'matching pattern' and connects 'matching_algorithm' to automatic tagging, which aids understanding beyond the schema. However, it doesn't explain 'name', 'parent', or 'is_insensitive', which the schema partially covers. It adds value but not comprehensive compensation for the undocumented parameters.

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

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

The description states a specific verb and resource: 'Create a new tag'. It also names the key optional fields (color, matching pattern, matching algorithm) and the purpose ('automatic document tagging'), which clearly distinguishes it from read-only and update/delete tag siblings. This is unambiguous and resource-specific.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like update_tag or edit_tags_bulk. The phrase 'for automatic document tagging' hints at the tag's intended role but does not help an agent decide between this and other tag-related 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?

Beyond the simple readOnlyHint/destructiveHint annotations, the description adds meaningful run semantics: actions execute in order when any trigger matches, and it discloses cross-field validation constraints (remote OCR requires consumption-started trigger; apply-AI-suggestions cannot use only consumption-started triggers). This is substantial behavioral context for a write operation.

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

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

Four sentences deliver the core purpose, execution semantics, a concrete example, and critical validation constraints with no filler. The most important information is front-loaded, and 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 complex tool with no output schema, the description plus rich input schema covers creation semantics, trigger/action object shapes, example usage, and hard validation rules. It could be slightly more complete by stating the return shape or explicitly contrasting with the single-trigger/action creation tools, but overall it is strongly sufficient.

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 80%, so the schema already documents most parameters. The description adds value beyond the schema with a concrete example mapping trigger and action types to a real scenario, and by clarifying that triggers/actions use the same full object shapes as the sibling create_workflow_trigger/create_workflow_action tools.

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

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

The description opens with a specific verb and resource: 'Create a complete workflow — the automation Paperless actually runs — with its triggers and actions in one call.' This clearly distinguishes it from sibling tools like create_workflow_trigger and create_workflow_action by emphasizing it creates the full runnable workflow rather than a component.

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

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

It gives clear context for when to use this tool: when you want a complete workflow with triggers and actions in one call. It also references create_workflow_trigger and create_workflow_action as the sources for the full object shape, which helps an agent route correctly, though it does not explicitly state when to prefer those separate tools instead.

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

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

Beyond the annotations, the description reveals a critical side effect: Paperless deletes unassigned actions whenever any workflow is updated. It also clarifies that a standalone action is inert, giving an agent the exact risk model before invoking a non-read-only 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?

Three sentences, with the warning front-loaded before the routing advice. Every sentence earns its place and none repeats schema or annotation content.

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

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

For a 36-parameter, side-effect-prone creation tool with no annotations and no output schema, the description covers behavior, risk, and sibling routing well. It is missing only a note on what the tool returns (e.g., the created action id), which an agent would need without an 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?

The description text itself adds no parameter guidance, and with only 28% schema coverage it does not compensate for the roughly 26 parameters lacking schema descriptions. The strong type-code mapping lives in the schema, not in the tool description, so this dimension falls short despite the rich conditional objects.

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

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

States a specific action ('Create ONE standalone workflow action') and immediately clarifies what it is not: a standalone action does nothing on its own. This differentiates it from create_workflow, so an agent can select it correctly.

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

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

Explicitly names the alternatives and the conditions that select them: use create_workflow with inline actions for automation, and update_workflow/update_workflow_action for modifying an existing action. The 'standalone' framing plus exclusion of the obvious sibling leaves no ambiguity.

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 only say readOnlyHint=false and destructiveHint=false, which is minimal. The description adds critical behavioral context: 'On its own a trigger does nothing, and Paperless deletes triggers that belong to no workflow whenever any workflow is updated.' This warns about a non-obvious destructive side effect (orphaned triggers being deleted) that annotations don't capture. It doesn't fully explain all side effects, but it discloses the most important behavioral trap.

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 sentences with zero waste. The critical warning about orphaned triggers is front-loaded, and the alternative routing is compact. 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 23-parameter tool with 83% schema coverage and no output schema, the description covers the essential context: what the tool does, the critical deletion behavior, and how to route to alternatives. It doesn't explain return values, but with no output schema and a create operation, that's a minor gap. The warning about deletion is the most important contextual information and it's present.

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 83%, so the schema already documents most parameters well. The description doesn't add parameter-level detail beyond what the schema provides, but it does clarify the purpose of the trigger in context. Baseline 3 is appropriate since the schema carries 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 clearly states the tool creates ONE standalone workflow trigger, and immediately distinguishes it from create_workflow (which creates workflows with triggers inline) and update_workflow/update_workflow_trigger (which modify triggers). The verb 'create' plus the specific resource 'standalone workflow trigger' is precise and differentiates it from the many sibling tools.

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

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

The description explicitly says when to use this tool vs alternatives: 'To build an automation, use create_workflow with the triggers inline; to change a trigger inside a workflow, use update_workflow (or update_workflow_trigger with the trigger id from get_workflow).' This is explicit when/when-not guidance with named alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is lighter. It adds valuable context beyond annotations by disclosing the blast radius: the deletion affects ALL documents that use the correspondent and is system-wide. This meaningfully raises transparency even though auth requirements and error behavior are not covered.

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, and the destructive warning is front-loaded. Every part contributes either to warning or clarifying the scope of the operation.

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

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

For a simple two-parameter delete with destructiveHint and a confirm field already specified in the schema, the description covers the critical risk: permanence and cascading impact on documents. It does not describe response or error behavior, but the operation is straightforward and the main hazards are disclosed.

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 documents the confirm parameter well, and the description reinforces the destructive nature that confirm is tied to. The id parameter has no description in the schema and the description does not compensate, though the name makes its referent reasonably clear. With 50% schema coverage, this is adequate but not enriched.

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

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

The description uses a specific verb and resource: permanently delete a correspondent, and clarifies the scope is the entire system. It does not explicitly differentiate from sibling tools like update_correspondent or edit_correspondents_bulk, though the deletion semantics are clear from the name and wording.

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 this tool is for permanently removing a correspondent and warns about the consequences, which gives an implicit sense of when to use it. However, it does not explicitly state when to choose it over alternatives or mention prerequisites such as the confirm flag, which is left to the schema.

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

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

Annotations already declare destructiveHint=true, so the 'DESTRUCTIVE' warning reinforces rather than adds. However, the description adds meaningful context beyond annotations: the operation is permanent and cascades by removing the field from ALL documents that use it. No contradiction with annotations.

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

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

Two sentences with zero waste. The destructive warning and core action are front-loaded, and the second sentence adds the essential cascade consequence. 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 low-complexity tool (2 params, no output schema), the description covers the action, permanence, scope, and the key consequence for documents. Minor gaps: no error behavior for nonexistent fields, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is exactly 50%: the confirm parameter is already described in the schema ('Must be true to confirm this destructive operation'), and the id parameter's meaning is inferable from the tool name and description ('delete a custom field'). The description adds no explicit parameter detail but doesn't need much given the low complexity.

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 ('delete'), a specific resource ('custom field'), and the scope ('from the entire system'). It clearly distinguishes this from sibling tools like update_custom_field, edit_custom_fields_bulk, and other delete_* tools targeting different resources.

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

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

The description conveys clear context: this is for permanent, system-wide removal, so an agent understands when this tool is appropriate. It doesn't explicitly name alternatives or exclusions, but the permanent/global framing implies it should only be used when a field must be removed everywhere.

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, but the description adds critical context about the soft-delete nature, recovery window (~30 days), and the condition under which data is permanently lost. This goes beyond the simple destructive flag and informs the agent of consequences and reversibility.

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 sentences with no filler: the action, the recovery consequence, and the alternative are presented in a logical, front-loaded order. Every sentence adds distinct value.

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

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

For a simple two-parameter destructive operation, the description covers what happens, the recovery window, and the alternative for permanent deletion. With annotations and full schema coverage, nothing essential is missing for an agent to invoke 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?

Schema description coverage is 100%: both 'id' and 'confirm' are fully described in the schema. The description adds no additional parameter-specific meaning (e.g., id format or confirm semantics), so 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 uses a specific verb ('Move a document to trash') and resource ('document'), immediately clarifying the operation as a soft-delete. It distinguishes itself from permanent deletion by explicitly naming empty_trash, and from other delete_* siblings by focusing on documents.

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 states when to use this tool (soft-delete with recoverability) and provides a direct alternative: 'Use empty_trash for permanent deletion.' This is clear routing that prevents an agent from accidentally choosing permanent deletion.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the warning is redundant but reinforces the safety profile. The description adds the confirmation requirement via the 'confirm' parameter, which is useful context. However, it does not disclose what happens to associated data or whether the operation is reversible.

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

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

The description is a single short sentence with the warning flag front-loaded. It is concise and to the point, though it could be slightly more structured by separating the warning from the action.

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 (3 scalar params, no output schema), the description is adequate. The destructive nature is highlighted, and the confirm parameter is self-explanatory. However, missing usage guidance and potential side effects mean it falls short of being fully complete for an agent.

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 each parameter (id, note_id, confirm) having a description. The description adds no extra semantic meaning beyond the schema, so baseline 3 is appropriate; the confirm parameter's purpose is already clear from 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 clear verb ('Delete') and a specific resource ('a note from a document'). It distinguishes from sibling tools by targeting notes specifically, though it does not explicitly differentiate from other delete tools like delete_tag or delete_document_version.

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 or when not to use it. It does not mention prerequisites, such as needing the document ID and note ID, or that the operation is irreversible, which would help agents decide.

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

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

Annotations already declare destructiveHint=true, so the description's extra context about permanence, system-wide impact, and cascade to all documents adds meaningful behavioral transparency. It could be more precise about what 'affect' means for the documents, but it goes 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?

Two short sentences with the destructive warning front-loaded. Every word adds necessary clarity about permanence and scope, with no filler.

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

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

For a simple two-parameter destructive delete with annotations and a confirm flag, the description conveys the key risk and consequence. It could clarify what happens to the affected documents, but it is substantially complete for correct invocation.

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

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

The description adds no parameter-level meaning. The confirm parameter has a schema description, but the id parameter is only typed as a number with no explanation of what it references. With 50% schema coverage, the description should have compensated but did not.

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

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

The description uses a specific verb and resource: permanently delete a document type. It also clarifies system-wide scope and the impact on all documents using that type, which distinguishes it from sibling tools like delete_document or update_document_type.

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 destructive warning and permanence imply when this tool is appropriate, but the description does not explicitly name alternatives or state when-not-to-use. It lacks direct routing guidance such as 'use update_document_type to modify instead'.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's warning aligns. It adds value by specifying the root-version restriction and the permanence of deletion, which are not in the annotations. No contradiction.

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

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

Two sentences with no waste. The destructive warning is front-loaded, and the root-version constraint is stated immediately. 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 destructive single-resource delete tool with full schema coverage and clear annotations, the description covers the key behavioral constraints. It doesn't mention return values, but there's no output schema and the operation is simple enough that this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the root-version restriction but doesn't add new parameter-level meaning beyond what the schema provides. 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 states a specific verb ('delete'), a specific resource ('one non-root version of a document'), and a critical constraint (root version can't be deleted). It clearly distinguishes from sibling tools like delete_document and upload_document_version.

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

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

The description explicitly warns about the destructive nature and the root-version exclusion, which tells the agent when NOT to use it (for root versions). It doesn't explicitly name alternatives like delete_document for root versions, but the guidance is clear enough.

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

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

Annotations already declare destructiveHint=true, so the description adds real value by spelling out consequences: mail rules using the account are also deleted, fetching stops, but imported documents remain untouched. This goes beyond the binary annotation and gives the agent a precise picture of collateral effects.

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 one compact sentence with the destructive warning front-loaded. Every clause adds useful consequence information, and there is no filler or redundant restatement of the tool name.

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 two-parameter operation, the description covers the main action, cascade deletion, and what is unaffected. The schema already documents that confirm must be true. A minor gap is that id's exact semantics are not described, but this is still largely sufficient 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 only 50%: the confirm parameter is documented, but id is just a bare number. The description does not compensate by explaining that id identifies the mail account to be deleted or how it relates to confirm, so an agent must infer that meaning.

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

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

The description states a specific verb ('delete') and resource ('mail account'), making the action unmistakable. It also clarifies permanence and the stop-fetching effect, which separates it from create/update/test/process account siblings.

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

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

The description clearly indicates when the tool is appropriate: when a mail account must be permanently removed and no longer fetched. It does not explicitly name alternatives or exclusion conditions, but the sibling context makes the usage obvious.

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, and the description adds useful context beyond that: the deletion is permanent and already-imported documents are not affected. This clarifies the scope and side effects without 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?

The description is only two sentences, front-loads the destructive warning, and includes no redundant wording. Every clause contributes meaningful information about the operation and its consequences.

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

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

For a simple two-parameter destructive delete with a confirm flag in the schema, the description plus annotations cover the essential behavior, permanence, and non-scope of the operation. It does not explain return values or error cases, but the low complexity and absence of an output schema make this acceptable.

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

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

Schema coverage is 50%, with only the confirm parameter documented in the schema. The description implies that id refers to the mail rule to delete, which adds some meaning, but it does not elaborate on how to obtain or validate the id, and confirm semantics are left entirely to the schema. It provides partial but not full compensation for the missing id description.

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

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

The description uses a specific verb and resource (permanently delete a mail rule) and adds the permanence qualifier, which clearly distinguishes it from update or non-destructive actions. It also isolates the mail-rule resource, separating it from siblings like delete_mail_account.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as update_mail_rule, list_mail_rules, or delete_mail_account. The description implies use for deleting a mail rule but offers no prerequisites, exclusions, or routing context beyond that.

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 'permanently' and a warning, which is consistent and slightly extends the annotation. It does not disclose other behavioral aspects like the need for confirmation (though the schema covers that) or consequences of deleting a referenced view. Given the annotation coverage, the bar is lower, and the description adds some context but not rich detail.

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

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

The description is a single sentence with a warning prefix, front-loading the destructive nature. It is efficient and wastes no words, though it is minimal. The structure is clear and appropriate 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 delete operation, the description conveys the core action and permanence. It does not explain the return value or error behavior (e.g., what happens if the id doesn't exist), but the annotations and schema cover safety and confirmation. The description is adequate but leaves some context 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 50% (only the confirm parameter has a description). The description does not mention either parameter, leaving the 'id' parameter entirely undocumented. It fails to compensate for the schema gap by explaining what id refers to. This is a significant omission for a tool with two required parameters.

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

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

The description 'Permanently delete a saved view' uses a specific verb and resource, clearly stating the action. It distinguishes itself from sibling delete tools by naming the resource type, though it relies on the tool name for disambiguation. It adds the qualifier 'permanently' which is helpful.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_saved_view or get_saved_view. It only warns that the operation is destructive, which is cautionary, not a usage directive. There is no mention of when not to use it or what to use instead.

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

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

Annotations already include destructiveHint=true, but the description adds concrete context: the deletion is 'permanent' and the shared URL 'will stop working.' This goes beyond the bare hint and gives the agent a clear sense of the irreversible consequence.

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

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

Two sentences with a front-loaded destructive warning, followed by the action and its consequence. Every word earns its place; there is no fluff or redundancy.

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

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

For a simple two-parameter delete operation without an output schema, the description covers what the tool does and what effect it has. It does not explain return values or all side effects, but those are unnecessary for this straightforward destructive action.

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 50%: only 'confirm' has a description in the schema. The tool description adds no parameter meaning, leaving 'id' undocumented. It does not compensate for the low coverage, but the confirm requirement is adequately covered by 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 the specific verb 'delete' and the resource 'share link', and clarifies the consequence ('The shared URL will stop working'). This distinguishes it from the many other delete_* siblings by naming the exact resource, so an agent can immediately 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 does not explicitly state when to use this tool versus alternatives like delete_share_link_bundle or when it is not appropriate. However, the action is self-evident from the name and description, making usage guide the implied but not explicit.

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

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

Annotations already mark destructiveHint=true, and the description adds specific behavioral context: the public link stops working and documents are unaffected, plus permanent deletion. This goes beyond the annotation without contradicting it. It lacks details on permissions or reversibility, but the core destructive behavior is well disclosed.

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

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

A single, front-loaded sentence with the destructive warning first. Every word earns its place, and the effect on documents is concisely stated. No fluff.

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

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

For a simple deletion tool with two parameters and no output schema, the description covers the core behavior (permanence, effect on public link and documents). It doesn't mention prerequisites like authentication or admin rights, but these are not critical for this action's selection. The description is adequate for an agent to understand when and how to call it.

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

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

Schema description coverage is 50% (only confirm has a description). The description does not clarify the 'id' parameter, which is left undocumented. Since coverage is below 50%, the description should compensate but does not mention id at all. Confirm is already described in the schema, so the description adds no parameter value.

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 (delete), the resource (share link bundle), and the consequence (permanent deletion, public link stops working, documents unaffected). It distinguishes itself from sibling tools like delete_share_link by specifying 'bundle', so an agent can select it correctly without ambiguity.

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

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

The description implies usage when you want to delete a bundle while preserving documents, but it does not explicitly contrast with alternatives like delete_share_link or provide when-not conditions. The 'documents are not affected' hint gives some context, but no explicit routing to alternatives.

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

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

Annotations already convey destructiveHint=true, and the description adds meaningful context beyond that: the deletion is permanent, system-wide, and impacts all documents using the path. However, it stops short of clarifying whether documents are deleted, unlinked, or left in an invalid state, which would make the behavior fully transparent.

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

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

The description is extremely concise: two short sentences with the destructive warning front-loaded. Every phrase earns its place, and the all-caps warning effectively signals risk without adding 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 destructive tool with no output schema, the description leaves important operational details unresolved: what exactly happens to documents that reference the path, whether deletion can fail if documents are still using it, and what the response or confirmation flow entails. The warning is strong but the operational semantics are 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 only 50%, and the 'id' parameter has no description in the schema. The tool description does not compensate by explaining that 'id' refers to the storage path's identifier or how 'confirm' relates to the destructive nature 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 names the exact verb 'delete' and resource 'storage path', and clarifies the scope ('from the entire system') and the consequence ('affect ALL documents that use this storage path'). This clearly distinguishes it from sibling tools like update_storage_path, test_storage_path, and create_storage_path.

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 warning explains the impact of deletion, but it does not say when to use this tool versus siblings such as update_storage_path, nor does it suggest reassigning documents first or avoiding deletion while documents still reference the path. Usage context is only implied, not explicit.

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

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

Annotations already mark destructiveHint=true and readOnly=false, so the description's warning is consistent with the structured metadata. It adds valuable behavioral context by disclosing the cascade effect: the deletion propagates to all documents using the tag and is permanent. This goes beyond what the annotations alone state.

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

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

Three short sentences, front-loaded with the destructive warning, with no filler. Every clause either states the action, the consequence, or the caution.

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 destroy operation, the combination of description and schema covers the target entity, the global cascade, the permanence, the confirmation requirement, and the safety profile. No output schema is needed, and an agent has enough information to decide whether to call the tool and what to pass.

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 description does not directly explain the `id` or `confirm` parameters, and the schema only documents `confirm` (50% coverage). It does add implicit meaning by defining what object is being deleted, which makes `id` interpretable as the tag identifier, but it does not compensate for the undocumented `id` field. The warning also provides context for why `confirm` exists, though the schema already states its requirement.

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

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

The description opens with an explicit verb and object ('Permanently delete a tag') and clarifies the scope ('from the entire system'). It differentiates itself from sibling read/update tools (list_tags, get_tag, update_tag) by emphasizing permanent, system-wide deletion.

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 destructive consequence ('remove the tag from ALL documents') gives the agent a clear condition to evaluate before choosing this tool, and 'Use with extreme caution' is an explicit warning. However, it does not name any alternative (e.g., update_tag) or state when not to use it, so usage guidance is mostly implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context beyond the annotations: the deletion is permanent, and documents already processed by the workflow are not affected. This is genuinely useful behavioral disclosure.

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 front-load the destructive warning and then add the key side-effect clarification. Every word earns its place and no filler is present.

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

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

For a simple two-parameter delete tool with a confirm flag already documented in the schema, the description covers the essential side-effect and permanence. It does not mention return behavior or prerequisites, but these are largely unnecessary for this operation, so the description is close to complete.

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

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

Schema description coverage is 50%: the confirm parameter is described, but id has no schema description. The tool description does not compensate by explaining that id identifies the workflow or how confirm must be supplied, 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 names a specific verb ('delete') and resource ('workflow'), and clarifies that the deletion is permanent. It clearly distinguishes this from related tools like delete_workflow_action or delete_workflow_trigger by stating exactly what object is removed.

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

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

No guidance is given about when to choose this tool over alternatives such as delete_workflow_action, disable/update_workflow, or when deletion should be avoided. The destructive warning implies caution, but it does not provide explicit usage conditions 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?

Annotations already mark the operation as destructive and not read-only, so the description's warning is largely redundant, but 'permanently' adds the important irreversibility detail. This is meaningful because sibling tools include restore_from_trash, implying some deletions may be reversible.

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 entire description is one front-loaded warning plus a clear action. Every word earns its place and nothing is padded.

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 two simple parameters, a required confirmation flag, a destructiveHint, and no output schema, the description plus schema gives an agent what it needs to invoke the tool safely. The only minor omission is any hint of the response value or side effects on workflows, which is usually trivial for delete operations.

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 fully documents 'confirm' as a required safety flag, and 'id' is inferable as the workflow action identifier from the tool name and description. The description itself adds no explicit parameter detail, but the moderate schema coverage leaves no serious ambiguity.

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') and resource ('workflow action') and states the operation is permanent. This clearly distinguishes it from sibling tools such as update_workflow_action, get_workflow_action, delete_workflow, and delete_workflow_trigger.

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 'permanently delete a workflow action' implies the natural use case: call this when the agent intends to remove a workflow action for good. It does not, however, contrast with alternatives or state when not to use it, leaving the guidance implicit.

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

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

The description explicitly warns 'DESTRUCTIVE' and states 'Permanently delete', which aligns with and reinforces the annotations (destructiveHint=true, readOnlyHint=false). It adds the 'permanently' qualifier, which is useful context beyond the annotation. However, it does not disclose additional behavioral details such as cascading effects, irreversibility beyond the obvious, or whether related resources are affected.

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 short and front-loads the critical destructive warning. It earns its place with the 'permanently' qualifier, though it could be slightly more informative without becoming verbose.

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

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

For a simple two-parameter destructive operation, the description plus annotations and schema are mostly sufficient. However, there is no output schema and no mention of what happens after deletion (e.g., success response, errors), and the 'id' parameter is undocumented. The description is adequate but leaves minor gaps.

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

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

Schema description coverage is 50%: the 'confirm' parameter is documented in the schema, but 'id' has no description. The tool description does not add any parameter-level meaning beyond the schema. Since the schema covers half the parameters and the description adds nothing, a baseline of 3 is appropriate.

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

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

The description states a specific verb ('delete') and resource ('workflow trigger'), clearly distinguishing it from sibling tools like delete_workflow or delete_workflow_action. It is concise and unambiguous, though it doesn't explicitly differentiate from the broader delete_* family beyond the resource name.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any context about prerequisites or consequences beyond the destructive warning. The description implies it is for deleting a workflow trigger, but it does not explain when a user should choose this over update_workflow_trigger or other delete 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 declare readOnlyHint=true, so the description doesn't need to restate safety. The description adds the base64 return format, which is useful behavioral context. However, it doesn't disclose details like whether 'original' affects the response, file size limits, or whether the download is a direct binary vs. wrapped in JSON. With annotations covering the read-only nature, a 3 is appropriate.

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

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

The description is a single, efficient sentence that front-loads the action and resource. It earns its place by adding the base64 return detail. It could be slightly more informative about parameters, but it is not bloated.

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 download tool with no output schema and 0% schema description coverage, the description is too thin. It doesn't explain the 'original' parameter, the response envelope, or how this differs from get_document_content/download_documents_bulk. An agent would need to inspect the schema or guess to use it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the two parameters. It only explains 'id' implicitly ('by ID') and says nothing about 'original'. The description adds minimal meaning beyond the schema, leaving the 'original' parameter's purpose and effect undocumented.

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

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

The description states a specific verb ('Download') and resource ('a document file by ID'), and clarifies the return format ('base64-encoded resource'). It is clear enough to distinguish from siblings like get_document_content or get_document_preview, though it doesn't explicitly name those alternatives.

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

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

The description implies usage: call it when you need the raw document file as base64. It does not explicitly state when to use alternatives like get_document_content, get_document_preview, or download_documents_bulk, nor does it mention any exclusions or prerequisites. The context is clear but not fully elaborated.

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

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

Annotations declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that the response is a base64-encoded ZIP file, which is useful behavioral context. However, it doesn't disclose details like file size limits, timeout behavior, or how the ZIP is structured (e.g., folder hierarchy), which could matter for large bulk downloads.

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 action and return format are front-loaded. It could arguably include a hint about the 'content' parameter's effect on ZIP contents, but the schema covers that.

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

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

For a bulk download tool with readOnlyHint=true and full schema coverage, the description is mostly adequate. The main gap is that it doesn't mention the relationship to download_document (single vs. bulk) or any practical caveats like response size, which an agent might need to know when choosing between the two tools.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate since 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 verb ('Download') and resource ('multiple documents as a ZIP archive'), which clearly distinguishes it from single-document download tools like download_document. It doesn't explicitly name a sibling alternative, but the bulk vs. single distinction is clear enough from the name and 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 implies usage for downloading multiple documents at once, and the sibling list includes download_document for single downloads, providing implicit context. However, it doesn't explicitly state when to prefer this over download_document or mention any limits or prerequisites beyond the schema's maxItems.

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 readOnlyHint=false and destructiveHint=true. The description adds meaningful context beyond those hints by warning that 'delete' permanently removes correspondents from the entire system, clarifying the scope and severity of the destructive action.

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: two sentences plus a warning, with the core purpose and exclusion stated first. Every sentence earns its place and there is no redundant 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?

Despite good safety context, the tool has six parameters including a nested permissions object and no output schema. The description does not explain merge/owner semantics or how permissions should be structured, so an agent would lack key information needed to construct a correct call.

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

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

Schema description coverage is only 17%, so the description must compensate, but it only explains the operations at a high level. It does not clarify the meaning of 'merge', 'owner', or the semantics of the permissions object, leaving several parameters effectively unexplained.

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 ('correspondent objects themselves') and the two operations it supports (permissions, delete). It also explicitly distinguishes itself from edit_documents_bulk by stating what it does NOT do, so an agent can disambiguate it from a likely sibling.

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

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

The description gives explicit when-not-to-use guidance: 'This does NOT assign correspondents to documents' and names the exact alternative tool and method. This is more than sufficient for an agent to route to the correct sibling.

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 strong warning that 'delete' permanently removes custom fields from the entire system, which goes beyond the destructiveHint annotation by specifying permanence and scope. It also clarifies the tool operates on definitions, not values. No contradiction with annotations; the extra warning adds meaningful behavioral context.

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

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

Two sentences, front-loaded with purpose and then exclusions/warnings. The emoji and warning are useful and not filler. Slightly dense but every sentence earns its place. Not as tight as the highest examples, but efficient.

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

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

For a destructive bulk tool with no output schema, the description covers the main safety aspects and the key sibling distinction. However, it omits any mention of the singular delete_custom_field alternative, does not clarify what the confirm parameter does beyond the schema, and the unsupported 'permissions' reference adds confusion. An agent would need to inspect the schema to fully understand operation and custom_fields.

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

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

Schema description coverage is only 33%, with custom_fields and operation lacking property descriptions. The description helps by indicating custom_fields are the definitions themselves, but it does not explicitly state they are IDs or explain the array's role. Operation's enum is self-documenting, but the confirm parameter is only explained in the schema. The description adds some meaning but does not fully compensate for the low coverage.

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

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

The description says 'Manage custom field definitions themselves (permissions, delete)' which names the resource and includes 'delete', but 'permissions' is not supported by the schema (operation enum only allows 'delete'). This is misleading. The distinction from edit_documents_bulk is clear, but the verb 'manage' is less specific than stating the actual bulk delete operation.

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 states this does NOT modify custom field values and directs the agent to edit_documents_bulk with method 'modify_custom_fields' as the alternative. This clear when-not guidance prevents a common confusion. However, it does not mention the sibling delete_custom_field for singular deletes, so it lacks a complete routing picture.

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 destructiveHint=true and readOnlyHint=false. The description adds valuable context: the 'delete' method requires confirm=true and permanently deletes, remove_tag vs delete_tag semantics, and all=true limitations. Some method-specific behaviors (e.g., merge, split) aren't detailed, but the most critical destructive aspects are covered.

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

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

The description is long but dense with essential information for a complex 27-parameter tool. It's front-loaded with the core purpose, then flows logically through methods, selection, destructive warnings, and specific method notes. While not bulleted, it remains scannable and every sentence contributes value.

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

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

Given the tool's complexity (27 params, no output schema), the description covers the most critical aspects: method list, selection modes, destructive warnings, and key parameter formats. However, it doesn't explain every method's parameters or return behavior, leaving some gaps for the agent to infer. Still, it's remarkably complete for such a large 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 52%, so the description carries partial burden. It explains filters format with examples, confirms the requirement for delete, and details custom field value formats (monetary/documentlink). This adds meaning beyond the schema, though many parameters (e.g., degrees, pages) remain undocumented. Overall, it compensates well for the coverage gap.

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

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

The description clearly states the tool applies one of a fixed set of operations to many documents at once, listing all methods. It explicitly differentiates from update_document for per-document field edits, making its purpose and scope 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?

Provides explicit when-to-use guidance: names update_document as the alternative for per-document field edits, warns that all=true is not supported for certain methods, and clarifies selection via documents vs. all+filters. This gives clear routing to the correct tool.

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, but the description adds crucial context: 'delete' permanently removes document types from the entire system. This goes beyond the annotation and appropriately signals system-wide, irreversible impact.

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, purposeful sentences. The core scope is front-loaded, and the disambiguation and destructiveness warning each earn their place without padding.

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

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

The description covers the two riskiest aspects: sibling confusion and irreversible deletion. However, given six parameters, nested permission objects, low schema coverage, and no output schema, the description leaves 'owner' and 'merge' unexplained, so it is not fully complete.

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

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

With only 17% schema description coverage, the description needed to compensate for the undocumented parameters, but it only names operations in prose. It adds no meaning for 'owner', 'merge', or 'confirm', and while 'permissions' maps to a schema object, the relationship between operation and parameters is not explained.

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

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

The description names the exact resource ('document type objects themselves') and the two operations ('permissions, delete'). It also explicitly distinguishes itself from edit_documents_bulk, resolving the most likely source of confusion.

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

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

The description explicitly states when not to use this tool: 'This does NOT assign document types to documents' and names the alternative ('use edit_documents_bulk with method set_document_type'). This leaves little 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 mark destructiveHint=true and readOnlyHint=false. The description adds crucial context beyond annotations: 'delete' permanently removes tags from the entire system. It does not expand on set_permissions side-effects, but the destructive warning covers the most consequential behavior.

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

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

The description is compact, front-loaded with the core purpose, and each sentence earns its place: what it does, what it does not do and which sibling to use, and a critical destructive warning. No filler or redundancy.

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

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

Given there is no output schema and limited parameter documentation, the description could add more context about response behavior or parameter effects. However, combined with the schema and annotations, it provides enough for an agent to avoid the most dangerous misuse and choose the correct operation.

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

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

Schema description coverage is only 17%, so the description must compensate, but it only names operations and their general domain. Parameters like merge and owner are not explained, and the permissions object's semantics are only implied. This leaves significant gaps for an agent trying to construct correct calls.

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

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

The description clearly identifies the tool as managing tag objects themselves (permissions, delete) and explicitly distinguishes it from adding/removing tags on documents. This prevents confusion with the heavily overlapping sibling edit_documents_bulk.

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 states when NOT to use this tool and names the alternative: use edit_documents_bulk with methods 'add_tag'/'remove_tag'/'modify_tags' for document-level tag changes. The warning about permanent deletion also guides safe usage.

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 indicate the operation is not read-only and not destructive, and the description's 'Send' action is consistent with that. However, the description adds no behavioral context beyond the annotations—it does not mention side effects, prerequisites like configured mail accounts, whether an email is actually dispatched, or what happens on failure.

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

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

A single, information-dense sentence with no filler. It front-loads the action ('Send'), the resource ('document'), and the recipients, and every word contributes to meaning.

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

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

For a straightforward send action with fully documented parameters, the description is minimally viable. However, it lacks guidance about prerequisites, side effects, or return/confirmation behavior, which would help an agent call it with full confidence.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents all five parameters. The description adds nothing about parameter meaning or format beyond what the schema states, such as comma-separated addresses or the archive-version default.

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 ('Send'), a clear resource ('document'), and a delivery method ('via email to one or more recipients'). This distinguishes it from sibling tools, which are mostly document retrieval, editing, or mail-account management tools.

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

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

No guidance is provided on when to use this tool versus alternatives such as creating share links, bulk downloading, or other document-sharing mechanisms. The description only states what the tool does, leaving the agent to infer its place among the many document-related 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context: the operation is irreversible and permanently deletes. This goes beyond the generic annotation and gives the agent a clear warning about consequences. No contradiction with annotations.

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

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

The description is a single sentence with a strong leading warning (⚠️ DESTRUCTIVE) that immediately signals the risk. It states the action, the two usage modes, and the irreversible consequence with no wasted words. The structure is ideal for front-loading critical information.

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

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

For a tool with only two parameters and no output schema, the description is adequately complete. It covers the two possible operations and the irreversible nature. It does not mention return values, but that is not required since no output schema exists. The missing guidance on when to prefer this over restore_from_trash is a minor gap, but overall it is sufficient for an agent to 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?

Schema description coverage is 100%: both confirm and documents are described in the schema. The description does not add any parameter-specific meaning beyond what the schema provides, such as the optional nature of documents and the required confirm flag. It implicitly references the two modes but adds no new semantic detail, so it sits at the baseline for full schema coverage.

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

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

The description clearly states the verb (permanently delete) and the resource (documents from the trash), and also covers the two operational modes (specific documents or entire trash). It does not explicitly differentiate from siblings like restore_from_trash or delete_document, but the resource focus is evident enough for an agent to infer its 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 description implies when to use it (when you need to purge trashed documents), but it does not explicitly state when not to use it or name alternatives such as restore_from_trash for recovering documents or delete_document for removing a document outside the trash. The 'or empty the entire trash' clause gives a usage nuance but lacks 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 declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it returns 'full details including matching rules,' which is useful behavioral context beyond the annotation. It doesn't disclose pagination, error behavior, or response format, but for a simple read-by-ID tool with readOnlyHint, this is adequate.

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

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

One sentence, zero waste, and the key information (get by ID, full details, matching rules) is front-loaded. 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 read-by-ID tool with one parameter and readOnlyHint annotation, the description is nearly complete. It tells the agent what it returns (full details including matching rules) and how to identify the resource (by ID). The only minor gap is not describing the response structure, but no output schema exists and the description's mention of 'full details' is sufficient for a tool of this simplicity.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'id' parameter. The description says 'by ID' which clarifies the parameter's role, but doesn't add details like format, requiredness, or how to obtain the ID. Since there's only one parameter and its purpose is inferable from the tool name and description, this is minimally adequate.

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 a specific correspondent by ID and includes full details including matching rules. It distinguishes itself from list_correspondents (which lists all) and from create/update/delete correspondent tools, though it doesn't explicitly name a sibling.

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

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

The description implies usage when you need a single correspondent's full details by ID, which is reasonably clear context. However, it doesn't explicitly state when to use this over list_correspondents or mention any alternatives 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?

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that the response includes 'full details including data type and extra configuration', which is useful but not deep behavioral context. It doesn't mention error behavior, auth requirements, or what happens if the ID doesn't exist, but with readOnlyHint covering the safety profile, a 3 is appropriate.

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

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

One sentence, front-loaded with the verb and resource, and every word earns its place. The detail about 'data type and extra configuration' is valuable and not redundant with the schema.

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

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

For a simple single-parameter read tool with readOnlyHint=true, the description is nearly complete. It tells the agent what the tool does and what the response includes. It doesn't explain return format or error cases, but the simplicity of the tool and the annotation coverage make this a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'id' parameter. The description clarifies that 'id' is the custom field's ID and that the result includes full details, which adds some meaning beyond the bare schema. However, it doesn't specify the ID format (number is in schema) or any constraints, so it only partially compensates.

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

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

The description states a specific verb ('Get'), a specific resource ('custom field'), and the retrieval mechanism ('by ID'), and it adds detail about what the response includes ('full details including data type and extra configuration'). It is clear and distinct from siblings like list_custom_fields or delete_custom_field, though it doesn't explicitly name them.

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

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

The description implies usage: call this when you need a single custom field's full details by ID. It doesn't explicitly state when to use this vs list_custom_fields or update_custom_field, but the 'by ID' and 'full details' phrasing gives reasonable context. No exclusions or alternatives are named.

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

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

Annotations provide readOnlyHint=true, but the description adds substantial behavioral nuance beyond that: content is excluded by default, version handling, and the subtle page_count vs. root version behavior. It also gives a concrete example (password-protected PDF) and a practical warning. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, content exclusion, version handling, and a cautionary note. It is front-loaded with the main purpose and logically structured, avoiding redundancy.

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

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

Given the complexity (versions, content exclusion, page_count semantics) and no output schema, the description covers all essential aspects an agent needs to call the tool correctly. It clearly states what is included and excluded, how versions behave, and which fields are unreliable for readability checks.

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

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

Schema coverage is 0% but there is only one parameter 'id' of type number, which is self-explanatory. The description reinforces it with 'by ID'. While it doesn't elaborate on format, the trivial nature of the parameter makes this sufficient.

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

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

The description opens with a specific verb and resource: 'Get a specific document by ID with full details including correspondent, document type, tags, and custom fields.' It explicitly differentiates from get_document_content by stating content is excluded by default and naming the alternative. It also distinguishes the version-related semantics from get_document_metadata.

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

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

The description gives explicit when-to-use vs when-not-to-use: it says to use get_document_content when content is needed, and it warns against using page_count to judge readability. It also references version management tools (upload_document_version etc.) providing clear routing 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?

Beyond the readOnlyHint annotation, the description discloses that the tool requires AI to be enabled and fails with a specific error otherwise. It also reveals the shape of its output (IDs for existing objects, suggested names for new ones), which is useful 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?

The description is dense but not bloated: the first sentence gives the core action and result contents, the second adds the prerequisite and failure behavior, and the third routes to the correct alternative. 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?

With only one simple parameter and no output schema, the description provides enough context: what suggestions are returned, what prerequisite must hold, what happens if it doesn't, and which sibling to use instead. Nothing essential is missing.

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

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

Schema coverage is 100% and the single id parameter is already documented as 'The document ID', so the description adds little parametric meaning. It refers to 'a document' in passing but does not need to elaborate given the schema covers it.

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

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

The description opens with a specific verb and resource ('Get LLM-based suggestions for a document') and enumerates exactly what is returned. It also distinguishes this tool from its closest sibling, get_document_suggestions, by naming the AI/non-AI difference.

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

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

It states the AI-enabled prerequisite and the exact failure mode if unmet, and explicitly instructs to use get_document_suggestions for classifier suggestions that work without AI. The when-to-use and when-not-to-use guidance is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description reinforces this by describing the tool as reading text, but does not add further behavioral context such as response size, format, or error behavior. Still, it is consistent and not misleading.

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

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

Two sentences with no filler. The first sentence states the core operation and the second gives the usage guidance; 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, one-parameter, read-only getter, the description covers the core operation and the return value ('text content') despite lacking an output schema. It could mention error conditions or content format, but given the tool's simplicity and the readOnlyHint annotation, it is sufficiently complete.

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

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

The input schema only defines id as a required number with no description (0% coverage). The description compensates by identifying the id as the identifier of a specific document, clarifying that the parameter is a document ID rather than an arbitrary number. It does not explain where the ID comes from or any format nuances, but for a single parameter this is minimally adequate.

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

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

States the exact operation ('Get'), resource ('text content'), and target ('specific document by ID'). The phrase 'text content' differentiates it from siblings like get_document_metadata, get_document_preview, and get_document_thumbnail, though it does not name them explicitly.

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

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

Provides an explicit when-to-use condition: 'Use this when you need to read or analyze the actual document text.' This clearly signals the intended use case, but does not mention when to prefer alternative getters (e.g., for metadata or previews), 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 readOnlyHint annotation already communicates that this is a safe read operation, so the description does not need to restate that. It adds the detail that the history includes actor and timestamp, but does not disclose behavioral traits such as pagination behavior, ordering, or any permission requirements. The annotation and description are consistent, and the description adds a modest amount of context 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 a single, compact sentence that front-loads the primary action ('Get the change history') and immediately clarifies the output ('who changed what and when'). Every word is functional; there is no redundancy or filler.

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

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

For a read-only tool with three well-documented parameters and no output schema, the description sufficiently conveys the tool's purpose and return content. It does not explicitly mention pagination or result ordering, but the schema's page/page_size parameters imply those behaviors, making the overall definition complete enough for an agent to use it correctly.

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

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

Schema description coverage is 100%, with all three parameters (id, page, page_size) already documented in the schema. The description does not add any additional parameter-level detail, so it does not improve on 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 verb ('Get'), a specific resource ('change history / audit log for a document'), and the exact information it provides ('who changed what and when'). This clearly distinguishes it from sibling tools like get_document_content or get_document_metadata, which serve different purposes.

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 use case (retrieving audit information for a document) but does not explicitly name alternatives or state when not to use this tool. There is no mention of sibling tools like get_document_content or get_document, so an agent must infer the appropriate selection from the description 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, and the description is consistent with a read operation. It adds useful context about the response contents (checksums, sizes, archival info), but it does not disclose any further behavioral traits such as permission requirements or edge cases. Given the annotation coverage, a middle score is appropriate.

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

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

A single clear sentence with no filler. The key action and resource are front-loaded, and the additional metadata details are presented compactly without redundancy.

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

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

For a simple one-parameter read-only operation with no output schema, the description is mostly complete: it names the resource and highlights the return contents. It is slightly vague about 'archival information' and does not clarify its relationship to get_document, but an agent can still invoke it correctly.

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

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

Schema description coverage is 100% for the single parameter 'id', which is documented as 'The document ID'. The description does not add extra parameter-level meaning, but with full schema coverage, the baseline score applies.

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

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

The description uses a specific verb-resource pair ('Get file metadata for a document') and lists concrete contents (checksums, file sizes, archival information). This distinguishes it from content- or download-focused siblings, though it does not explicitly differentiate it from get_document, which may also return metadata.

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 like get_document, get_document_content, or download_document. The phrase 'file metadata' implies a use case, but no exclusions or sibling comparisons are provided.

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

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

The annotation readOnlyHint=true already signals a safe read operation, and the description adds the behavioral detail of returning a base64-encoded image. However, it does not disclose potential size limits, format specifics, or any other side effects. The description adds some value but is not rich in 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?

The description is a single sentence that is concise and front-loaded with the primary purpose. It wastes no words and clearly communicates the essential information.

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

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

For a simple tool with one well-documented parameter and an annotation indicating read-only, the description is sufficiently complete. It states what the tool does and the return format. It could mention the image format or dimensions, but these are not critical for a preview tool, and the lack of an output schema means the description appropriately covers the return.

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

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

Schema coverage is 100% (the 'id' parameter has a description 'The document ID'), so the schema already documents the parameter adequately. The description does not add any extra semantic meaning to 'id' beyond what the schema provides, aligning with the baseline for high coverage.

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

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

The description clearly states the action ('Get') and the resource ('full-page preview image of a document'), and mentions the return format (base64-encoded). It distinguishes itself from the sibling 'get_document_thumbnail' by specifying 'full-page', though it does not explicitly name the alternative.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_document_thumbnail or get_document_content. It does not mention any conditions or exclusions, leaving the agent to infer the appropriate use case.

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

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

Beyond the readOnlyHint annotation, the description discloses that results are limited to IDs of existing objects and clarifies the classifier-based nature of the suggestions. This adds useful behavioral context, though it does not elaborate on possible empty results or response shape.

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

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

Two sentences, no filler, with the primary purpose front-loaded and the alternative guidance placed second. Every sentence contributes either scope or routing information.

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

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

For a single-parameter, read-only tool with no output schema, the description covers the suggestion fields, the existing-only return constraint, and the sibling distinction. It does not specify the exact response format, but the provided detail is sufficient for correct selection and invocation.

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

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

The input schema already documents the sole parameter 'id' with 100% coverage ('The document ID to get suggestions for'), so the description adds no new parameter-level semantics. The baseline score of 3 applies because the schema handles the documentation burden.

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

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

The description states a specific verb ('Get classifier-based suggestions') and resource (a document's correspondent, tags, document type, storage path, and dates), which is unambiguous. It also distinguishes itself from get_document_ai_suggestions by noting the classifier approach and the constraint that it returns IDs of EXISTING objects only.

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

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

The description explicitly names the alternative get_document_ai_suggestions and the condition for choosing it: LLM suggestions that may propose a title and new objects. This provides a clear when-to-use/when-not-to-use rule, so an agent can route between the two suggestion tools without further exploration.

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

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

The readOnlyHint annotation already signals this is a safe read operation一味 The description adds value by disclosing the response format in detail (base64-encoded WebP image resource), which is helpful given there is no output schema. It does not cover error cases or size limits, but for a simple read-only fetch the disclosure is reasonable.

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

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

The description is two short sentences with no filler. It front-loads the action and resource, then provides the key output detail. 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 one-parameter, read-only, simple fetch tool, the description provides the essential purpose and the return format, compensating for the missing output schema. It is complete enough for an agent to select and invoke the tool correctly, though it could mention that the ID is specifically a document ID.

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 only says 'id' is a number, with no description. The main description clarifies that this ID selects a document whose thumbnail will be retrieved, giving the parameter its purpose and context. This meaningfully compensates for the 0% schema description coverage, though it could have been more explicit by naming it the document ID.

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

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

The description states a specific verb ('Get'), a resource ('document thumbnail'), and the input ('by ID'), and adds the output format ('base64-encoded WebP image resource'). It does not explicitly differentiate from sibling tools like get_document_preview, which is a close alternative, so it stops short of a 5.

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

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

The description implies when to use the tool: whenever a thumbnail image of a document is needed. However, it provides no explicit guidance about when not to use it, nor does it mention alternatives such as get_document_preview or get_document_content, leaving some routing ambiguity.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds 'full details including matching rules', which gives some context about the return payload but does not describe other behavioral aspects such as error behavior (e.g., 404 on missing ID), auth requirements, or rate limits. It does not contradict annotations and adds minimal value beyond them.

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

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

The description is a single sentence with no filler. It front-loads the verb and resource, includes the scoping detail ('specific ... by ID'), and adds the distinguishing output detail ('full details including matching rules'). Every word contributes to understanding.

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

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

For a simple single-parameter read tool with readOnlyHint, the description is adequate but not rich. It mentions 'full details including matching rules' but does not outline the response structure or edge cases like missing IDs. Given the lack of an output schema, the description leaves the return format to inference, which is a notable gap for an agent that needs to parse results.

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 provides only a 'number' type for id with 0% coverage, so the description must explain the parameter. 'by ID' clearly identifies the id as the document type's unique identifier. This adds meaningful semantics beyond the bare schema, even though it does not specify the format or source of the ID.

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

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

The description clearly states the verb 'Get', the resource 'specific document type', and the identifier-based access ('by ID'). It adds 'full details including matching rules', which differentiates it from list_document_types and other get_* tools. An agent can immediately recognize what this tool does and how it differs from getting a document or listing types.

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