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

Annotations already carry destructiveHint=true and openWorldHint=true; the description adds useful behavioral details beyond the flags: paths are relative to `/api/`, trailing slashes are added automatically, and responses are raw rather than name-resolved. It does not contradict the annotations.

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

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

Four sentences, each earning its place: purpose, path semantics, schema discovery, and alternative-preference guidance. It is front-loaded with the most important information and has no filler.

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

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

For a generic raw-API escape hatch with no output schema, the description is appropriately complete: it teaches the agent how to discover endpoint schemas, how to build paths, and when to avoid the tool. It correctly delegates exhaustive endpoint enumeration to the linked API schema.

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

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

Schema coverage is high, but the description adds meaning beyond the schema by explaining that `path` is relative to `/api/`, giving concrete examples, and noting trailing-slash normalization. It also clarifies that `body` is for POST/PATCH/PUT implicitly via the raw-API context.

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

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

States a specific verb+resource: an escape hatch for any paperless-ngx REST endpoint not covered by the purpose-built siblings, with concrete examples such as workflows, share links, mail rules, and trash. It clearly distinguishes itself from the other paperless tools by 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?

Gives explicit routing guidance: prefer the purpose-built tools when one fits; use this tool for endpoints they do not cover. It also provides path-relative-to-`/api/` instructions and a link to the full API schema, so the agent knows exactly how to construct a call.

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 the operation as mutating/destructive, so the description adds meaningful behavior beyond them: it runs asynchronously and `delete` moves documents to trash rather than permanently deleting them, with `confirm: true` required. This is exactly the kind of context that helps an agent predict consequences.

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

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

Three short, front-loaded sentences communicate the core operation, the parameter-selection rule, and the two most important behavioral cautions. Every sentence contributes value and there is no redundancy with the schema.

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

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

Given the tool's complexity, the description correctly focuses on the non-obvious facts: asynchronous execution and trash/confirm behavior. The schema covers parameter-method mappings, though the conditional parameter requirements across the nine methods are not fully enforced or spelled out in either place, leaving minor ambiguity.

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

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

Schema description coverage is 100%, so parameter details are already well documented. The description only reinforces the general principle of passing only method-relevant parameters and highlights the `confirm` flag for delete, without adding new parameter-level semantic detail.

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

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

The description states a concrete action, 'Apply one operation to many documents at once,' which clearly identifies the resource and scope. It distinguishes the tool from single-document operations like paperless_update_document without needing to name them.

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

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

It gives useful operating guidance: 'Supply only the parameters the chosen method needs' and calls out the delete confirmation requirement. However, it never explicitly says when to choose bulk edit over single-document alternatives, so the tool-selection guidance is mostly 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 indicate this is not read-only and not destructive. The description adds relevant domain context: matching algorithm values, storage path template requirements, and custom field data types. It does not disclose return values, validation behavior, or permission needs, but the annotation safety profile lowers 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?

The description is compact and front-loaded with the core purpose, followed by concise type-specific notes. It loses a point because the full matching algorithm list largely duplicates the schema's existing description, and the title's 'type' is slightly ambiguous compared to the fuller description.

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 10 parameters and several type-specific constraints, the description supplies the important cross-cutting requirements: storage paths need a path template and custom fields need a data_type. Combined with the rich schema containing per-parameter descriptions and enums, the agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the matching algorithm enum and data_type values that are already in the schema, while adding only a storage path template example. This adds slight value but does not meaningfully compensate beyond what the schema already provides.

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

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

The description names a specific verb ('Create') and enumerates the exact resources: tag, correspondent, document type, storage path, or custom field. This clearly differentiates it from sibling tools like paperless_update_object, paperless_delete_objects, and paperless_list_objects, even without explicit cross-references.

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 usage case by saying 'Create a tag...' and adds helpful type-specific conditions, such as storage paths needing a `path` and custom fields needing `data_type`. However, it does not explicitly state when not to use the tool or point to alternatives like paperless_update_object for modifications, leaving some routing to inference.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses the exact nature of the destructive effect: associations are permanently removed while documents remain intact. It also surfaces the non-negotiable 'confirm: true' requirement, which is a critical behavioral condition for safe invocation.

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 succinct sentences front-load the primary action, then add the two most important qualifications: the effect on documents and the confirm requirement. No filler or duplication with schema descriptions.

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

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

