mcp-paperless-ngx

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

Annotations only indicate the operation is not read-only and not destructive; the description adds that the effect is a state change that suppresses tasks from the UI. This goes beyond the annotations without contradicting them, though it doesn't discuss reversibility or error behavior.

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

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

Single sentence, front-locads the action, and contains no filler or repetition of schema/annotations.

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

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

For a one-parameter mutation with schema coverage and annotations, the description covers the action and its effect. It is slightly light on what happens to invalid or non-terminal tasks, but the tool is simple enough that this is not a major gap.

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

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

The input schema documents that 'tasks' are database IDs, not UUIDs, so format is covered. The description adds the missing semantic filter: the IDs should correspond to finished or failed tasks, which an agent would not know from the schema alone.

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

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

Description uses a specific verb ('Mark') and resource ('tasks'), identifies the state transition ('as acknowledged'), and states the observable outcome ('stop showing in UI'). This distinguishes it from sibling task tools like get_active_tasks, list_tasks, and get_task, which are read-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?

It specifies the conditions for use: only 'finished or failed tasks' should be acknowledged, and the goal is to remove them from the UI. It doesn't explicitly mention when not to use or name alternative tools, but no sibling offers acknowledgment, so the context is sufficiently clear.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds useful behavior beyond that: the archive is written to a download directory and the response is the archive path, not file contents. This gives the agent a clear model of what happens when invoked.

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, tightly scoped, and front-loads the core action and key behavioral detail. Every sentence earns its place with 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?

For a moderate-complexity tool with five parameters and no output schema, the description covers the key behavioral contract: archive creation, destination, and return type. It does not detail all parameter interactions, but those are sufficiently documented in the schema, and annotations cover safety and idempotency.

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%, with descriptions for content, filename, and follow_formatting; documents and compression rely on their names/enum values. The description itself adds no parameter-level detail, but the schema carries most of the needed meaning for those 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: downloading several documents as one zip archive, written to the download directory. It also clarifies the return value is the archive path, not contents. This clearly distinguishes it from siblings like download_document or bulk_edit_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?

The description gives clear context for when to use the tool: when downloading several documents as a single archive. It does not explicitly mention alternatives or exclusions, such as using download_document for a single file, but the bulk scope is clear from both title and description.

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 tool destructive and non-read-only, but the description adds valuable detail beyond that: it names exactly which methods are destructive and states the confirmation requirement. It also adds a performance trait ('far cheaper') and explains the tag-list behavior. No contradiction with the annotations.

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

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

The description is compact: two sentences deliver purpose, benefit, full method inventory, and the safety rule. The method list is long but scannable and does not repeat parameter details. It overlaps the schema enum slightly, but the overlap helps an agent scan capabilities without opening 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?

Given 18 parameters, a nested set_permissions object, and no output schema, the description plus the rich schema is mostly sufficient for correct invocation. It covers all methods and the destructive-confirmation workflow. The remaining gap is that it does not state return behavior or whether the operation completes synchronously, which would matter for a bulk mutation tool.

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

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

Schema description coverage is 94% and each parameter already carries a 'For <method>' note, so the schema does the heavy lifting. The description adds little parameter-level meaning beyond mentioning delete_originals in the destructive list, which is already documented in the schema. The baseline 3 is therefore 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 opens with a precise action ('Apply one operation to many documents at once') and a clear resource, then lists every supported operation. It also distinguishes the tool from looping update_document and calls out the unique tag-add/remove capability, so an agent can tell it apart from sibling tools.

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

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

It explicitly says to prefer this over looping update_document for cost reasons and identifies the tag add/remove case as the only way to avoid replacing the whole tag list. It also states that destructive methods require explicit user confirmation. However, it does not disambiguate against overlapping dedicated siblings such as delete_documents, merge_documents, rotate_documents, or edit_pdf.

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 destructiveHint annotation already flags that this is destructive; the description adds operational value by specifying that deletion is permanent and instructing the agent to confirm with the user before calling. This is important behavioral context beyond the annotation. It does not elaborate on set_permissions overwrite behavior, but the schema already describes that.

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

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

Two tight sentences: the first states the operation and scope, the second delivers a critical safety warning. No wasted words, and the most important action verbs are front-loaded.

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

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

For a complex bulk operation with six parameters, a nested permissions object, and no output schema, the description is minimal. The safety warning is excellent, and the schema covers parameter details, but the description lacks guidance about alternatives, prerequisites, or the response after deletion. It is adequate but leaves routing and edge-case decisions to the 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?

The description clarifies the meaning of the operation and object_type enums ('Delete or set permissions' and listing the object types), and adds the semantic that deletion is permanent. However, schema description coverage is only 50%, and the description does not compensate for undocumented parameters like owner or the full structure of permissions, though the schema's permissions field already carries some weight.

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

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

The description names specific verbs ('Delete or set permissions') and specific resources ('tags, correspondents, document types or storage paths'). The phrase 'many ... at once' clearly separates this bulk tool from the singular per-object sibling tools like update_tag or delete_correspondent, so an agent can identify what it does without opening the schema.

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

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

The description implies usage for bulk edits by saying 'many ... at once', and the permanence warning gives an important conditional caution. However, it does not explicitly state when to choose this over individual update/delete tools, nor does it name 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 convey that this is a non-read-only, non-idempotent, non-destructive create operation. The description adds the practical risk of near-duplicates being hard to merge, which is helpful operational context, but it does not disclose error behavior, permission side effects, or return values. This is a fair extension of the annotations rather than a contradiction.

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

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

The description is two sentences with no filler. The first sentence states the core action minimally, and the second provides a high-value operational warning 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?

Given six parameters, nested permission objects, and no output schema, the description plus the richly documented schema is sufficient for correct invocation. The duplicate warning is important. It would be a 5 if it also described the returned object or duplicate-name error behavior.

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 parameters like match, owner, is_insensitive, set_permissions, and matching_algorithm. The description adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description states a clear action and resource: 'Create a new correspondent.' It also positions the tool against its sibling CRUD operations by instructing the agent to check list_correspondents first, making the creation entry point unmistakable.

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 tells the agent to run list_correspondents before creating and explains why: 'near-duplicate entries are hard to merge later.' This is useful when-to-use guidance, though it stops short of explicitly saying to use update_correspondent when a matching entry already exists.

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 valuable non-recoverable behavior: the data type cannot change after creation, which is not encoded in annotations or schema. Since annotations already signal that this is a mutating, non-idempotent operation, the extra permanence warning is strong added 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 two short sentences with no filler; the core action comes first and the critical design constraint follows immediately. Every sentence earns its place.

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

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

Given the annotations and a schema that lists required parameters and extra_data examples, the description is nearly sufficient. It covers the one non-obvious constraint (type immutability), though it omits details such as return value and duplicate-name behavior, which are not critical 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?

With 67% schema coverage, the schema already explains data_type and extra_data, including select/monetary requirements. The description adds meaningful semantics for data_type (immutability), but it does not explain the 'name' parameter or add details that the schema lacks for the remaining fields.

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

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

The description uses a specific verb-resource pairing ('Define a new custom field') and the word 'new' clearly distinguishes this creation action from sibling update_custom_field, get_custom_field, and delete_custom_field. There is no ambiguity about what the tool does.

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

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

Usage timing is implied by 'new' and the permanence warning suggests using this tool only when a custom field with a deliberate type is needed. However, it does not explicitly name alternatives like update_custom_field or say when not to use it, so the guidance is only 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?

Annotations already indicate this is a mutating, non-idempotent operation, and the description does not contradict them or add significant behavioral details beyond 'attach.' It explains the purpose of the note but does not disclose, for example, whether repeated calls create multiple notes or how the note relates to the document record.

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-load the action and resource, then immediately provide the intended use case with concrete examples. Every word earns its place with 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 two-parameter create operation with clear annotations and simple schema constraints, the description covers the essential context: what the tool does, when to use it, and what kind of content belongs in the note. No output schema is needed because the effect is straightforward.

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%, but the description compensates by establishing that 'note' is free-text and the target is a 'document,' which makes the role of the 'id' parameter clear. No ambiguity remains about what the two parameters mean, even though the description does not restate schema constraints.

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 ('Attach') and resource ('document'), and clearly defines the output as a free-text note. It also distinguishes this tool from siblings like delete_document_note and list_document_notes by emphasizing its purpose of storing context alongside the document.

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

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

The description gives clear usage context: 'record context that belongs with the document rather than in the conversation' with concrete examples. It does not explicitly name alternatives or exclusions, but the distinction between document-bound notes and conversational context is clear enough for selection among siblings.

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

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

Annotations already indicate a non-readonly, non-idempotent write operation. The description adds a valuable behavioral warning about the long-term consequence of creating near-duplicates (hard to merge), which is not available from the annotations alone.

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

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

Two short sentences with no wasted words. The core purpose is front-loaded in the first sentence, and the second sentence provides directly actionable guidance.

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

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

For a create operation with a fully described schema, the description covers the essential call-gating behavior (check for existing entries). It does not mention the return value or permission requirements, but those are less critical given the annotations and schema richness.

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

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

Schema description coverage is 100%, and the schema already explains each parameter, including defaults and matching algorithm behavior. The tool description adds no parameter-level meaning, so the baseline of 3 is appropriate.

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

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

Uses a specific verb and resource ('Create a new document type') that clearly distinguishes it from sibling update/list/delete operations. The added warning about near-duplicates reinforces that this is a creation action, not a lookup or modification.

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 context: check list_document_types first, and warns that near-duplicate entries are hard to merge later. This effectively tells an agent when to pause before creating, though it does not explicitly name alternatives like update_document_type for modifications.

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

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

Annotations already cover the read/write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds useful behavioral context: the saved view appears in the user's sidebar and filter_rules rely on numeric web UI rule types. It does not mention duplicate-name behavior or the return payload, but it adds enough context beyond the annotations.

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

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

Two sentences, no filler. The first states the tool's purpose; the second flags the key gotcha and points to get_saved_view. Strong front-loading and every sentence carries weight.

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 create tool with seven parameters and no output schema, the description covers the one genuinely tricky aspect (filter_rules) and explains the expected user-visible effect (appears in sidebar). It does not describe the return value or repeated-call behavior, but those are unlikely to block correct invocation. It is sufficiently complete for selection and basic use.

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 14%, so the description must compensate. It does meaningfully explain the most complex parameter, filter_rules, with the advice to copy an existing view's shape from get_saved_view instead of guessing. However, other parameters like page_size, sort_field, sort_reverse, show_in_sidebar, and show_on_dashboard are left entirely to the schema/type/name, so compensation is only partial.

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: 'Save a filter preset that shows up in the user's Paperless sidebar.' This clearly indicates the tool creates a user-facing saved view. However, it does not explicitly contrast with update_saved_view or list_saved_views, and the verb 'Save' could ambiguously imply either create or update without the tool name carrying that weight.

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

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

The description gives concrete, actionable guidance: 'copy the shape from an existing view via get_saved_view rather than guessing.' This tells the agent exactly how to obtain valid filter_rules and identifies get_saved_view as the source. It does not, however, state when to use this tool versus update_saved_view or other siblings, so exclusions are 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?

The description meaningfully extends the annotations by disclosing that the link is public, unauthenticated, readable by anyone holding it, and temporary unless expiration is null. This is valuable context beyond readOnlyHint/idempotentHint and is consistent with annotations; no contradiction exists.

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

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

Three concise, well-organized sentences. The primary action is front-loaded, followed by security/access implications and then user-facing usage requirements. Every sentence earns its place with no redundant 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?

For a low-complexity creation tool, the description covers the essential behavior, access model, and user-consent requirement. However, with no output schema, it doesn't explicitly state what the tool returns, such as the generated URL, which would be useful for an agent handling the response.

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%, and the description doesn't compensate. It clarifies expiation behavior broadly, but doesn't add meaning for the required 'document' parameter or 'file_version'. The schema already documents expiration, so the description adds little beyond what structured data 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 clearly states the action: creating a public, unauthenticated URL for a document, and explains its core behavior. It doesn't explicitly distinguish itself from the sibling create_share_link_bundle, but the singular 'document' focus and access semantics make the purpose clear.

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

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

It provides concrete operational guidance: always confirm with the user first and set an expiration unless a permanent link is explicitly requested. It doesn't explicitly name alternatives or when-not-to-use this tool vs create_share_link_bundle, but the usage context is sufficiently clear.

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

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

Beyond the annotations, the description discloses the critical security behavior: the link is publicly reachable without authentication. It also advises confirming before creation and preferring a finite expiration, which is valuable operational context. 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 no filler: the action is front-loaded, and the security warning and usage preference follow immediately. 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 creation tool with no output schema, the description covers the essential purpose and the main operational risk. The file_version parameter is left to the schema's enum, and the response format is only implied, so it is not a full 5.

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

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

Schema description coverage is only 33%, so the description needs to compensate for undocumented parameters. It only loosely references document_ids ('several documents') and expiration_days ('finite expiration'), and it says nothing about file_version or null expiration semantics.

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

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

The description uses a specific verb ('Publish') and a specific resource ('several documents behind one public link'), which clearly identifies the bundle operation. This distinguishes it from single-link tools like create_share_link and matches the tool 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?

It clearly states the use case: publishing multiple documents behind one public link. It does not explicitly say when not to use this tool or point to a single-document alternative, so it falls just short of a 5.

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

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

Annotations indicate this is a write operation with open-world semantics, and the description adds a useful behavioral warning about near-duplicate merging difficulty. However, it does not disclose return behavior, permission requirements, 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?

Two concise sentences with no filler. The primary action is front-loaded, and the caveat about checking list_storage_paths earns its place by preventing a costly mistake.

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 create operation with no output schema, the description would benefit from stating what the tool returns (e.g., the created storage path object). The pre-check guidance and schema coverage make it minimally viable, but the missing return-value information leaves a gap for agents that need to chain 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 input schema has 100% parameter description coverage, so the schema already documents all parameters. The description adds no new parameter-level meaning beyond the general duplicate warning, which is acceptable but not exceptional.

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 ('Create') and resource ('storage path'), and the phrase 'new storage path' distinguishes it from sibling operations like update_storage_path, delete_storage_path, and list_storage_paths. No ambiguity about what the tool does.

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

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

The description explicitly tells the agent to check list_storage_paths first and explains why ('near-duplicate entries are hard to merge later'). This provides clear usage context, though it does not explicitly state when not to use this tool or name alternative create 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 mark this as non-read-only and non-destructive, so the bar is lower. The description adds valuable context that near-duplicate entries are hard to merge later, which is a non-obvious consequence not present in the schema. It does not cover permissions or return behavior, but the annotation coverage lessens that burden.

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 tight sentences with the core action front-loaded and a single high-value caveat following. No wasted words or redundant schema repetition.

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

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

Given the rich 100%-covered schema and annotations, the description covers the key operational warning that is otherwise undiscoverable. The lack of output schema is not critical for a create operation, and the parameter semantics are fully handled elsewhere.

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

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

Schema description coverage is 100%, so every parameter already has a meaningful description. The tool description adds no parameter-specific detail, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Create a new tag', which states a specific verb and resource and is immediately distinct from sibling tools like list_tags, update_tag, and delete_tag. The purpose is unambiguous and requires no inference.

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

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

It gives an explicit precondition: 'Check list_tags first', and explains why via the near-duplicate merge warning. This effectively tells the agent to avoid creating redundant tags, though it does not explicitly enumerate alternatives or exclusion conditions.

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

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

This goes well beyond annotations by disclosing that workflows run automatically against future documents and that a mistake can silently mis-file everything afterward. That is behavioral context an agent cannot infer from readOnlyHint or destructiveHint alone, and it appropriately raises the caution level for this mutation tool.

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

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

The description is long but packed with necessary detail for two complex nested objects. It is front-loaded with the most important warning before diving into field semantics. Some content duplicates the input schema descriptions, and the '5=..., 6=...' placeholders are weak, but overall the length is justified.

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 of trigger/action configuration and the lack of an output schema, the description covers the critical invocation concerns: what to build, how to model it, and what risks to consider. It does not describe the return value or what happens after successful creation, which is a minor gap for a create operation.

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

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