For a destructive tool with annotations present and no output schema, the description covers the essential behavioral context: what is deleted, what is not deleted, and the required confirmation. This is sufficient for an agent to call it correctly without additional hidden guidance.

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

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

Input schema description coverage is 100%, so the schema already documents all three parameters. The description adds no new detail beyond the schema, though it does reinforce the confirm requirement via 'Requires confirm: true'. This matches the baseline for fully-described 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?

States a specific verb ('delete'), a precise set of resources ('tags, correspondents, document types or storage paths'), and clarifies the scope of the effect. It is immediately distinguishable from siblings like paperless_create_object, paperless_update_object, and document-focused tools because it is the only one that deletes these metadata 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 gives useful context about when not to use this tool: 'Documents themselves are not deleted, but they lose the association' tells the agent this does not remove documents. It also communicates the required confirmation. However, it does not explicitly name an alternative tool for deleting documents or for listing objects to obtain ids.

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 destructiveHint=true and readOnlyHint=false, and the description explicitly mentions delete, which is consistent and non-contradictory. However, it adds no additional behavioral context beyond what annotations and the action list already convey, such as irreversibility of deletion or that adding appends to existing notes.

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 sentence efficiently conveys the core capability without redundancy. It is front-loaded with the action list and resource, and every word adds meaning. This is appropriately concise for a multi-action CRUD tool.

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

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

The description is short but adequate given the absence of an output schema and the presence of annotations that cover safety. It does not detail return values or the effect of the default 'list' action, but those are implied by the action enum and not critical for a basic call. The required parameter relationships are documented in schema descriptions, so the agent can correctly construct calls.

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

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

The description adds value by clarifying when note and note_id are required, complementing the schema's 75% coverage which lacks description for 'action'. It explains 'Note text. Required for add' and 'Note id. Required for delete', which is not in the schema description. This helps the agent map parameters to actions.

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

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

The description clearly states the tool operates on document notes with three distinct actions: list, add, delete. It mentions the resource (document) and the actions, making the purpose explicit. It distinguishes from siblings like paperless_update_document by focusing on notes, though it doesn't explicitly name alternatives.

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

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

The description gives no guidance on when to use this tool versus other tools, such as paperless_update_document or paperless_bulk_edit_documents. It does not mention prerequisites, exclusions, or alternative tools for related operations. Usage context is only implicit through the actions list.

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

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

Annotations already signal idempotence, non-read-only, and non-destructive behavior; the description adds useful context by stating that writes are confined to PAPERLESS_DOWNLOAD_DIR and that the tool returns the file path. It does not contradict the annotations, and the added safety scoping is genuinely valuable for an agent deciding how to invoke it.

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

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

Three front-loaded sentences carry the essential message with no filler: the action, the key parameter option, the sibling alternative, and the safety boundary. Formatting with backticks makes parameter values easy to parse.

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

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