The description substantially compensates for incomplete schema coverage by enumerating trigger types, source filters, schedule fields, action types, and action-specific assignment/removal fields. It loses one point because action types 5 and 6 are left as '...' and a few fields like matching_algorithm are named but 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 opens with a clear verb and resource: 'Create an automation rule.' It clearly identifies the workflow domain and is distinguishable from sibling tools like update_workflow, delete_workflow, and get_workflow. The mention of reading get_workflow to copy the shape reinforces what this tool is for.

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 strong usage guidance: workflows act on future documents, mistakes are high-stakes because they silently mis-file, and the user should confirm the rule before creation. It also points to get_workflow as a way to model the correct shape, which is an explicit alternative/helper strategy.

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 mark this as destructive, but the description adds important behavioral detail beyond that: the deletion is permanent, documents retain their data but lose the correspondent assignment, the assignment cannot be restored, and user confirmation is required. This fully discloses the key side effects and irreversibility.

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 three short sentences with no filler. It front-loads the primary action, then immediately states the most important side effect and the user-confirmation requirement. 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 one-parameter destructive tool with no output schema, the description covers the essentials: permanence, non-deletion of documents, irreversible loss of assignment, and user confirmation. Nothing critical is missing for an agent to understand what invoking this tool will do.

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 has one required 'id' parameter with 0% description coverage, and the description does not explicitly explain what this id identifies or how to obtain it. The parameter's role is inferable from the tool name and the sentence 'delete a correspondent,' but the description itself adds no direct parameter-level meaning. Low schema coverage required more compensation than this.

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

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

The description clearly states the action and resource: 'Permanently delete a correspondent.' It also differentiates from deleting documents by explicitly saying documents are not deleted, only the assignment is lost. This is a specific verb-plus-resource statement with no ambiguity.

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

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

The description provides clear context for when to use the tool: when a correspondent should be permanently deleted. It also gives an explicit precondition by instructing to confirm with the user first. It does not name alternative tools such as update_correspondent, but the side-effect warning helps distinguish it from document 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 mark destructiveHint as true, but the description goes beyond that by specifying the cascading effect across all documents and the irreversible nature of the operation. This is exactly the behavioral context an agent needs before invoking a destructive tool.

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

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

Two sentences, no filler. The action and scope are front-loaded, followed by a concise safety warning. 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 one-parameter destructive tool with no output schema, the description captures the core behavior, scope, irreversibility, and a precondition ('check document_count first'). It could slightly improve by clarifying where document_count is obtained, but it is otherwise complete enough for safe invocation.

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

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

The schema has a single required 'id' integer parameter with no schema description, so coverage is 0%. The description does not explicitly state that 'id' identifies the custom field to delete, but with only one parameter and the action phrase 'a custom field definition,' the parameter's role is reasonably inferable. Still, the description could have compensated more directly.

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 ('Delete') and a specific resource ('a custom field definition') and adds the critical scope: 'every value stored in it, across all documents.' This clearly distinguishes it from create_custom_field, update_custom_field, and get_custom_field, and matches the tool's 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?

The description gives clear operational context by warning that the action cannot be undone and instructing the agent to confirm with the user and check document_count first. It does not explicitly name an alternative like update_custom_field for non-destructive changes, so it stops short of an exhaustive when-to-use vs when-not-to-use guide.

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

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

Annotations already flag this as destructive, but the description adds important behavioral context: deletion is reversible via trash, recovery is time-limited, and user confirmation is required. This is exactly the kind of nuance that annotations alone do not provide.

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

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

The description is three short sentences with no filler. The main action is front-loaded, the recovery behavior follows naturally, and the safety instruction earns its place. Every sentence adds 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 single-parameter destructive action, the description covers the operation, recovery semantics, retention caveat, and a usage rule. There is no output schema to explain, and the annotation set carries the destructive flag, so 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?

The schema has one required `id` parameter with 0% description coverage, so the description carries the burden of explaining the parameter. 'Move a document' implies the id refers to the document to trash, but the description never explicitly states that `id` identifies the target document. For a single obvious integer parameter this is acceptable but still indirect.

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 ('Move to trash') and resource ('a document'), making it immediately clear this is a soft-delete operation rather than a permanent destructive delete. It also distinguishes itself from trash-related siblings like empty_trash by clarifying recovery behavior.

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

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

The description gives clear usage context: the document stays recoverable until the trash is emptied or a retention period expires, and it mandates user confirmation. It does not explicitly compare to alternatives like delete_documents or restore_from_trash, but the soft-delete framing is sufficient guidance for most cases.

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

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

Annotations already mark this as destructive, and the description adds 'Not recoverable,' which is a useful permanence warning beyond the annotation. This gives an agent important behavioral context about irreversible side 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?

Two short sentences that front-load the primary action and then add a critical safety warning. No unnecessary words or repetitive 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 simple, two-parameter destructive operation, the description plus annotations cover the essentatial safety and irreversibility aspects. While it omits return value details, it is still sufficiently complete for correct invocation in most cases.

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

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

Schema description coverage is 0%, and the description provides no parameter details. The property names id and note_id are somewhat self-explanatory, but the description fails to clarify which id refers to the document vs. note, leaving some 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 states a specific action ('Remove a note from a document') and resource, making its purpose immediately clear. It also distinguishes itself from sibling tools like delete_document and create_document_note by focusing on note deletion specifically.

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 use this tool instead of alternatives such as delete_document or list_document_note s. The context implies the intended use, but the description does not explicitly state exclusions or 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, but the description adds crucial context: the action is recoverable until trash is emptied, and it requires user confirmation. It also clarifies the batch scope. This goes beyond the structured 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?

Three short sentences: action+scope, recoverability, and the confirmation requirement. Every sentence earns its place and critical safety info is front-loaded in the first sentence.

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

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

For a batch destructive tool with one well-schematized parameter, the description fully covers what an agent needs: what will happen, recoverability, confirmation requirement, and the explicit-list constraint. No output schema is present, but return-value details aren't critical for correct invocation.

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

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

Schema coverage is 100% and the single parameter is well documented in the schema. The description reinforces the explicit-list nature with 'several documents' and aligns with 'always an explicit list'. Slight deduction because it doesn't add additional format details, but the schema already carries the load.

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

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

The description states a specific verb ('Move'), a precise resource ('documents'), and the action's effect ('to the trash at once'). It distinguishes from the sibling 'delete_document' by signaling batch operation ('several documents'), and from 'empty_trash'/'restore_from_trash' by explicitly framing trash as recoverable.

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

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

Explicitly instructs that explicit user confirmation is required and that the tool must not be invoked without first listing what will be deleted. This provides a clear when-to-use and a safety gate, which is especially important given the destructive annotation.

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 destructiveHint=true and readOnlyHint=false, and the description adds important behavioral nuance beyond that: the deletion is permanent, documents retain existence but lose the assignment, the assignment cannot be restored, and user confirmation is required. This is exactly the kind of consequence disclosure that helps an agent safely invoke a destructive 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?

Two short sentences carry the essential information: what the operation does, its permanence, its side effect on documents, and the confirmation requirement. There is no filler or redundant restating of the title.

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

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

For a simple delete operation with a single parameter, no output schema, and no nested objects, the description covers the critical operational facts: permanence, irreversibility, side effects on associated documents, and user confirmation. Nothing needed to safely invoke this tool is missing.

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

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

Schema description coverage is 0% and the description does not explain the 'id' parameter or map it explicitly to the document type being deleted. The parameter name and tool context make it inferable, but the description does not compensate for the lack of schema documentation as required by the rubric.

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

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

The description uses a specific verb and resource: 'Permanently delete a document type.' It also distinguishes itself from document deletion by stating 'Documents are not deleted, but they lose this assignment,' which is especially helpful given sibling tools like delete_documents and 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 description clearly implies when to use the tool: when a document type should be permanently removed. It adds a strong usage requirement by saying 'Confirm with the user first,' and clarifies that the deletion does not remove documents. It does not explicitly name alternative tools or when not to use it, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds one useful behavioral detail beyond annotations: deleting a saved view does not affect documents. However, it does not explain what happens if the id does not exist or whether the deletion is reversible, though those are partially covered by the annotations.

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

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

Two short sentences, front-loaded with the core action and then a useful caveat. Every word earns its place, with no redundant or filler 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 simple one-parameter destructive operation, the description covers the key purpose and the most relevant side-effect boundary (documents unaffected). The annotations cover idempotency and destructiveness. Missing details like return values or error behavior would be nice, but they are not critical given the simplicity and the existing annotations.

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

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

Schema description coverage is 0% and the only parameter 'id' has no description in the schema. The tool name and description make it reasonably clear that 'id' represents the saved view to remove, but the description does not explicitly state this or add any format/precondition details beyond the schema. The parameter is simple enough that this is adequate but not exemplary.

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

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

The description clearly states a specific action ('Remove a saved view') on a specific resource, and the added sentence 'Documents are unaffected' disambiguates it from other destructive tools like delete_document. This makes the tool's scope immediately obvious even among many sibling delete operations.

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

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

The description implies the tool is for deleting saved views but gives no explicit guidance on when to choose it over alternatives such as update_saved_view or get_saved_view, and no prerequisites or ownership conditions are mentioned. The distinction from document deletion is helpful but not a full usage guideline.

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 the description adds meaningful behavior beyond that: the revocation is immediate, holders lose access at once, and the document itself is unaffected. This gives the agent a clear safety-relevant mental model of the operation's side 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?

Two short sentences convey the core action and its key side effects with no redundancy. The most important information is front-loaded in the first phrase.

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 destructive action with annotations already covering the read/write and destructive nature, the description provides enough context about the immediate effect and non-effect on the document. It stops just short of being fully complete by not naming the sibling alternative for bundle revocation, but 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?

With 0% schema description coverage, the description should clarify the parameter, but it does not explicitly explain that id is the identifier of the share link to revoke. That inference is easy from the tool name and action, and the single integer parameter is simple, so the gap is moderate rather than severe.

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 ('Revoke a share link immediately'), the resource (a share link), and the immediate effect on holders of the URL. It also distinguishes itself from document deletion by explicitly noting 'the document itself is untouched.'

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

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

The description conveys that this tool is for immediate revocation of a single share link, which implies its use case. However, it does not explicitly mention when to use this tool instead of the closely related sibling delete_share_link_bundle, leaving some selection 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 establish destructive, non-readOnly, non-idempotent behavior, and the description adds valuable specificity: revocation is immediate, it affects every document in the bundle, and the documents themselves are untouched. This clarifies exactly what is destroyed beyond what the annotations convey, and does not contradict 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?

Two sentences with no filler; the action and immediate effect are front-loaded, and the 'documents themselves are untouched' clause earns its place by preventing a common confusion with document deletion.

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 destructive tool with strong annotations, the description is almost complete: it states the scope and limits of destruction clearly. The only meaningful gap is that it does not define or point to how the required id is obtained, which would make invocation fully self-contained.

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

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

Schema description coverage is 0%, and the description does not explain the meaning of the id parameter beyond the tool's name. It neither states that id is the share link bundle's identifier nor says how to obtain it, so it fails to compensate for the missing schema documentation.

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

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

The description uses a specific verb ('Revoke') and resource ('share link bundle'), and immediately clarifies the consequence: every document in the bundle stops being publicly reachable. This clearly differentiates it from sibling tools like delete_share_link and delete_document, which affect different objects.

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—whenever a share link bundle needs to be revoked—and states the immediate effect. However, it gives no explicit when-not-to-use guidance and does not mention alternatives such as delete_share_link for revoking a single link.

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?

Even though annotations already mark this as destructive, the description adds important context: documents are not deleted, the assignment is lost, and it cannot be restored. This goes beyond the annotation and helps the agent anticipate side effects and irreversibility.

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 carry the core action, side-effect warning, and a usage instruction. There is no filler, and the most important information is front-loaded.

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

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

For a simple one-parameter destructive tool, the description is largely complete: it explains permanence, non-deletion of documents, and requires user confirmation. The main gap is the lack of parameter clarification, but annotations and schema cover the rest of the operational context.

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

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

The schema has a single id parameter with no description, and the tool description does not mention id at all. With 0% schema coverage, the description should compensate by indicating which identifier is needed, but it does 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 clearly states the action ('Permanently delete') and the resource ('storage path'). It explicitly notes that documents are not deleted, only lose this assignment, which distinguishes it from sibling delete_document and other delete_* 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 instruction to 'Confirm with the user first' provides some usage guidance, but there is no explicit when-to-use versus alternatives or conditions that would make this tool inappropriate. The usage is mostly implied by the tool name and description.

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

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

Beyond the annotations, the description discloses important behavioral consequences: documents lose the tag assignment, the deletion cannot be restored, and user confirmation is required. This goes well beyond the bare destructiveHint and provides exactly the kind of context an agent needs before invoking a 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 concise, with no wasted words. The primary purpose is front-loaded, followed by the two most important caveats: documents lose the assignment and the action cannot be undone.

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 destructive tool with no output schema, the description covers all essential context: what is deleted, what happens to associated documents, irreversibility, and confirmation requirement. Nothing crucial 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?

The input schema has 0% description coverage for its only parameter, and the description does not explain that the required 'id' refers to the tag being deleted. While the parameter name is somewhat self-evident, the description provides no explicit mapping or additional meaning, so it fails to compensate for the low schema coverage.

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

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

The description states a specific action ('Permanently delete a tag') and clearly distinguishes the resource from siblings like update_tag or create_tag. It also clarifies the scope by explaining that documents themselves are not deleted, which differentiates it from delete_document.

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

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

The description gives clear context: use this when permanently removing a tag, and it emphasizes irreversibility and the need to confirm with the user first. It does not explicitly name alternative tools or exclusions, but the destructive purpose is unmistakable.

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 tool as destructive (destructiveHint=true) and non-idempotent, but the description adds the crucial behavioral detail 'permanently,' indicating irreversibility. It also hints at a safer alternative, which is valuable context beyond the structured hints.

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

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

Two short, purposeful sentences with no filler. The primary action is front-loaded and the alternative guidance is concise, making the description easy to parse and act on.

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 delete operation, the description covers the essential points: what it deletes, permanence, and a safer alternative. With no output schema, return behavior isn't specified, but this is a minor omission for a delete action and the description remains functional.

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%, so the description carries the burden of explaining the 'id' parameter. It does clarify that 'id' refers to an automation rule/workflow, but it adds no further detail about types, meaning, or requirements beyond what the schema already defines. The compensation is partial.

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

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

Description states a specific verb ('Delete'), resource ('automation rule'), and a defining qualifier ('permanently'). It clearly distinguishes from siblings like update_workflow by naming the alternative, so there is no ambiguity about what the tool does.

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

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

The description explicitly names the alternative tool (update_workflow with enabled:false) and advises considering it instead. While it doesn't spell out exact conditions for when each is appropriate, the word 'instead' implies the choice between soft-disabling and permanent deletion, giving useful 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?

Description adds meaningful behavior beyond annotations: files are written to PAPERLESS_DOWNLOAD_DIR (default temp), and the bytes are intentionally not returned to avoid context exhaustion. This is highly relevant for an agent deciding whether to call this tool and what to expect. No contradiction with readOnly/idempotent/destructive hints.

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

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

Three sentences, each earning its place: the action and return value, the disk location, and the reason for not inlining bytes. No fluff or repetition.

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

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

Despite no output schema, the description states the return value (path), the side-effect location, and the rationale for not returning content. Together with annotations it covers safety, idempotency, and operational expectations. This is complete for a simple download operation.

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

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

Schema coverage is 67%, and version and filename already have descriptions in the schema. The description adds little param-specific meaning beyond implying that 'id' identifies the document to save. id's semantics are fairly obvious from the tool name, but the description does not explicitly connect it to the document.

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

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

The description states a specific action — 'Save a document's file to disk' — and identifies the resource and output shape ('return the path'). It clearly distinguishes itself from content-returning siblings by noting the bytes are deliberately not returned inline.

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

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

The description makes the intended use clear: use this when you need the document saved to disk on the MCP server machine and want the path back. It explains why it avoids returning base64 inline, but does not explicitly name sibling alternatives such as get_document_content or bulk_download_documents. This is clear context without 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 establish destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful context by clarifying that it generates a new document and that the operations shape is non-trivial, but it does not explain side effects of delete_original or what happens on partial 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?

The description is compact and front-loaded: it opens with the action verbs, explains the core parameter, and closes with a necessary caution to consult the API docs for the exact operation shape. Every sentence earns its place.

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

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

The description gives enough high-level context for selecting the tool and understanding its purpose, and the schema documents most parameters. However, with no output schema and a complex `operations` parameter, the definition delegates critical invocation details to external docs and does not describe the return value or error behavior.

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 80%, so most parameters are already documented. The description adds meaningful semantics for the under-documented `operations` parameter, calling it 'a list of page instructions' where 'each entry names a source page and what to do with it,' which materially improves the agent's understanding beyond the generic schema object.

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 set of actions ('Reorder, rotate, remove or split out pages') on a specific resource ('a single document') and clarifies the output ('producing a new document'). This clearly distinguishes it from siblings like rotate_documents or merge_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?

The description establishes the scope ('single document') and that this produces a new document, which implies when it might not be appropriate, but it never names alternatives or gives explicit when-to-use/not-to-use guidance. The instruction to consult the Paperless API docs is a usage caution, not a comparison to sibling tools.

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

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

Annotations already mark the operation as open-world, non-read-only, and non-idempotent. The description adds meaningful behavioral context by stating 'This sends real mail to real people,' which emphasizes the real-world side effect and justifies the confirmation requirement. This goes beyond the annotation flags and is valuable for an agent deciding whether to call the 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?