The description covers the return value (the path), the key parameter distinctions, the alternative tool, and the write boundary, which is strong for a tool with no output schema. It falls slightly short by not clarifying the relationship between `preview` and `thumbnail` or elaborating on the `version` parameter, but the schema covers the latter and the overall picture 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 coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema by explaining what each rendition means ('as uploaded', 'OCR'd PDF', 'small preview image') and reinforces the download directory confinement. It does omit the `preview` enum value, but the main parameter semantics are enriched.

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

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

The description names a specific verb-resource pair ('Save a document's file to local disk and return the path') and clearly differentiates this tool from paperless_get_document by directing text-only needs to the sibling. This is unambiguous and distinguishes the tool from its siblings.

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

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

It explicitly tells the agent which `kind` to choose for original files, OCR'd archives, and thumbnails, and it specifically says to use paperless_get_document when only extracted text is needed. This provides actionable when-to-use guidance with a clear 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?

Annotations already mark this as read-only. The description adds useful behavioral detail: metadata names are resolved, and the response includes extracted text, notes, and custom field values. No contradictions with the readOnlyHint annotation.

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

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

Two sentences, front-loaded with the core action and payload, with no filler. Every clause contributes either scope or usage guidance.

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

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

For a single-document read tool with a fully documented schema and read-only annotations, the description covers the main behavior and even notes the natural predecessor tool. It does not explicitly contrast with downloading the file, but the listed return contents make the distinction inferable.

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%, including defaults and limits for include_content, include_metadata, and content_max_chars. The description adds no extra parameter semantics beyond that, matching the baseline for fully documented 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?

States a specific verb and resource ('Fetch one document by id') and enumerates what is returned: metadata with resolved names, extracted text, notes, and custom field values. This clearly distinguishes it from sibling search and download tools.

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

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

Explicitly says to use this after `paperless_search_documents` for reading a document's contents. It does not mention the alternative `paperless_download_document`, but the intended context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true, and the description adds what the tool returns: suggested correspondents, tags, document types, storage paths, and dates. It also explains the suggestion source ('trained matching'), which goes beyond the structured 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 with no wasted words. The primary action and return value are front-loaded, and the note about being useful before paperless_update_document adds practical guidance without bloating the description.

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

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

For a tool with a single fully documented parameter and read-only annotations, the description covers the purpose, inputs, and expected outputs. Since there is no output schema, listing the returned suggestion fields is sufficient for an agent to understand what 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?

placeholder

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 clearly states a specific action: asking paperless what it would file a document as, based on its trained matching. It enumerates the returned suggestion categories, making it distinct from sibling tools like paperless_get_document or paperless_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 context for when to use the tool: when you want filing suggestions and before calling paperless_update_document. It does not explicitly mention when not to use it or name alternative tools, but the use case is well defined.

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

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

The description adds meaningful behavior beyond the readOnlyHint annotation by specifying exactly what aggregate data is returned and emphasizing the whole-library scope. It also implicitly communicates a safe, lightweight overview operation. No side effects are claimed, and the description does not contradict the annotations.

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

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

The description is compact and front-loaded: the first phrase states the core scope, then the sentence enumerates the contents, and the final sentence gives the use case. Every sentence adds value and there is no redundant filler.

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

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

For a simple parameterless, read-only statistics tool, the description is largely complete: it enumerates the returned categories and explains when to use it. Since there is no output schema, some response-shape detail is left unspecified, but the listed contents give an agent enough confidence to invoke the tool and interpret the result.

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

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

With zero parameters and 100% schema description coverage, the input schema already fully documents the calling contract. The description adds no parameter details because none are needed. The baseline of 4 for parameterless tools is appropriate.

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

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

The description clearly identifies the tool as returning library-wide totals and enumerates the specific statistics included (document count, inbox count, characters indexed, tag/correspondent/document-type counts, file type breakdown). It does not use an explicit verb, but the tool name and content make the purpose unambiguous. It implies differentiation from search-oriented siblings by stressing 'whole library' and positioning it before searching.

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 states a clear usage context: it is 'a good first call to see how big the library is before searching it.' This gives an agent a concrete trigger for choosing this tool. However, it does not explicitly mention alternatives or say when not to use it, so it falls short of full 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 mark readOnlyHint=true, and the description adds meaningful context by listing which subsystems are inspected. It makes clear this is a passive health probe and does not mutate anything, going beyond the bare annotation.

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

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

Two concise sentences: the first defines scope, the second defines when to use it. Every phrase adds value and there is 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?

The description covers the main returned categories and the intended diagnostic use, which is sufficient for a zero-input status endpoint. It could specify exact response formatting, but the absence of an output schema is mitigated by the concrete list of reported areas.

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 schema description coverage is 100%, so there are no inputs left for the description to clarify. The baseline of 4 applies since no parameter documentation burden 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 states the tool reports the health of the paperless-ngx install and enumerates the exact areas covered (version, database/index status, Redis/Celery connectivity, API version). It clearly distinguishes this diagnostic endpoint from sibling document/data 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 use this tool to check connectivity and diagnose failures, providing a concrete use case. It does not name alternatives or state when not to use it, but the intended trigger condition 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 readOnlyHint and openWorldHint, so the description doesn't need to restate read-only behavior. It adds value by disclosing the return shape (ids and document counts) and broadening scope to saved views, users, groups, mail accounts, mail rules, workflows and share links, which the title alone doesn't 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 sentences, no filler. The primary purpose and usage guidance are front-loaded, and the extra object-type coverage is confined to a single closing sentence. 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?

There is no output schema, so the description carries the return-value burden; it says the tools provides ids and document counts, which is sufficient for an agent to know what to expect. It could add a note about pagination or rate limits, but those are partially covered by the all_pages parameter description and 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 67%, covering type, ordering, all_pages, and name_contains. The description reinforces the type enum by naming tags, correspondents, document types, storage paths, and custom fields, but it does't add meaningful semantics for page or page_size beyond their schema defaults.

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

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

The description opens with a specific verb and resource: 'List the objects documents are filed under, with their ids and document counts.' It clearly distinguishes itself from document-search and document-mutation siblings by positioning itself as the id-lookup tool.

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

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

It explicitly instructs when to call it: 'Call this first when you need an id for a tag, correspondent, document type, storage path or custom field — the document tools take ids, not names.' This also implies when not to use it, since document tools should be used once you have the 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 mark the tool as read-only, and the description adds the meaningful follow-up behavior: checking whether consumption succeeded and which document was produced. It avoids repeating the annotation and contributes a useful workflow detail, though it does not describe pagination or response format.

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

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

Two sentences, front-loaded with the tool's domain and then immediately giving a concrete usage pattern. Every word contributes; there is no filler or redundant restatement 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?

With no output schema, the description usefully communicates the key outcome: seeing whether consumption succeeded and which document resulted. It could mention status filters or default pagination, but the upload-follow-up scenario is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is about 60%, with status and acknowledged already explained in the schema. The description adds critical provenance for task_id by identifying it as the value returned by paperless_upload_document, making the most important parameter actionable. It leaves page and page_size semantically thin, but they are conventional.

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

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

States a specific resource (paperless background tasks) with a concrete inspection purpose, and clarifies typical task types like document consumption and index rebuilds. The tie-in to paperless_upload_document makes the tool's role in an upload workflow unmistakable and distinguishes it from document-centric siblings.

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

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

Explicitly tells the agent when to call it ('Use this to follow up on an upload') and exactly how to use it by passing the task_id from paperless_upload_document. It does not enumerate when not to use it or alternatives, so it stops short of a 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 only provide readOnlyHint and openWorldHint, so the description carries the burden of behavioral disclosure, and it delivers: it documents advanced query syntax, date keywords, word-order-independent and accent-insensitive matching, and the fact that returned names are resolved rather than raw ids. It does not contradict annotations, though it omits details about result response structure.

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 the length is justified by the tool's 25-parameter search surface. It front-loads the purpose, then moves through syntax, alternative routes, and return behavior without filler. Each block earns its place, though it could be slightly more scannable.

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

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

For a complex search tool with no output schema, the description covers the ambiguous parts: query syntax, date keywords, matching semantics, id-based filters, and resolved-name return behavior. It appropriately relies on the schema for the many structured filter parameters. The main missing piece is a fuller description of the result payload shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema: it teaches the full-text query syntax with rich examples, clarifies that tag/correspondent/type filters consume ids, and points to paperless_list_objects as the id source. This materially helps an agent use the parameters correctly.

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 opens with 'Find documents in paperless-ngx' — a specific action and resource — and immediately differentiates itself from retrieval/download siblings. It also names the closest semantic alternatives ('title_contains', 'content_contains', 'more_like_id'), so the tool's unique search scope is unambiguous.

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

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

It explicitly tells agents when to prefer alternatives: use title_contains/content_contains for plain substring matching or more_like_id for similarity search. It also directs the agent to paperless_list_objects for id-based filters, preventing the common mistake of passing names instead of ids.

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 goes well beyond annotations by disclosing that only passed fields are touched, that tag_ids is a wholesale replacement while add_tag_ids/remove_tag_ids are relative, and that clear_* flags unset fields. This gives an agent critical behavioral knowledge about merging versus replacing that cannot be inferred from the schema alone.

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

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

Three sentences lead with the core action, then state the partial-update behavior, then clarify the tag and clear-flag edge cases. Every sentence earns its place and the most important distinguishing semantics 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 16-parameter mutation tool with no output schema and low schema coverage, the description covers the highest-risk semantics but leaves gaps: how to clear simple fields, null-handling for owner_id and archive_serial_number, and the wholesale replacement behavior of custom_fields is only in the schema. An agent could still call it correctly for common cases but would be uncertain about several edge 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?

With only 31% schema description coverage, the description compensates for the most confusing parameters: tag_ids, add_tag_ids, remove_tag_ids, and the clear_* flags. However, many parameters (owner_id, custom_fields, archive_serial_number, storage_path_id) are not addressed in the description, and the generic 'only fields you pass are touched' rule only partially fills that gap.

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

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

The description opens with 'Change one document’s metadata', a specific verb ('change') and resource ('one document’s metadata'), and the singular scope clearly separates it from sibling tools like paperless_bulk_edit_documents. The distinction from paperless_update_object is also implied by the document focus.

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 this is for a single document and explains update mechanics, but it never explicitly states when to prefer this over paperless_bulk_edit_documents or when not to use it. Usage context is present but no exclusions or alternative 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety behavior. It adds a useful behavioral guarantee: 'Only the fields you pass are changed,' clarifying that this is a partial update rather than full replacement. This 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 sentences with no redundancy. The first sentence states the action and resource types; the second states the key behavioral caveat. 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 an 11-parameter object with no output schema, the description gives a workable overview but omits edge-case guidance such as uniqueness constraints, error behavior for nonexistent IDs, or explicit direction to use paperless_update_document for document fields. It is complete enough for common calls but not fully comprehensive.

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 several parameters (type, path, colour, extra_data, is_inbox_tag, matching_algorithm), giving moderate coverage. The description adds general partial-update semantics but doesn't clarify parameters like name, match, owner_id, or is_insensitive beyond what the schema provides. It is adequate but not fully compensatory.

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 specific verbs ('Rename or reconfigure') and names the exact resources (tag, correspondent, document type, storage path, custom field), distinguishing it clearly from document-level tools like paperless_update_document and from create/delete object 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 phrase 'existing' implies this tool is for modifying already-created objects rather than creating or deleting them, but it never explicitly states when to prefer this over paperless_update_document, paperless_create_object, or paperless_delete_objects. Usage context 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?

The description reveals important behavior beyond the annotations: it returns a consumption task ID, consumption is asynchronous, polling can yield the final document ID, and unset fields defer to paperless's matching rules. These details are not visible in the schema or annotations and materially affect how the agent should invoke and await the result.

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

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

The description is compact and front-loaded: purpose first, then prerequisites, then return behavior, then fallback behavior. Every sentence contributes a necessary operational fact, 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?

Despite having no output schema, the description explains what the tool returns, how to wait for completion, and what prerequisites exist. It gives enough context for an agent to invoke it correctly and interpret the result, including the local-file restriction that is critical for 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?

The description adds real meaning to `file_path` (allowed directory constraint), `wait_seconds` (polling semantics), `created` (date format example), `custom_fields` (map example), and the general fallback behavior for unset fields. It does not explain every ID parameter, but the schema already names them clearly and coverage is moderate.

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 and resource: uploading a local file into paperless-ngx for consumption via OCR, tagging, and filing. It clearly distinguishes this from sibling tools like paperless_search_documents or paperless_download_document by focusing on the ingestion pipeline.

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

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

It gives concrete operational guidance: files must reside in PAPERLESS_UPLOAD_DIRS, consumption is asynchronous, and `wait_seconds` should be used to poll for completion. It does not explicitly list when not to use this tool or mention alternative siblings, but the context is clear enough for an agent to select it correctly.

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