The description is two sentences with no filler. The core action is front-loaded in the first sentence, and the critical safety warning is placed immediately in the second. Every phrase 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 side-effecting email tool, the description covers the essential purpose, the real-world impact, and the key user-confirmation precondition. The absence of an output schema is acceptable because the tool's observable effect is the email itself. A minor gap is that the confirmation precondition lists recipients, subject, and body but omits explicit mention of confirming the documents to be sent.

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 40%, with `documents`, `subject`, and `message` lacking descriptions, but the tool description partially compensates by referencing 'one or more documents' and 'recipients, subject and body.' These phrases map to the main parameters and clarify their roles. However, `use_archive_version` is not explained anywhere, and no additional format or constraint details are added 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 opens with a specific verb and resource: 'Send one or more documents by email from the Paperless instance.' This clearly identifies both the action and the object. It also distinguishes the tool from sibling document operations by emphasizing actual email delivery, and there is no other email-sending sibling that could be confused with it.

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 a clear precondition: 'only call it after the user has confirmed the recipients, subject and body.' This tells the agent when it is appropriate to invoke the tool and explicitly warns against calling without user confirmation. It does not mention alternatives such as share links or bulk downloads, so it stops short of a full when/alternatives comparison.

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 meaningful behavioral context: there is no recovery, files are gone, and explicit consent is required. This goes beyond the annotation by warning about irreversibility and the need for prior listing.

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 three sentences with each sentence earning its place: what it does, why it is dangerous, and when it may be called. The warning is front-loaded and no words are wasted.

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

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

For a low-complexity destructive action with one optional parameter and no output schema, the description is complete enough. It covers irreversibility, consent requirements, and the need to inspect trash first. The optional documents parameter semantics are already fully covered by the 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 schema description coverage is 100%, so the schema already documents the documents parameter completely. The tool description does not need to restate the parameter semantics. The baseline of 3 applies because the description adds no further param 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 and resource: 'Permanently destroy trashed documents.' It clearly distinguishes this from other document operations like delete, restore, or list. The title and description align without being tautological.

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

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

The description gives explicit usage conditions: never call without the user explicitly asking in the current conversation, and list what is in the trash first. This is strong guidance for a destructive irreversible action and helps an agent decide whether to proceed.

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 establish read-only, idempotent, non-destructive behavior. The description adds that tasks are those 'executing right now', a useful temporal scoping. However, it leaves the return representation ambiguous (a list of tasks vs. a boolean busy flag), which is a behavioral detail an agent would need.

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 redundancy: the first states what is returned, the second states its operational meaning. Every word earns its place and the key scoping ('executing right now') is front-loaded.

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

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

For a zero-parameter read-only tool with annotations covering safety, the description is mostly sufficient. The meaningful gap is the output shape: are running tasks returned as a list, or is the result a boolean busy indicator? The name and first sentence suggest a list, but 'tells you whether' suggests boolean, leaving an agent to guess.

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

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

The tool has zero parameters and the schema coverage is trivially 100%. There is nothing for the description to add about parameters, so the zero-parameter baseline of 4 applies.

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

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

The description conveys that the tool retrieves tasks currently executing and augments that with a practical purpose ('tells you whether the instance is busy'). It is specific about the resource and state, though it does not explicitly name sibling tools to differentiate from list_tasks or get_task.

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?

'Tells you whether the instance is busy' gives a clear use case: checking if the system is occupied before proceeding. It does not mention alternatives or exclusions, but the context is direct enough for an agent to select it for busy-state checks.

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 disclose that the tool is read-only, idempotent, and non-destructive, so the description does not need to cover safety. The description adds that the response includes all fields of the correspondent, which is useful, but it does not mention what happens if the ID does not exist or how errors are surfaced. For a simple getter with a strong annotation profile, this is acceptable but not 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 one clear sentence with no redundancies or filler. 'Fetch a single correspondent by ID' is front-loaded, and 'with all fields' adds meaningful return-value information. Every part 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 one parameter, no output schema, and no nested objects, the description is mostly complete: it identifies the resource, the lookup key, and the return scope ('all fields'). The only notable omission is behavior for a non-existent ID, such as a 404 vs a null result. Given the low complexity, 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?

The schema has a single required `id` integer with bounds but no property description, and schema description coverage is 0%. The description's 'by ID' matches the parameter name and clarifies that the integer is the correspondent identifier, but it adds no further semantics such as where the ID comes from or what formats are valid. This is the minimum compensation for the missing 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 says 'Fetch a single correspondent by ID, with all fields,' which names a specific verb, a specific resource, and a precise selection criterion. This clearly distinguishes it from list_correspondents, which would return multiple correspondents, and from create/update/delete mutations of correspondents. An agent can confidently tell what this tool does without opening the schema.

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

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

The description implies the use case: when you already have a single correspondent ID and need the full corresponding record. However, it does not explicitly say to prefer this over list_correspondents when only one ID is needed, nor does it describe how to obtain the ID. The guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by specifying that the response includes the definition and any select options, clarifying the return content beyond the annotations.

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

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

The description is a single sentence with no filler or redundant phrasing. It front-loads the key information and every word earns its place.

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

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

For a simple get-by-id operation with rich read-only annotations, the description is adequate. It conveys the return type and a key inclusion (select options), though without an output schema it could elaborate on other fields of the custom field definition.

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%, yet the description does not mention the required 'id' parameter or explain what it identifies. Although the parameter name is self-explanatory, the description fails to compensate for the missing schema documentation.

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

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

The description clearly identifies a single custom field definition as the resource and notes the inclusion of select options, distinguishing it from list_custom_fields. However, it lacks an explicit action verb (e.g., 'Retrieves'), relying on the tool name to convey the 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?

The description gives no explicit when-to-use or alternative guidance. While 'One custom field definition' hints at singular retrieval versus list_custom_fields, it does not state when to choose this tool over siblings or mention prerequisites such as requiring the custom field's id.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds value by specifying the exact metadata payload and the conditional behavior that OCR content is excluded unless include_content is set, which is meaningful context beyond the annotations.

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

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

Two tight sentences with no filler. The core purpose and return fields are front-loaded, and the critical content-exclusion caveat is stated immediately after, making the description economical and easy to scan.

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

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

For a simple single-document fetch with no output schema, the description names the expected output fields and the only important conditional behavior. More detail about the shape of versions or notes would be useful but is not essential for correctly invoking the tool.

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

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

Only 50% of the parameters are described in the schema (id lacks a description), but the description compensates by making 'by ID' explicit and by explaining that include_content controls whether OCR text is returned. The behavior of both parameters is inferable even with the incomplete 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 starts with a specific verb and resource: 'Fetch one document's metadata by ID' and enumerates the returned fields (title, correspondent, type, tags, dates, custom fields, notes, versions). This clearly identifies the tool's scope and distinguishes it from content-focused siblings like get_document_content.

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

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

The description gives clear context: use this to retrieve metadata for one document, with OCR text only when explicitly requested. It doesn't fully articulate when not to use it or name alternatives directly, but the exclusion of OCR content and the pointer in the include_content parameter make the primary use case clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: the tool is tied to a specific version (Paperless-ngx 3.x), depends on server-side AI features, and will return 404/error when disabled. This failure-mode disclosure is valuable and not present in 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, zero waste. The primary behavior is stated first, followed by a critical caveat about expected failure modes. All information is relevant and front-loaded.

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

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

Given one simple parameter, no output schema, and strong annotations covering safety, the description is nearly complete. It covers the feature dependency, version, and expected error behavior. The only gap is that it does not describe the shape of a successful response, but this is minor for such a simple read-only tool.

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

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

Schema description coverage is 0%, but the single parameter 'id' is a standard integer with exclusiveMinimum. The description does not explicitly say id refers to a document ID, though the tool name makes it inferable. The description adds no parameter-level semantics, but the meaning is clear enough given the context, so a 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 title 'Get AI filing suggestions' and description 'Suggestions from the instance's configured LLM backend' clearly state the core function and resource. It differentiates from the sibling get_document_suggestions by the 'AI' and 'LLM backend' qualifiers, 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?

States a clear precondition: 'only if AI features are enabled server-side.' It also gives explicit guidance on the expected 404/error result when AI is disabled, telling the agent this is normal. It does not explicitly mention the sibling get_document_suggestions or say 'use this instead when...', but the conditional context is clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds a meaningful behavioral trait: the high cost/latency of this operation and the need to limit its use. It also discloses the content type (OCR/extracted text) and offline/lim support, which goes beyond the sterile 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?

Three sentences, each earning its place: the first defines the return, the second explains why this tool is separate and when to use it, the third notes pagination. No filler. The most important scoping constraint is front-loaded.

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

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

Given the simplicity of the tool and the strong annotation safety profile, the description is nearly complete. It covers what is returned, the cost warning, and offset/limitt. The absence of an output schema is mitigated by 'OCR/extracted text' clearly indicating a text string. A slight gap is guidance on handling truncated output or iterative fetching, but this is minor.

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

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

The schema already describes limit and offset with default/min/max values. The id parameter is self-evident given 'one document' and is not described in the schema, but the description doesn't need to elaborate. The description's mention of offset/limitt aligns with the schema without adding new semantics. With 67% schema coverage and obvious id, this hits the baseline.

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

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

The description states a specific verb and resource: 'Return the OCR/extracted text of one document.' It also says it is deliberately a separate tool and the most expensive thing to pull, clearly distinguishing it from siblings like get_document, get_document_thumbnail, and download_document. An agent can immediately understand what this tool does and how it differs.

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 an explicit usage rule: fetch this only for documents you have already narrowed down, because it is the most expensive operation. This is a clear when-to-use directive. It also implies when not to use by framing it as a last-step retrieval, though it doesn't name specific alternatvives.

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 establish that the operation is read-only, idempotent, and non-destructive. The description adds genuine behavioral context beyond that: it requires audit logging to be enabled, returns newest entries first, and implies pagination via the limit parameter. 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 two sentences with no filler. It front-loads the core purpose, then states the prerequisite and ordering/limit behavior, all in a compact and readable way.

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

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

For a simple read-only tool with two well-understood parameters and no output schema, the description covers purpose, prerquisitie, result ordering, and limit usage. It is essentially complete for calling the tool correctly, though it omits explicit details about the exact response shape or behavior when audit logging is disabled.

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 only 50% because the id parameter has no description. The description compensates partially by explaining that limit controls how far back the audit trail is viewed, but it adds little about id beyond the term 'document' in the purpose statement. The limit schema already documents the default and max, so the added semantic value is modest.

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

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

The description clearly identifies the tool as an audit trail of document changes, specifying who changed which field and when. This meaningfully distinguishes it from sibling tools like get_document or get_document_metadata, though it does not name alternatives 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?

It implies the intended use case through 'audit trail of changes' and gives a prerequisite: audit logging must be enabled. However, it does not contrast with nearby tools such as get_document_metadata or get_document_content, so an agent gets only indirect guidance for selecting this tool over 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing the scope of the metadata retrieved and clarifying what is excluded, which helps set expectations about the result. It does not describe error conditions or edge cases, but for a read-only metadata getter the added context is strong.

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 first sentence front-loads the concrete metadata fields, and the second immediately provides the exclusion and alternative. 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 single-parameter read-only tool with rich annotations and no output schema, the description sufficiently covers what the tool returns and how it differs from get_document. It lacks explicit return-structure details or parameter clarification, but the enumerated metadata fields largely compensate for the missing output schema. A slightly more complete description would connect 'id' to the document identifier.

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

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

The schema description coverage is 0%, so the description carries the full burden of explaining the 'id' parameter. It never explicitly states that 'id' is the Paperless document ID or how it relates to the document resource. While the tool name and title make this inferable, the description itself adds no direct parameter meaning beyond what the generic 'id' integer property already implies.

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

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

The description opens with a specific verb-resource pair ('Technical file metadata for a document') and enumerates exactly what it returns: checksums, byte sizes, MIME type, stored filename, archived PDF/A presence, and embedded PDF metadata. It actively differentiates itself from get_document by explicitly excluding tags/correspondent, so an agent can disambiguate without inspecting either schema.

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

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

The description names the sibling alternative explicitly: 'Not the Paperless tags/correspondent — use get_document for those.' This states both when not to use the tool and which tool to use instead, giving clear routing guidance with no reliance on inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds useful behavior beyond them: the result is model-dependent and not authoritative, so it must be verified. This is honest about output variability and aligns with the annotations.

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

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

Two sentences deliver the content, purpose, and an important caveat with no filler. The substantive detail comes first and the verification warning follows naturally.

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 read-only tool with one param and strong annotations, the description is largely complete: it names the output categories and reliability caveat. It does not describe the exact response structure, but no output schema exists and the listed suggestion types give enough orientation for 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?

There is one id parameter with zero schema description coverage. Description references 'a document' but never explicitly states that id is the document identifier or how invalid ids behave. The id is simple and self-evident, but the description does not truly compensate for the missing schema property text.

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 identifies a specific verb-resource relationship: it returns Paperless' classifier suggestions for a document, enumerating the fields (correspondents, tags, document types, dates). It is clear, but does not explicitly name the nearby sibling get_document_ai_suggestions, relying on the phrase 'Paperless' own' to imply the distinction.

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

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

It states clear use context: useful as a starting point when triaging. It also tells agent to verify before applying because suggestions depend on model quality. It does not name alternative tools/exclusion conditions, so it misses the full 5.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile. The description adds behavioral context beyond the annotations by specifying that the return is an inline thumbnail image meant to be viewed, which helps the agent anticipate the response format.

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

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

The description is two concise sentences with no filler. The primary action is front-loaded, and the use-case rationale is expressed in one clause.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the main purpose, the return nature, and the practical use case. It does not detail image format or size, but this is not critical given the simple signature and read-only annotations.

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 has 0% description coverage for its single 'id' parameter. The description implies that 'id' refers to the document whose thumbnail is returned, but it does not explicitly document the parameter's meaning or any special formatting. For a single obvious integer id, this is adequate but not exemplary.

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 ('Return the document's thumbnail image inline') and the resource (the document's thumbnail). It conveys the practical purpose of visually confirming a document, which differentiates it from content-retrieval tools, though it does not explicitly name 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 provides clear usage context: use it when you want to see what a document is without reading its OCR text. It does not explicitly list alternatives or exclusions, but the implied when-to-use is strong enough for an agent to select it appropriately among siblings.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds 'with all fields,' indicating the response includes the complete object, but does not disclose behavior for missing/invalid IDs or other edge cases. This is acceptable given the strong annotation coverage.

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 starts with the core action and resource, then adds the scope and return expectation. Every word earns its place, with no filler or repetition.

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

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

For a simple single-ID read operation, the description covers what the tool does, what it returns ('all fields'), and which input identifies the target. Annotations cover safety and idempotency, and no output schema is present, so the description's return note is 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 description coverage is 0%, so the description must compensate. It mentions 'by ID' but does not explain the id parameter's meaning beyond what the schema already states. Since there is only one obviously named parameter, the gap is minor, but the description still adds little semantic 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 action ('Fetch'), the resource ('a single document type'), and the scope ('by ID, with all fields'). This distinguishes it from list_document_types and other singular getters like get_tag or get_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 description implies usage: use this when you have a specific document type ID and need its full record. It does not explicitly contrast with list_document_types or mention when not to use it, but the singular 'by ID' provides adequate implied guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context about being 'one compact snapshot' and cheaper than four calls, but does not disclose additional details such as response size limits or consistency guarantees. This is adequate but not rich.

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

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

The description is two sentences with no filler. The first sentence defines the resource and its contents, and the second sentence provides the use context and cost benefit, making it highly efficient and easy to parse.

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

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

For a parameterless read-only tool with no output schema, the description is complete enough. It tells the agent what data will be returned, when to use it, and why it is preferable to multiple sibling calls, so 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?

The tool has zero parameters, so the empty schema places no burden on the description. The description still adds meaning by enumerating what the returned snapshot covers: tags, correspondents, document types, and storage paths with their IDs and counts.

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 resource as a compact metadata overview aggregating tags, correspondents, document types, and storage paths, including IDs and document counts. It also differentiates this tool from the many sibling list tools by emphasizing it is one combined snapshot rather than four separate calls.

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 this is the 'right first step before filing or triaging documents' and points out it is 'cheaper than four separate list calls,' making the intended context clear. It does not explicitly state when not to use it, but the comparison to separate list calls strongly implies the alternative.

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

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

The annotations already cover the safety profile: readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds the 'next free' semantics and the filing use case, but it does not clarify whether the returned number is reserved or how it should be applied to a document afterward. This is useful context but not rich behavioral disclosure beyond what annotations convey.

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

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

The description is a single well-constructed sentence with no wasted words. The core result is front-loaded, and the intended context is appended 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?

For a zero-parameter, read-only, idempotent helper, the description plus annotations are almost sufficient. The only thing left implicit is the exact output format—likely an integer serial number—but with no output schema and a simple return value, the omission is minor.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds meaning to the empty schema by explaining that the tool returns the next free archive serial number rather than a generic or arbitrary 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 title supplies the verb 'Get' and the description names the specific resource: the next free archive serial number. The appended purpose—'for filing a physical document alongside its scan'—distinguishes this tool from all document-management siblings, none of which claim this responsibility.

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

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

The description explicitly states the intended use case: obtaining a serial number when filing a physical document with its scan. It does not discuss alternatives, but no sibling tool serves this purpose, so the lack of exclusions is not a significant gap.

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 establish this as read-only, idempotent, open-world, and non-destructive. The description adds that the tool reports the latest release and update availability, but it does not disclose whether this involves a network call, how failures are handled, or the exact shape of the response. With strong annotation coverage, this is acceptable but not rich.

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

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

The description is very short and free of filler, but it is a sentence fragment rather than a complete, front-loaded statement of action. It conveys the key information efficiently, though a verb would improve its structural quality.

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

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

For a zero-parameter, read-only tool with strong annotations, the description covers the essential outcome: the latest release and whether an update is available. There is no output schema, so a bit more detail about the return format would be helpful, but an agent can still select and invoke this tool correctly with the information provided.

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

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

The tool has zero parameters, so the schema already covers everything needed for invocation. The description adds semantic context about what the result represents, which is useful, but parameter-related information is inherently complete due to the empty 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 title 'Check for Paperless updates' supplies the missing verb, and the description names the resource: the latest Paperless-ngx release plus update availability. This is distinct enough from siblings like get_server_status or get_statistics, though the description itself is a noun phrase rather than an explicit action statement.

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 title implies the use case: checking for Paperless updates. However, the description gives no explicit when-to-use guidance, no mention of alternatives, and no context about how this relates to other status/statistics tools. The usage context is only implied, not stated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations by revealing the return payload: the saved view includes its filter rules, which is the key behavioral detail for callers.

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-ordered sentence delivers the resource, its key content, and the reason it matters without any filler. Every part of the description 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 getter with strong annotations, the description covers what is returned and why it is useful. It omits edge cases like not-found behavior, but that is minor for a safe, idempotent lookup.

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

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

Schema description coverage is 0%, and the description does not explain the required id parameter at all. The agent must infer from the schema and tool name that id selects which saved view to retrieve.

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?

Clearly identifies the resource as a single saved view and explains the value-add: it includes filter rules so the view can be reproduced as a search. This also differentiates it from list_saved_views, which returns a collection.

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

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

The phrase 'one saved view' and the purpose clause 'so you can reproduce it as a search' give a clear context for when to call this tool. It does not explicitly name alternatives or exclusions, but the intended use is evident.

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 readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds useful semantics about aggregated counting and the one-call efficiency, but does not discuss edge behavior such as missing IDs, duplicate IDs, or how the open-world hint affects result completeness.

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

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

Two concise sentences fully convey the operation and use case with no redundant wording. The core behavior is front-loaded and the explanatory analogy is 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?

Despite lacking an output schema, the description adequately conveys what the result represents: counts of documents per tag, correspondent, type, and storage path. Given the single-parameter surface and rich annotations, this is nearly complete, though exact response structure is left unspecified.

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

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

The input schema provides only the type and constraints for the single `documents` parameter, with no description. The tool description adds that these are document IDs and that they form a selection, which is meaningful but minimal; it does not explain duplicate handling, limits, or invalid-ID behavior.

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: given a set of document IDs, return counts per tag, correspondent, document type, and storage path. The use-case phrasing "what is in this pile?" makes the tool's role immediately clear and distinguishes it from individual document-fetching 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 clearly indicates when to use this tool: when aggregate summaries of a document selection are needed, and contrasts it with fetching every document. It does not name sibling alternatives explicitly, nor note when to avoid it, so it falls just short of full explicit routing guidance.

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

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

Annotations already convey that the tool is read-only, idempotent, open-world, and non-destructive. The description adds value by revealing exactly which subsystems are examined and that the search index freshness is part of the health signal, giving the agent a clearer behavioral picture without contradicting 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, compact sentence that front-loads the key concept ('Instance health') and then lists the covered components efficiently. Every word adds useful information; there is no filler or repetition.

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

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

For a zero-parameter read-only health check, the description is complete: it states the resource, enumerates the checked subsystems, and the annotations cover safety and side-effect expectations. No output schema exists, but the description sufficiently characterizes the status information the tool provides.

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

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

The tool takes zero parameters and the schema has 100% coverage, so there is nothing meaningful for the description to add about parameter usage. The baseline of 4 applies because no parameter ambiguity exists.

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's purpose: assessing instance health and enumerates the specific components covered (Paperless version, database, index, Redis, task workers, search index freshness). This distinguishes it from siblings like get_statistics, get_remote_version, and get_active_tasks.

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 about when to use this tool versus alternatives, such as get_statistics for usage metrics or get_active_tasks for operation status. The intended use as a health check is implied by the description, but no exclusions or sibling routing are provided.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful transparency about cost and purpose: it is 'cheap' and suited for orientation, which is meaningful beyond the annotations.

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

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

Two short sentences deliver the resource, the exact data returned, and the use case with no filler. The core statement is front-loaded.

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

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

For a zero-parameter, read-only statistics tool, the description is complete: it names the output fields and the intended call context. Annotations cover the safety profile, and siblings are unlikely to be confused with it.

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

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

The tool has zero parameters, so there is nothing for the description to clarify. Schema description coverage is 100%, and the baseline for a zero-parameter tool is 4.

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

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

The description states a specific verb and resource ('Totals for the archive') and enumerates exactly what is returned: document count, inbox count, characters, and file type breakdown. This makes the tool clearly distinct from siblings like get_server_status or get_metadata_overview.

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

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

'A cheap orientation call at the start of a session' explicitly tells an agent when to use it. It does not name alternatives or exclusions, but the context is clear enough to make a correct selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe, non-mutating nature is covered. The description adds modest context by saying the response contains 'all fields,' but it does not disclose not-found behavior, error semantics, or authentication requirements. This is acceptable given the simple single-fetch nature but not richly 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 a single front-loaded sentence with no filler. It efficiently conveys the action, resource, selection method, and return scope, earning every word it uses.

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

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

Given the tool's low complexity, one required parameter, rich safety annotations, and no output schema, the description is largely complete for correct invocation. It could optionally mention not-found behavior or explicitly name list_storage_paths as the alternative, but nothing critical is missing for an agent to select and call 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 description coverage is 0%, so the description must compensate. The phrase 'by ID' does clarify that the sole parameter identifies which storage path to fetch, which is meaningful. However, for a single integer 'id' parameter, this is only minimal compensation; the description does not explain expected format, source of the ID, or edge cases.

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 ('Fetch'), identifies the resource ('storage path'), and clearly specifies cardinality ('a single') and selector ('by ID'). This distinguishes it from sibling tools like list_storage_paths, which would retrieve multiple storage paths. 'With all fields' also clarifies the expected response 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 clearly implies the tool should be used when the caller has a specific storage path ID and wants that single object. It does not explicitly mention alternatives such as list_storage_paths for listing, so it lacks an explicit exclusion, but the 'single... by ID' phrasing provides adequate contextual guidance for routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and a non-destructive profile, so this is clearly a safe read operation. The description adds the useful behavioral note that the full tag object is returned ('with all fields'), but it does not describe error cases or response shape. This is adequate but not rich 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, front-loaded sentence with no filler. Every word contributes meaning: fetch, single tag, ID, all fields. It is appropriately minimal for a simple get-by-id 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 single-resource lookup with strong annotations, the description is complete enough: it states the operation, the input, and that all fields are returned. It does not enumerate the tag fields, but the domain context and sibling tools provide adequate grounding, and no complex behavior needs explaining.

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

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

The only parameter, 'id', is self-descriptive and its type and constraints are fully specified in the input schema. The description confirms its role via 'by ID' but adds no additional semantic detail. With one trivial parameter this meets the minimum viable standard, though schema description coverage is technically 0%.

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 ('Fetch'), a specific resource ('a single tag'), and the access mechanism ('by ID'), which clearly distinguishes it from sibling tools like list_tags, update_tag, and delete_tag. The added 'with all fields' further clarifies the expected return scope.

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

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

The phrase 'a single tag by ID' gives a clear context: use this when you have a known tag ID and need that tag's data, not when listing or searching tags. It does not explicitly name alternatives or exclusions, but the usage context is clear enough for this simple operation.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context by stating that the response includes the task result and can be used to verify success, which goes beyond the schema and annotations.

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

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

Two concise sentences front-load the core behavior and then add a practical purpose. Every word earns its place, with no redundant restatement of the tool name or title.

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

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

For a single-parameter, read-only getter with rich annotations, the description covers the identifying information, the result payload, and a practical use case. 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?

The schema provides no parameter descriptions, so the description carries the burden. Saying the tool fetches a task 'by database ID' clarifies that the sole required parameter is the task's database ID, not just any integer.

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 operation: fetching one background task by database ID, including its result. This clearly distinguishes it from list_tasks and get_active_tasks, which retrieve collections of tasks.

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 identifies a concrete use case: checking whether an upload or merge actually succeeded. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for an agent to select it appropriately.

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 establish that this is a safe, read-only, idempotent operation. The description adds that the response contains complete trigger and action definitions, giving the agent useful expectations about payload richness. Error or authentication behavior is not mentioned, but the annotation coverage removes much of the burden.

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 concise sentence with no filler. The core scope and return content are front-loaded, and every word adds 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 simple read-only getter with one id parameter, comprehensive annotations, and no output schema, the description supplies the key expectation: the returned workflow includes full trigger and action definitions. Nothing significant is missing for an agent to call this tool correctly.

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

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

The schema description coverage is 0%, and the description does not explicitly document the id parameter. The single required id is trivially inferable from the tool name and property name, and its constraints are clear, so this is a minor gap rather than a critical one.

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 what is returned: one workflow, and it adds that the response includes full trigger and action definitions. This distinguishes it from list_workflows, which returns multiple workflows, and from the separate trigger/action list 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 singular phrasing implies fetch-by-id, so an agent can infer this is the right tool when a single workflow is needed. However, there is no explicit guidance about when to use this over list_workflows or the standalone trigger/action endpoints, leaving the routing mostly 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?

Annotations already mark it read-only, idempotent, and non-destructive, so the description's job is lighter. It adds a meaningful behavioral cap ('Returns at most three hits per type') and the cross-type scope, which is useful beyond the annotations.

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

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

Three sentences, front-loaded with the core action, and no filler. The long list of object types is necessary for scope, and the final sentence earns its place as a routing cue.

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

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

Given the annotations already cover the safety profile and the schema covers all parameters, the description supplies the key behavioral context: breadth, per-type results cap, and the preferred alternative for document searches. No output schema exists, but the return behavior described is sufficient to select and invoke the tool.

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

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

Schema description coverage is 100%, so the schema already documents both query and db_only. The description does not add parameter-level detail beyond the schema, which puts it at the baseline for covered schemas.

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 action ('Search across every object type at once') and lists the covered object types in detail. It also positions itself relative to search_documents, so an agent can understand its purpose among the large sibling set.

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 a clear when-to-use condition ('when you do not yet know which kind of object you are looking for') and an explicit exclusion ('For document searches, search_documents is better').

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

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

Annotations already cover the read-only, idempotent, open-world, and non-destructive aspects, so the description doesn't need to repeat those. It adds useful behavioral context by defining the domain concept and stating the exact return shape (id, name, document_count). This goes beyond the schema and 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?

Three short sentences each carry distinct value: the action, the domain clarification plus return fields, and the usage guidance. The most important information is front-loaded ('List correspondents'), and there is 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 read-only list endpoint with no required parameters and a fully documented schema, the description is largely complete: it states the purpose, the meaning of a correspondent, the return fields, and when to call it. It doesn't explicitly mention pagination behavior in prose, but the schema already documents page/page_size, and the annotations cover safety, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so the input schema already documents all five parameters, including filters, pagination, ordering, and the full flag. The description adds no parameter-specific meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource pair ('List correspondents') and clarifies exactly what a correspondent is ('the sender or counterparty a document came from'). It also specifies the return fields (id, name, document_count), which makes the tool's purpose and scope unambiguous and distinguishes it from sibling tools like get_correspondent or create_correspondent.

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 situational guidance: 'Call this before creating anything — reusing an existing correspondent is almost always correct.' This tells an agent when to use the tool and effectively steers it away from create_correspondent unless necessary, which is exactly the kind of alternative-routing the dimension asks for.

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 establish read-only, idempotent, non-destructive behavior. The description adds that the response includes IDs, data types, and usage counts, and that IDs are a prerequisite for document field operations. It does not disclose pagination or ordering behavior, but that is minor given the annotations.

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

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

Two sentences with no wasted words. The first sentence states the output and result, the second gives the practical purpose. Information is front-loaded and efficient.

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

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

Covers what the tool returns and why it should be used (to obtain IDs before document field operations). Pagination and filtering are left to the fully documented schema, and while there is no output schema, the description adequately summarizes return content.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already documents.

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 it lists custom fields defined on the instance, with IDs, data types, and usage counts. This clearly differentiates it from singular get_custom_field and management tools like create/update/delete_custom_field.

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

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

Explicitly tells the agent that IDs are required before reading or writing custom field values on a document, which is a clear use case. It does not explicitly name alternatives such as get_custom_field for a single field, so it falls short of full alternative routing.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that notes include authors and timestamps and that they may contain non-OCR context, which is useful, but it does not disclose pagination, ordering, empty-result behavior, or what the returned structure looks like.

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

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

Two concise sentences with no filler: the first states the resource and key output fields, and the second provides genuinely useful context about when the notes matter. The most actionable information is front-loaded.

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

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

For a simple single-parameter, read-only list tool with no output schema, the description covers the core need: what the tool returns (notes with authors/timestamps) and why it is valuable. It does not describe the exact JSON array shape, but the annotations and low complexity make this a moderate rather than critical 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?

With schema description coverage at 0%, the description should clarify the parameter, and it only loosely implies that the single 'id' refers to a document. The phrase 'attached to a document' plus the tool name makes the parameter inferable, but the description does not explicitly say 'the id of the document whose notes should be listed.'

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 identifies the resource as 'notes attached to a document' and indicates the content includes authors and timestamps, so an agent can tell this is a read operation on document notes. However, it relies on the tool name/title for the actual verb 'list' and does not explicitly contrast itself with sibling read tools like get_document_content or search_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?

The description gives clear usage context: 'worth reading before drawing conclusions about a document' because notes contain information the OCR text lacks. It does not name specific alternatives or state when not to use the tool, but it does convey a concrete scenario where this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the document-scoping behavior and positioning as a precondition to creation, but does not disclose pagination, ordering, or partial result behavior. 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?

A single, front-loaded sentence that immediately conveys scope and purpose. The second clause earns its place by giving a concrete usage hint. No filler or redundancy.

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

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

For a simple one-parameter read-only tool, the description plus rich annotations is mostly sufficient. However, it does not differentiate from list_share_links, explain output/return behavior, or clarify parameter meaning, and there is no output schema to fill those 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 0%, so the description must explain the 'id' parameter, but it does not. The tool name and title imply 'id' is a document ID, but the description itself provides no parameter semantics beyond 'one document'.

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 resource ('share links') and scope ('for one document'), and the title provides the verb 'List'. It hints at differentiation from creating a share link, but it never explicitly distinguishes itself from the sibling list_share_links.

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 one clear usage scenario: check before creating another share link. However, it does not mention when to prefer list_share_links over this tool, nor does it state exclusions. The guidance is useful but mostly 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 the read-only, idempotent, non-destructive profile, lowering the bar. The description adds useful behavioral context by defining the return shape (id, name, document_count) and clarifying the domain concept, giving the agent an accurate expectation of what the tool produces beyond what the annotations convey.

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

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

Three short sentences with no wasted words: purpose, domain definition with examples, and actionable usage guidance. The key behavioral and procedural 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 simple read-only list endpoint with zero required parameters and a well-detailed schema, the description covers purpose, output shape, and when to call it. The schema handles pagination, ordering, and filtering details, while annotations cover safety, leaving nothing essential 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?

All five parameters are fully described in the input schema (100% coverage), including the 'full' parameter which mirrors the summary fields mentioned in the description. The description adds no parameter-level information beyond the schema, 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?

States the operation directly with a specific verb and resource ('List document types'), defines what a document type is with concrete examples, and specifies the output fields. It is unambiguous and easily distinguished from sibling tools like get_document_type, create_document_type, update_document_type, and delete_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?

Provides explicit when-to-use guidance: 'Call this before creating anything' and a decision rule that 'reusing an existing document type is almost always correct.' This effectively steers the agent away from create_document_type, though it does not name the alternative tool explicitly.

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