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

With no annotations, the description carries the safety burden and does disclose that the 'delete' operation permanently removes correspondents system-wide, which is genuinely useful. However, it says nothing about the other operation (set_permissions), permission/auth requirements, or that a confirm flag is mandatory, leaving important behavior undisclosed.

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

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

Two short sentences with the destructive warning front-loaded and no wasted words. Efficient, though it is under-informative rather than over-specified.

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

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

For a 6-parameter destructive bulk tool with nested objects, no output schema, and no annotations, the description is far too thin. It covers only the delete hazard and omits the second operation, parameter meanings, and return 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 only 17%, so the description should compensate but instead mentions no parameters at all. The nested permissions object, merge, owner, and even the enum values are left unexplained in both the description and largely the schema.

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

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

The description states a verb ('bulk edit') and resource ('correspondents'), but this is essentially a restatement of the tool name. It signals the bulk scope, which distinguishes it from the singular update_correspondent/delete_correspondent siblings, but adds little beyond that.

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

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

There is no guidance on when to use this versus the singular update_correspondent or delete_correspondent, or versus other bulk_edit_* tools. The only hint is the embedded warning about the delete operation; no prerequisites or alternative selection criteria are given.

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

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

With no annotations, the description must carry the safety burden, and it does disclose the key trait: 'delete' permanently removes fields from the entire system, which is a global, irreversible side effect beyond the schema. It omits auth requirements and what happens to documents using the deleted fields, keeping it short of a 5.

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

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

Two short sentences, with the destructive warning surfaced up front and no filler. Efficient, though it spends words on 'bulk edit' framing that the schema actually narrows to delete-only.

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 mutation with no annotations and no output schema, the description covers the critical hazard but omits prerequisites (confirm must be true), the delete-only operation reality, and any return behavior. Adequate but with clear 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 coverage is only 33%, so the description should compensate but adds nothing about parameters. The custom_fields array of numbers (field IDs) is undocumented, and the confirm flag's destructive-precondition role is left entirely to the schema.

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

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

The description names a verb ('bulk edit') and resource ('custom fields'), but 'edit' oversells the tool: the operation enum permits only 'delete', so a reader expecting edits could be misled. It also does not distinguish this from the sibling 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?

No guidance on when to use this bulk tool versus the singular delete_custom_field, nor when bulk deletion is appropriate over individual calls. The delete warning hints at scope but never states the selecting condition.

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?

With no annotations, the description carries full behavioral burden. It usefully discloses that 'delete_tag' is system-wide and permanent, and that 'delete' permanently deletes documents and needs confirmation. But it remains silent on side effects, permissions, or reversibility for the remaining methods (set_permissions, merge, split, reprocess, etc.).

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

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

Three tight sentences: purpose first, then method distinction, then destructive warning. Nothing is wasted, though given the tool's breadth it is arguably too sparse rather than too long.

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 18 parameters, 14 methods, nested objects, no annotations, and no output schema, the description is substantially incomplete. It covers only a fraction of the method semantics and parameter meanings an agent would need to invoke it correctly.

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

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

Schema description coverage is only 22%, so the description must compensate. It explains the distinction between two method values but adds no meaning for core parameters like 'tag', 'documents', 'pages', 'storage_path', or most of the 14 enum methods, leaving most parameters undocumented.

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

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

States a specific verb+resource ('Perform bulk operations on multiple documents'), which clearly separates it from single-document siblings like update_document and from other bulk tools. However, it does not enumerate what kinds of operations are available beyond the two tag methods it calls out, so it stops short of full sibling differentiation.

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 guidance for choosing between two similar methods ('remove_tag' vs 'delete_tag') and warns that 'delete' requires confirmation, which is useful. But it gives no guidance on when to use this bulk tool versus other tools, and no context for the other 11 methods.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the 'delete' operation permanently removes document types system-wide, which is critical context beyond the schema. However, it omits other behavioral traits such as required permissions, the effect of set_permissions, and any rate limits or side effects for non-delete operations.

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

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

Two sentences with zero waste, front-loading the purpose and clearly marking the destructive warning. It is appropriately sized 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?

Given a complex mutation tool with 6 parameters, nested objects, no annotations, no output schema, and 17% schema coverage, the description is substantially incomplete. It covers purpose and delete danger but leaves the main non-delete operation, parameter meanings, and required confirmation behavior (documented only in schema) unexplored.

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

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

Schema description coverage is only 17% (only the confirm parameter has a description). The description adds meaning only for the 'delete' enum value, but does not explain document_type_ids, merge, owner, permissions, or the set_permissions operation. It does not 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 verb and resource ('Bulk edit document types'), clearly distinguishing it from siblings like bulk_edit_documents or bulk_edit_tags. However, it does not indicate what kinds of edits are supported (e.g., set_permissions vs delete) beyond the warning, leaving the purpose slightly less specific than a 5 would require.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as delete_document_type, update_document_type, or other bulk_edit_* tools. The warning about the 'delete' operation provides a condition but not a tool-selection rule, and no prerequisites or exclusions are 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?

With no annotations, the description carries the full burden; it does disclose that 'delete' permanently removes tags system-wide, which is the single most important behavioral fact and is not stated in the schema. However, it omits the confirmation requirement, the set_permissions behavior, and whether the operation is reversible or requires elevated permissions.

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

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

Two short sentences with the destructive warning front-loaded and no filler. Efficient, though the extreme brevity is partly the source of the coverage gaps.

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 6-parameter mutation tool with nested permission objects, no annotations, no output schema, and very low schema coverage, the description is far too thin. It should explain the two operation modes and the confirm gate, and at minimum sketch the permissions/owner/merge parameters.

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

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

Schema description coverage is only 17% across 6 parameters, so the description must compensate and it largely does not. It names 'delete' as an operation value but says nothing about confirm, merge, owner, permissions, or tag_ids semantics, leaving most parameters undocumented in both places.

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 verb and resource ('bulk edit tags'), so the purpose is discernible, but it is essentially a restatement of the tool name and gives no scope detail (what 'bulk edit' encompasses: set_permissions vs delete). It does not distinguish this tool from siblings like bulk_edit_documents or update_tag/delete_tag beyond the resource noun.

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

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

The warning implies caution for the 'delete' operation, but there is no explicit when-to-use guidance, no statement of when to prefer this over individual update_tag/delete_tag, and no mention of the required 'confirm' flag that gates the destructive path.

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?

No annotations are provided, so the description carries the full behavioral burden. For a mutation tool it says nothing about permissions, name-uniqueness/duplicate handling, idempotency, or what is returned after creation. It only hints that match/matching_algorithm drive automatic document assignment, which is useful but thin.

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 well-formed sentence with the core action front-loaded and no filler. It is appropriately sized, though it stops short of adding any operational 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 simple 3-parameter create tool with no output schema and no annotations, the description covers the action and the optional fields' intent. It leaves gaps on return value and on how the matching fields interact with existing documents, which matters given the tool's stated purpose of automatic assignment.

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 33% – only matching_algorithm is documented in the schema, and it is documented exhaustively (0-6 enum meanings). The description compensates partially by explaining that 'match' is a pattern and 'matching_algorithm' governs automatic assignment, but it does not clarify match syntax (regex vs. plain) despite algorithm 4 being regex.

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

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

States a specific verb and resource ('Create a new correspondent') and adds the purpose of the optional fields ('matching pattern and algorithm for automatic document assignment'). An agent can tell it apart from get_correspondent/update_correspondent by name, but the description does not explicitly contrast it with those 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?

No when-to-use, when-not-to-use, or alternative guidance is given. The only implied usage is the verb 'create', and there is no mention of update_correspondent for existing records or list_correspondents for lookup.

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?

With no annotations, the description carries the full burden. It does add genuine behavioral content: the accepted data_type set and the currency-prefix validation rule for monetary values. However, it omits other mutation traits — permission requirements, duplicate-name behavior, irreversibility, and what extra_data does — leaving significant gaps.

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 the type list, then the noteworthy monetary caveat. Every clause earns its place; only minor redundancy in listing all nine types already present in the enum.

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

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

For a mutation tool with no annotations, no output schema, and an undocumented `extra_data` parameter, the description is under-specified. It covers the happy path of creating a typed field but not side effects, failure modes, or the extra payload.

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 must compensate. It enumerates the data_type values (matching the enum) and explains monetary value formatting, but says nothing about `name` constraints or the open-ended `extra_data` object, which is the most opaque parameter.

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

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

States a specific verb+resource ("Create a new custom field") and adds the key discriminator, the data_type that shapes the field. It is clearly distinguishable from list/update/delete_custom_field siblings, though it does not name them explicitly.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. The agent must infer that this is the creation counterpart to update_custom_field purely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the effect and the return payload ('Returns the document's full list of notes after the note is added'), but says nothing about required permissions, whether the note is mutable or deletable afterward, or failure behavior when the document ID does not exist.

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

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

Three tight sentences with the action front-loaded, followed by usage context and the return value. 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 two-parameter create tool with no annotations or output schema, the description covers purpose, a usage scenario, and the return payload. It is nearly complete; only auth/idempotency details are absent.

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

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

Schema description coverage is 100% and the schema already documents 'id' (document ID) and 'note' (note text with minLength 1). The description adds no syntax, format, or length guidance beyond what the schema supplies, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a note to a document') that cleanly separates it from sibling tools like list_document_notes and delete_document_note. The sentence also clarifies the note is attached to the document itself, not a global record.

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?

Offers a concrete use case ('record an audit trail or progress note directly on the document'), which implies context, but does not state when NOT to use it or name alternatives (e.g. update_document, custom fields) for recording information.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a write/mutation but says nothing about uniqueness of name, behavior on duplicate, permissions required, or what the created type looks like. Only the classification purpose hints at downstream 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?

A single front-loaded sentence with no filler; the optional parameters are noted up front. It is efficient, though it could be slightly richer given the missing behavioral 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 mutation tool with no annotations and no output schema, the description leaves important gaps: side effects, name uniqueness/conflict handling, and return shape are unaddressed, and one of three parameters is undocumented in both schema and description.

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 33%: 'matching_algorithm' is fully documented in-schema (enum 0–6), while 'name' and 'match' are undocumented. The description partially compensates by framing 'match' as a matching pattern and both extras as optional, but gives no format or example for the pattern.

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+resource ('Create a new document type') and adds the purpose ('for automatic document classification'), which distinguishes it from sibling read tools like get_document_type. It does not explicitly disambiguate from create_tag or create_correspondent, but the create+resource framing is clear.

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

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

There is no explicit when-to-use guidance, no mention of alternatives like list_document_types or update_document_type, and no prerequisites. The phrase 'for automatic document classification' implies intent but leaves the agent to infer when to reach for this tool.

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

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

With no annotations provided, the description carries the full behavioral burden, yet it only hints at the attachment-vs-full-mail tradeoff. It says nothing about what happens once the rule is created (whether it starts fetching mail), permission requirements, or side effects for a 24-parameter mutating tool.

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

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

Three tight sentences with the core action front-loaded and no filler. The use-case advice is compact, though it is somewhat narrow relative to the tool's breadth.

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 high-complexity creation tool with 24 parameters, no annotations, no output schema, and 25% schema coverage, the description is far too thin. It omits the behavioral and parameter context an agent needs to invoke it correctly.

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

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

Schema description coverage is only 25%, and the description explains almost none of the 24 parameters beyond gesturing at account and attachment-only behavior. With low coverage the description should compensate, but it leaves most fields (order, action, filters, assign_* mappings) entirely to the sparse schema.

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

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

The description opens with a specific verb+resource, 'Create a Paperless mail rule,' which is unambiguous and clearly distinct from get/update/delete_mail_rule siblings. However, it does not explicitly name those siblings or differentiate create from update, so it stops short of full sibling routing.

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 concrete prerequisite ('Use list_mail_accounts first to choose account') and a situational recommendation ('Prefer attachment-only rules for invoices unless the full mail must be archived'). That is actionable, though it never addresses when to update vs create a rule or any preconditions beyond account 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?

With no annotations, the description carries the full behavioral burden, yet it only says 'Create.' It does not state whether the name must be unique, what happens on conflict, whether the operation requires specific permissions, or what the response contains – all material for a mutation tool.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though its brevity is part of why behavioral and parameter detail is missing.

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 4-parameter mutation tool with zero annotation coverage, no output schema, and 25% schema description coverage, the description leaves too much undisclosed – validation rules, uniqueness, permissions, and return behavior are all absent.

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

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

Schema coverage is only 25% (only matching_algorithm is documented). The description loosely labels three optional fields but never explains the color hex format, the syntax of the 'match' pattern, or the valid name constraints, so it does not compensate for the coverage gap.

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

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

States a specific verb ('Create') and resource ('a new tag') and enumerates the optional facets it accepts. It is clearly distinguishable from siblings like list_tags, update_tag, and delete_tag, though it does not explicitly name any of 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?

No when-to-use guidance is given, no prerequisites, and no mention of alternatives such as update_tag or bulk_edit_tags. The reader must infer that this is the creation path from the name alone.

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

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

With no annotations, the description carries the full burden and does disclose the two most important traits: the deletion is permanent (irreversible) and it cascades to ALL documents using the correspondent. It still omits permission/auth requirements and any recoverability detail beyond 'permanently'.

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 the destructive warning emoji and 'DESTRUCTIVE' keyword front-loaded before the mechanical detail. No filler.

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

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

For a simple two-parameter destructive tool with no annotations and no output schema, the description covers the essential consequence model (permanent + system-wide cascade). It stops short of permission requirements or recovery options, which would complete the picture.

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% – 'id' has no schema description and the description adds no meaning for it either. The description explains no parameter semantics, so it fails to compensate for the coverage gap even though 'confirm' is self-documented in the schema.

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

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

States a specific verb+resource ('Permanently delete a correspondent') plus the system-wide scope ('from the entire system'), which the sibling delete_tag/delete_document_type do not share. An agent can distinguish this from update_correspondent or bulk_edit_correspondents immediately.

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 consequence explicit, which implies caution, but never states when to choose this over alternatives such as update_correspondent or bulk_edit_correspondents, nor any prerequisite. Usage is implied by the destructive warning rather than spelled out.

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

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

With no annotations, the description carries the full behavioral burden and does well on the most important trait: it discloses that deletion is permanent and cascading, removing the field from ALL documents that use it. It omits any auth/permission requirements and the response shape, so it is strong but not exhaustive.

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, with the destructive warning and permanence front-loaded ahead of the cascading impact. Ideal sizing for a simple delete tool.

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

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

For a two-parameter destructive tool with no annotations and no output schema, the description covers the essential risk (permanent, system-wide removal). Minor gaps remain around permissions and the confirmation behavior, which the schema only partially covers.

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

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

Schema description coverage is only 50% (the 'id' parameter is undocumented). The description adds nothing about either parameter, not even mentioning the required 'confirm' gate or what 'id' refers to, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Permanently delete a custom field') and scopes it precisely ('from the entire system'), which distinguishes it from the many sibling delete_* tools for tags, correspondents, document types, etc. An agent can select it unambiguously.

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 when-to-use or when-not-to-use guidance: nothing says when to delete versus update or bulk_edit_custom_fields, nor mentions prerequisites beyond the schema's confirm flag. The destructive warning signals caution but not tool selection criteria.

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?

With no annotations, the description carries the full behavioral burden and does well: it flags the operation as destructive, states it is permanent and irreversible, and discloses that the return value is the document's remaining notes. It does not mention permission/auth requirements, which is the remaining gap.

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 tightly written sentences with the DESTRUCTIVE warning and irreversibility front-loaded, then the return value. No wasted words.

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

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

For a three-parameter destructive tool with no output schema, the description covers the safety profile, irreversibility, key parameter meaning, and return shape. Only a note about required permissions or a pointer to sibling list/bulk tools is missing.

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

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

Schema description coverage is 100%, so the schema already documents id, note_id, and confirm. The description adds only that deletion targets a 'note' by 'note ID' and implies a document context, which is marginal added value. Baseline 3 applies.

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

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

States a specific verb (delete), resource (a single note on a document), and the lookup key (note ID). It is clearly distinguishable from siblings like list_document_notes and create_document_note.

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

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

Usage is implied by the destructive warning and the singular scope ('a single note'), but there is no explicit when-to-use vs alternatives guidance (e.g., to remove many notes use bulk_edit_documents, or to list notes first use list_document_notes). No exclusions or prerequisites 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?

With no annotations, the description carries the full burden and it does disclose two important traits: the deletion is permanent (irreversible) and it cascades to ALL documents using that type. It omits permission requirements and what happens to the affected documents' type assignment, so it is strong but not complete.

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

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

Two short sentences with the warning icon and DESTRUCTIVE keyword front-loaded, followed immediately by the blast radius. Zero wasted words.

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

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

For a system-wide destructive tool with no annotations and no output schema, the description covers the danger well but leaves open the confirmation requirement, authorization needs, and the effect on documents that reference the deleted type. Adequate but with clear 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 coverage is only 50% (id is undocumented), and the description says nothing about either parameter. Notably, it never mentions the required 'confirm' flag, which is central to a destructive operation, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('delete a document type') and adds scope ('from the entire system'), which distinguishes it from bulk_edit_document_types. However, it doesn't name any alternative operation (e.g., update_document_type), so sibling differentiation is only implicit.

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

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

There is no guidance on when to use this versus update_document_type or bulk_edit_document_types, nor any stated prerequisites. The destructive warning implies caution but gives no condition that selects this tool over its 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?

No annotations are provided, so the description carries the full burden. It does disclose a genuinely non-obvious behavioral trait (affects future mail ingestion, does not delete documents), but omits reversibility, whether the confirm flag is required for safety, and permission requirements.

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, front-loaded with the action and then the key scoping caveat. Nothing redundant or padded.

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

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

For a small destructive tool with no annotations and no output schema, the description covers the blast radius but leaves the id parameter, reversibility, and confirmation requirement unexplained across all surfaces. Adequate but with clear 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 coverage is only 50% and the description adds no parameter meaning at all. The 'id' parameter has no description anywhere, and the 'confirm' semantics ('must be true') live only in the schema, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Delete one Paperless mail rule') and immediately scopes it against the confusing sibling domain by clarifying it does not delete documents. It is distinguishable from delete_document_note/delete_tag and from create_mail_rule/update_mail_rule, though it never names an alternative directly.

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

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

Usage is implied rather than stated: an agent can infer this is for removing a mail rule, and the ingestion-behavior note hints at the consequence. There is no explicit when-to-use vs update_mail_rule (e.g. disabling instead of deleting) and no prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden, and it does disclose the key traits: the operation is destructive, permanent, and cascades across the entire system. It omits auth/permission requirements, whether the deletion is recoverable, and what happens to the tag's other relationships, but the core behavioral risk is clearly surfaced.

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 the destructive warning front-loaded. The trailing caution sentence is somewhat redundant with the opener but small enough not to be wasteful.

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

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

For a simple two-parameter delete with no output schema, the description is largely complete: it conveys destructiveness, permanence, and global scope. Missing only the param explanation for id and any auth/cascade-recovery context, which are minor for this tool's complexity.

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%: the confirm parameter is self-documented, but id has no description in the schema and none in the description either. The description adds no parameter-level meaning beyond the schema, so it neither compensates for the gap nor confuses anything.

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) and resource (tag), and goes further by scoping the effect: 'from the entire system' and 'from ALL documents that use it.' An agent can distinguish this from sibling tag tools like update_tag or bulk_edit_tags immediately.

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?

'Use with extreme caution' is a warning, not usage guidance. It never says when to prefer this over alternatives such as update_tag (removing a tag from a single document) or bulk_edit_tags, nor does it state preconditions beyond the schema's confirm flag.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely non-obvious behavior: the tool does not return file bytes but a paperless:// resource URI that must then be read. It says nothing about permissions, file size, or error behavior, so it is only partially transparent for a no-annotation tool.

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

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

Two short sentences, zero filler, and the most important information (the URI indirection) is placed immediately after the core action. Nothing needs trimming.

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 does the right thing by explaining the return shape (a resource URI), which covers the biggest gap. But the undocumented 'original' parameter and the absence of any guidance about when to use this over sibling content-retrieval tools leave it short of complete.

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

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

Schema description coverage is 0% and there are 2 parameters. The description accounts for 'id' implicitly ('by ID') but adds no format or constraint detail, and completely ignores the 'original' boolean, leaving an agent unable to tell what it does from either schema or description.

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

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

States a specific verb ('Download') and resource ('a document file by ID'), which is clear enough to separate it from list/query siblings. However, it never distinguishes itself from the closely related get_document_content or get_document_thumbnail, so sibling differentiation is left to 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?

The sentence 'read the resource to fetch the file content' implies the two-step download flow, which is useful implied guidance. But there is no explicit when-to-use versus get_document_content or get_document_thumbnail, and no statement of prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the response includes full details and matching rules, which is useful behavioral context, but says nothing about error behavior for invalid IDs, permissions, or read-only nature.

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

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

A single front-loaded sentence with no waste. It is short and efficient, though it could carry slightly more routing information at the same length.

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

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

For a one-parameter read tool with no output schema or annotations, the description conveys the key facts (identifies record by ID, returns full details plus matching rules). It omits error/edge-case behavior but is largely 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 0% and there is one parameter. The description identifies the parameter's purpose ('by ID'), which compensates minimally for the single undocumented param, but adds no type or format 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?

States a specific verb (Get) and resource (correspondent) with scope ('by ID') and return detail ('full details including matching rules'). This distinguishes it from list_correspondents, though it never names that sibling explicitly.

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

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

The phrase 'by ID' implies the tool is for single-record retrieval versus the list variant, but there is no explicit when-to-use guidance or named alternative. Usage is only inferable.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully notes the return includes data type and extra configuration, which hints at the response shape, but says nothing about permissions, failure behavior when the ID does not exist, or whether this is strictly read-only.

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 efficient sentence that front-loads the action and the output promise. No padding 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 one-parameter read tool with no output schema, the description covers the basics of what is returned. However, with no annotations and no output schema, the agent still lacks detail on error cases and the exact structure of the returned 'extra configuration'.

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% and the schema only types the id as a number with no description. The description repeats 'by ID' without adding format, source, or range guidance, so it fails to compensate for the undocumented parameter.

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

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

The description states a specific verb (get) plus resource (custom field) and scope (by ID, full details). It implicitly distinguishes itself from list_custom_fields by requiring an ID, though it never names the list/create/update siblings 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?

There is no explicit when-to-use guidance and no alternatives named. The phrase 'by ID' implies the caller must already have an identifier (presumably from list_custom_fields), but that inference is left entirely to the agent.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that document content is omitted by default, which is real behavioral information beyond the schema, but it says nothing about permissions, error behavior for invalid IDs, or whether the result is cached/fresh.

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 filler, and the most important constraint (content excluded, use the sibling tool) is front-loaded right after the purpose statement.

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 and no annotations, the description compensates by enumerating the returned metadata fields and flagging the excluded content field. That covers most of what an agent needs for a single-parameter read tool; only input format and failure behavior remain unstated.

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 parameter (id) with 0% schema description coverage. The description implies the argument is a document identifier via 'by ID', which adds marginal meaning, but does not state expected format (the schema type is number) or whether it accepts other identifiers. Adequate but thin for a fully undocumented parameter.

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

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

States a specific verb (get) and resource (document by ID) and enumerates the shape of what is returned: correspondent, document type, tags, custom fields. It also explicitly distinguishes itself from get_document_content, so an agent can route correctly without opening any schema.

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

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

It names the primary alternative (get_document_content) and the exact condition that selects it (content excluded by default). It does not address when to use this versus list_documents, query_documents, or search_documents, but the content-vs-metadata split is the highest-value distinction and it is stated explicitly.

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?

No annotations are provided, so the description carries the full behavioral burden. It says nothing about permissions, whether large documents are truncated, pagination, or what happens with non-text/binary documents, which is a notable gap for a content-retrieval 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 tight sentences with the action front-loaded followed by the use case. 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?

With no output schema and no annotations, the description should say more about what comes back (raw text, truncation, encoding) and any access requirements. It covers the basic intent but leaves the agent guessing about the return payload.

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% and the single 'id' parameter is bare, but the description does clarify that the ID refers to a specific document. It adds no format constraints, valid range, or relation to other identifiers, so it only partially compensates for the schema 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?

States a specific verb and resource: retrieve the text content of a document identified by ID. This distinguishes it reasonably from the metadata-oriented 'get_document' and the image-oriented 'get_document_thumbnail', though it never names those siblings 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?

Gives a clear use condition: 'when you need to read or analyze the actual document text.' That differentiates it from metadata or thumbnail retrieval in spirit, but it stops short of naming alternatives (get_document, download_document) or excluding cases (e.g., binary/non-text documents).

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

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

With no annotations, the description carries the burden, and it does disclose a genuinely useful behavioral trait: the call returns a paperless:// resource URI that must then be read to obtain image bytes. However, it omits other relevant behavior such as what happens when a document has no thumbnail, any permission requirements, or the image format/size.

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 zero filler; the purpose is front-loaded and the two-step retrieval behavior 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?

For a one-parameter read tool with no output schema and no annotations, the description covers the essential contract including the non-obvious two-step resource-URI return. Only minor gaps remain, such as missing-thumbnail behavior and image characteristics.

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, and 'by ID' at least establishes that the single integer parameter identifies the document. It adds no constraints, format, or example beyond that, so it is only partially compensating for the undocumented parameter.

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

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

States a specific verb and resource ('Get a document thumbnail') and parenthetically disambiguates it as an image preview, which separates it from text-oriented siblings like get_document_content or get_document. It does not explicitly name any sibling, so it falls short of full differentiation.

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 when-to-use or when-not-to-use guidance, and no mention of the adjacent tools (get_document_content, get_document, download_document) an agent might confuse it with. The usage is only implied by the description of what is returned.

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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully signals that the response includes 'full details including matching rules,' but says nothing about whether this is a safe read, error behavior for invalid IDs, permissions, or rate limits.

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

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

A single, front-loaded sentence with no filler; the core action and scope are stated immediately. It is efficiently sized for a trivial single-parameter getter.

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 tool with no output schema, the description is minimally sufficient and gestures at return content ('matching rules'). It still leaves the return shape, error cases, and read-only nature unstated.

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 a single required parameter with 0% schema description coverage, so the schema does not document 'id' at all. The description only says 'by ID,' clarifying that the parameter is an identifier but adding no detail on type, format, or expected values.

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

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

States a specific verb and resource ('Get a specific document type') and nodes its scope by ID, which implicitly separates it from the sibling list_document_types. It does not name a sibling explicitly, so it stops short of the top score.

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 'by ID' implies you call this when you already have an identifier and want single-record detail, but there is no explicit when-to-use guidance, no exclusion, and no mention of when to prefer list_document_types or update_document_type instead.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that password/token fields are redacted in the response, but does not state permission requirements or confirm the read-only nature beyond the verb 'Get'.

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

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

Two short sentences with no filler; the core action is front-loaded and the redaction caveat follows. 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 single-record getter with no output schema, the description covers the action and the notable redaction behavior. It omits what fields are returned and any failure/not-found behavior, leaving some gaps for an agent.

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

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

The single 'id' parameter has 0% schema description coverage, so the description must compensate. It only says 'by ID', which restates the obvious integer identifier without adding format or lookup semantics, though the parameter is fairly self-evident.

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 ('Get one Paperless mail account') and scopes it to a single record by ID, which implicitly distinguishes it from list_mail_accounts. It does not name the sibling explicitly, but an agent can still tell it apart.

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

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

Usage is only implied: use this when you already have an account ID and want its details rather than the full list. There is no explicit when-to-use, when-not, or reference to list_mail_accounts as 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read, but it says nothing about behavior on a missing/invalid ID, required permissions, or what is returned; for a zero-annotation tool this is a substantial gap.

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 short sentence with the key scoping information front-loaded and no wasted words.

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

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

For a simple single-param getter the description is arguably sufficient, but with no annotations, no output schema, and 0% parameter documentation, an agent gets no safety or error-handling context. Adequate as a minimum but with clear 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?

There is one parameter at 0% schema description coverage, so the description must compensate. Saying 'by ID' confirms the parameter identifies a mail rule, but adds no format, range, or type detail beyond that; a minimal but non-zero contribution.

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

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

The description states a specific verb (Get) and resource (Paperless mail rule) scoped to a single entity by ID, which separates it from the sibling list_mail_rules. It is clear but does not explicitly name the alternatives it is distinguished from.

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 when-to-use guidance is given and no alternatives (e.g., list_mail_rules for discovery, get_mail_account for accounts) are mentioned. The only implied usage is fetching a rule whose ID is already known.

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?

With no annotations, the description carries the full burden. 'List' implies a read-only operation, but there is no explicit statement about safety, permissions, rate limits, pagination defaults, or what the response contains.

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 tightly written sentences with zero waste. The core purpose is front-loaded, followed by a brief clarifying definition.

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 7-parameter list endpoint with no annotations, no output schema, and no schema descriptions, the description is too sparse. It omits parameter explanations, pagination behavior, filtering syntax, and return format details.

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

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

The schema has 7 parameters at 0% description coverage, so the description must compensate. It only vaguely refers to 'filtering and pagination' without naming or explaining any of the specific name filters, ordering, page, or page_size 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?

States a specific verb ('List') and resource ('correspondents'), and adds a definition of what correspondents are. It implicitly distinguishes from single-item siblings like get_correspondent, but does not explicitly name alternatives or contrast with 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?

Mentions optional filtering and pagination, which hints at capabilities, but provides no guidance on when to use this tool versus get_correspondent or other list tools, nor any conditions or prerequisites for filtering.

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?

No annotations are provided, so the description carries the full burden. It discloses genuine behavioral traits (caching strategy, page_size guidance, request-reduction intent), but omits return format, read-only confirmation, and permission/auth needs for a list 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?

Front-loaded with the core purpose, then a clearly flagged IMPORTANT workflow note. Efficient overall, though the caching instruction is somewhat verbose for a single-line purpose.

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?

No output schema and no annotations means the description should carry more, yet it is heavily weighted toward workflow advice while leaving most parameter semantics and the return shape unexplained. Adequate for a list tool but with clear gaps for 7 undocumented params.

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% across 7 parameters, and the description only adds meaning to one of them (page_size, described as needing to be 'large enough'). page, ordering, and the four name filtering operators (name__iexact/icontains/iendswith/istartswith) are left entirely undocumented in both schema and description, leaving the compensation gap unfilled.

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

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

States a specific verb and resource ('List all custom fields') that an agent can immediately disambiguate from get_custom_field, create/update/delete_custom_field, and bulk_edit_custom_fields in the sibling set. The scope ('all') is clear, though slightly at odds with the exposed name-filter params.

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 operational guidance: fetch up front with a large page_size, cache for the session, and search locally before further API calls. This is strong 'when to use' context, but it never names the sibling alternatives (e.g., get_custom_field for a single record) so the routing 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?

No annotations are provided, so the description carries the burden; "List" does imply a read-only operation, and the description characterizes the returned data as free-text comments. It does not disclose ordering, pagination, or whether an empty result is possible for a document with no notes, leaving some behavioral gaps for a no-annotation tool.

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

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

Two short sentences, front-loaded with the core purpose, and the second sentence adds domain meaning rather than filler. Slightly more elaboration than strictly necessary for a one-parameter list tool.

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

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

For a simple, single-parameter read tool with no output schema, the description covers purpose and the nature of the returned notes adequately. Remaining gaps (result shape, ordering) are minor given the tool's low complexity.

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 one parameter at 100% schema description coverage, the schema already documents the required "id" as the document ID. The description adds no format, type, or constraint information about the parameter, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ("List all notes attached to a document"), so an agent immediately knows what the tool returns. It stops short of naming sibling note tools (create_document_note, delete_document_note), so the read-vs-write distinction is inferred from the verb rather than stated.

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

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

The second sentence explains what notes are and gives example use cases (audit trail, progress notes on an action item), which implies when reading them is valuable. However, it never states when to use this tool versus alternatives like get_document or query_documents, and there are no exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: results are paginated, document content is excluded by default, and lookups are required to obtain filter IDs. It stops short of stating auth/permission needs or response shape/pagination mechanics, but the key surprise (missing content) is flagged.

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?

It is longer than typical but front-loaded with the core action, then routing, then cautions in descending priority. Minor redundancy: the exclusion note and the get_document_content pointer state the same thing twice, but each sentence still 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 14-parameter, zero-coverage, no-output-schema tool, the description covers what it returns (documents without content), when to resolve IDs, and which sibling to prefer. The remaining gap is parameter-level format guidance, which the 0%-coverage schema leaves undocumented.

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% across 14 parameters, so the description must compensate. It names the filter concepts (title search, correspondent, document type, tag, storage path, creation date, ASN, simple custom field filters) but never maps them to parameter names or explains formats for ordering, page/page_size, or how custom_field_query differs from custom_fields__icontains and archive_serial_number__isnull.

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 ('List and filter documents') and immediately scopes it with pagination and the concrete Paperless filter set. It explicitly distinguishes itself from query_documents (full-text, structured conditions, advanced API params) and from get_document_content, so an agent can separate it from siblings without opening schemas.

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

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

It gives explicit routing rules: use query_documents for full-text/advanced queries, use the relevant lookup tool first to resolve tag/correspondent/type/storage-path IDs, and use get_document_content for text. Both a positive path and named alternatives are provided, plus the ID-resolution prerequisite.

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?

With no annotations, the description carries the burden and does disclose meaningful behavior: this is a cheap, cacheable, session-level lookup best fetched with a large page_size. It omits auth requirements, pagination/return shape, and what happens at the page_size limit, which keeps it short of a 5.

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

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

Front-loads the one-line purpose before the IMPORTANT block, and the guidance sentences each add operational value. Slightly verbose for a list endpoint, but nothing is padded.

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

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

No output schema and no annotations, so the description should cover more ground. It handles the workflow/caching story well but says nothing about return values or the seven input parameters, leaving an agent partially equipped for anything beyond the 'fetch everything and filter locally' path.

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?

Seven parameters at 0% schema description coverage, yet the description only alludes to page_size and never explains the name__iexact, name__icontains, name__istartswith, or name__iendswith filters or the ordering parameter. It actually advises client-side filtering instead of using the server-side name filters, leaving their semantics entirely unexplained.

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

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

States a specific verb and resource ('List all document types') that cleanly separates it from the sibling get_document_type, create_document_type, and update_document_type. An agent can identify the operation without opening the schema.

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

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

Gives explicit when-to-use guidance: fetch this alongside all tags up front when a user query may reference a document type or tag, cache for the session, and match locally before further API calls. It also frames why (reduces redundant requests, resolves tag/document-type ambiguity), which is stronger than a bare 'use this to 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses a security-relevant trait ('Does not expose account passwords') and 'List' implies a read-only operation, but it says nothing about pagination, ordering, or what happens when no accounts exist.

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, purpose front-loaded before the security caveat, with no filler or restated schema text.

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

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

There is no output schema, so the description should ideally sketch the return shape (IDs, names) and pagination, which it does not. What it does cover — purpose and the password caveat — is accurate but leaves an agent guessing about result structure and paging.

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 never mentions the two parameters (page, page_size). For a paginated list tool, pagination semantics are relevant and are left entirely undocumented in both places.

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 ('List') and resource ('mail accounts'), plus the downstream purpose of obtaining an account ID for mail rules. It implicitly separates itself from get_mail_account (singular) and list_mail_rules, though it never names the alternative.

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

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

The description tells the agent why one would call it (to get an account ID for mail rules), which is useful implied guidance, but it gives no when-not-to-use condition and never points to a sibling for fetching a single account's details.

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?

With no annotations provided, the description carries the full behavioral burden and delivers little: it implies a read-only listing but never states it, and says nothing about ordering, default result size, pagination limits, or permissions.

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 efficient sentence with the resource front-loaded and no filler. It is appropriately sized, though the size reflects under-specification rather than discipline.

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 list tool with 0% schema coverage and no annotations or output schema, the description should explain pagination defaults, ordering, and result shape. It does none of this, leaving key invocation details undefined.

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 two parameters ('page', 'page_size') are undocumented by type, default, or bounds. The description only gestures at 'optional pagination' without explaining either parameter's semantics or 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?

States a specific verb (List) and resource (Paperless mail rules), which distinguishes it from the sibling get_mail_rule and the mail account tools. It lacks explicit sibling differentiation text, but the name and scope are 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?

No guidance on when to use this versus get_mail_rule or list_mail_accounts, and no conditions or prerequisites are given. The agent must infer usage purely from the name.

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

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

With no annotations, the description carries the full burden. It discloses a caching/pagination usage pattern (use a large page_size, cache the result), which is genuinely useful behavioral context, but says nothing about authentication, rate limits, return format, or what happens on large result sets.

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

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

Front-loaded with the core action ('List all tags') before the guidance block, which is good structure. However, the trailing justification sentence ('This reduces redundant requests and handles ambiguity...') restates benefits already implied and pads the definition.

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?

No annotations, no output schema, and 7 parameters with 0% documentation. The description covers a workflow strategy but leaves the actual input semantics and the shape of the returned tags unexplained, so an agent cannot reliably construct filtered or paginated calls from it.

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

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

Schema coverage is 0% across 7 parameters, so the schema explains none of them. The description only hints at page_size; it entirely omits page, ordering, and the four name__i* filter parameters, leaving the agent to guess at filtering and pagination 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?

States a clear verb+resource ('List all tags') and even acknowledges the adjacent resource (document types), so the agent can place it among the list_* siblings. It falls short of 5 because it never distinguishes itself from other list_* tools such as list_correspondents or list_custom_fields, which behave identically at the surface level.

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 strong prescriptive guidance: fetch tags and document types up front with a large page_size, cache for the session, and resolve ambiguity by local name/slug matching. It clearly says when to call this tool, though it stops short of explicit when-not conditions or naming list_document_types as the paired 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?

With no annotations, the description carries the burden and does add real context: the server-side filesystem read implied by file_path, the filename derivation default, and the PAPERLESS_MCP_UPLOAD_PATHS security restriction. It omits failure behavior and whether processing is synchronous, which keeps it short of a 5.

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

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

Three sentences, front-loaded with purpose before the file/file_path mechanics and security note. The uppercase SECURITY sentence is slightly heavy but the content 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 mutation tool with no annotations or output schema and 11 partially documented parameters, the description covers the upload mechanics well but leaves several parameters and the response/processing outcome unexplained. Adequate but with clear 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 coverage is only 27% across 11 parameters. The description names the major fields (title, correspondent, document type, tags, custom fields) and explains the file/file_path/filename relationship, but says nothing about created, storage_path, or archive_serial_number, leaving those opaque.

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 ('Upload a new document to Paperless-NGX') and enumerates the optional metadata it accepts. This clearly separates it from sibling operations like update_document, create_document_note, or download_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?

It gives clear usage conditions: supply either 'file' (base64) or 'file_path' (server path), and prefer file_path to avoid base64 overhead for large files. It does not name alternative tools, but for a create/upload operation there is no close sibling to route against.

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?

With no annotations provided, the description carries the full behavioral burden. It does disclose a key side effect: processing 'can consume matching mails according to enabled Paperless mail rules', which warns that mail may be removed/changed. However, it omits permissions required, idempotency, whether the run is synchronous, and failure 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?

Two compact sentences with the action front-loaded and the side-effect caveat second. No filler, though the second sentence is somewhat hedged ('can consume').

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

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

For a trigger/mutation tool with no annotations and no output schema, the description covers the core action and the consuming side effect but leaves meaningful gaps: prerequisites, whether the account must be enabled, sync/async behavior, and result reporting. Adequate but not complete.

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

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

Schema description coverage is 0% for the single 'id' parameter, so the description must compensate. Saying 'for one account' hints that id is a mail account identifier, but it adds no format, valid-range, or sourcing detail beyond what the bare integer schema 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?

States a specific verb and resource: 'manually run Paperless mail processing for one account'. This clearly distinguishes it from read-oriented siblings like get_mail_account and list_mail_accounts. It is not fully differentiated from other triggering actions, but the action is unambiguous.

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

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

The word 'Manually' implies this is an on-demand trigger rather than a scheduled process, which is useful context, but the description never states when to use this versus letting rules run automatically, nor any prerequisites (e.g., account must be configured/enabled). Usage is only implied.

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

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

With no annotations the description carries the full burden, and it does disclose one important behavior (document content is excluded by default) plus the custom_field_query grammar. It omits pagination behavior, result shape, and auth/permission requirements, so significant behavioral ground is left uncovered.

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?

Purpose is front-loaded, followed by usage, syntax detail, and a closing caveat. Sentences are dense and mostly earn their place, though the two 'prefer top-level arguments' statements feel slightly redundant.

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

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

For a 17-parameter, nested-object tool with no annotations and no output schema, the description covers purpose, usage, one behavioral caveat, and query grammar. It still leaves the majority of the parameters and the pagination/return behavior unexplained, so it is adequate but incomplete.

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

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

Schema description coverage is only 12% across 17 parameters, so the description must compensate. It explains custom_field_query leaf/group syntax and paperless_filters purpose well, but the many first-class args (tag, correspondent, document_type, ordering, page_size, date bounds) remain undocumented in both schema and description.

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

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

States a specific verb+resource ('Query documents') and scopes it to the full-text engine plus structured Paperless filters, routing the agent to get_document_content for text. It does not, however, differentiate itself from the very similar siblings list_documents and 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?

Explicitly says to use it for complex filtering, custom field conditions, and undocumented /api/documents/ parameters, and to prefer dedicated top-level arguments when available. It lacks any exclusion against the closest alternatives (search_documents, list_documents), leaving the primary routing decision 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?

With no annotations, the description carries the behavioral burden, and it discloses two important traits: deprecated status and that document content is excluded from results by default. It does not cover pagination, result limits, or auth requirements, but the content-exclusion note is the key non-obvious behavior an agent needs.

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

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

Three tight sentences, front-loaded with the deprecation warning, then the replacement route, then the content caveat. No filler 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 single-parameter deprecated wrapper with no output schema and no annotations, the description covers purpose, migration path, and the notable return-content caveat. Only the query parameter's semantics remain undocumented.

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% and the single 'query' parameter has no documentation. The description only indirectly hints at the parameter by referencing query_documents' 'query' argument; it adds no syntax, format, or matching-semantics detail for this tool's own parameter.

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

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

States a specific verb and resource ('full-text document search') and immediately frames it as a deprecated compatibility wrapper, which lets an agent distinguish it from the live sibling, query_documents, without opening any schema.

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

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

Explicitly names the alternative ('Use query_documents with the query argument for new integrations') and gives a second routing rule ('Use get_document_content to retrieve content when needed'). Both the when-to-use and when-not-to-use conditions are 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?

No annotations are provided, so the description carries the full behavioral burden. It implies mutation and lightly signals that the target must already exist ('an existing correspondent'), but says nothing about permissions, whether fields are optional/partial, or reversibility of changes.

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

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

A single front-loaded sentence with zero filler. It is efficient, though extremely terse for a mutation tool with four parameters.

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

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

For a simple update tool with no output schema and no annotations, the description is minimally viable: the agent knows the resource and mutable fields. But with low schema coverage and no disclosure of return behavior or partial-update semantics, it stops short of full 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?

Schema description coverage is only 25% (only matching_algorithm is documented in-schema). The description partly compensates by naming the updatable fields (name, match, matching_algorithm), but it leaves the required 'id' identifier and the 'match' pattern semantics unexplained, so it adds only marginal 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?

States a specific verb (update) plus the resource (correspondent) and enumerates the mutable fields (name, matching pattern, matching algorithm). The intent is unmistakable, though it doesn't call out how it differs from siblings like bulk_edit_correspondents.

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

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

No when-to-use guidance and no alternatives named. An agent must infer from the naming convention alone that bulk_edit_correspondents handles multiple records and that create_correspondent is the creation path.

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?

With no annotations, the description carries the full behavioral burden. It says 'update' but does not disclose whether this is a partial or full replacement, what permissions are required, whether omitted fields are preserved, or how the change is confirmed. This is a significant gap for a mutation tool with zero 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?

A single efficient sentence with the operation front-loaded. Nothing is wasted, though it is too terse to convey the semantics it omits.

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

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

For a mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is insufficient. It should explain update semantics, required permissions, and the meaning of the required id and enum-constrained data_type.

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, and it only loosely maps to three of the four parameters (name, data_type, extra_data). It never explains the required id, the allowed data_type enum values, or the shape of extra_data, leaving key parameter meaning undocumented in both schema and description.

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

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

The description gives a specific verb (update) and resource (existing custom field), and names the updatable aspects (name, data type, configuration data). It implies the tool operates on existing fields but does not explicitly differentiate itself from siblings like bulk_edit_custom_fields or create_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?

There is no when-to-use guidance and no mention of alternatives such as bulk_edit_custom_fields for multi-field edits. The word 'existing' hints that the field must already exist, but nothing states prerequisites or when this tool is preferred over its 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?

With no annotations, the description carries the safety burden and does well: it discloses PATCH-style merge semantics ("Top-level fields you omit are left unchanged") and the destructive exception (custom_fields replaces the entire set, omitting a field CLEARS it), plus the merge workflow to avoid data loss. It does not mention permission requirements, error behavior for invalid IDs, or reversibility.

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

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

Three sentences, front-loaded with the operation and its default semantics, then the critical exception flagged with IMPORTANT. Nothing is redundant with the schema 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 mutation tool with no annotations and no output schema, the description covers the two behaviors most likely to cause damage (partial update semantics and the custom-field wipe) and links to the mitigating workflow. It is only slightly short of complete given the 100% schema coverage; return values and auth needs remain unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the omit-means-unchanged contract for all top-level params and the contrast between that contract and custom_fields' replace-everything behavior, mirrored by a pointer to the detailed parameter description.

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

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

States a specific verb and resource ("Update a specific document") and enumerates the mutable field categories, which lets an agent distinguish this from post_document (create) and bulk_edit_documents (batch) 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?

It routes the agent away from this tool for additive custom-field edits ("use bulk_edit_documents with method 'modify_custom_fields' instead") and tells it to call get_document first for merge-based updates. It gives no guidance about permission prerequisites or when to prefer bulk_edit_documents for other field types, so it stops short of full when/when-not coverage.

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?

No annotations are provided, so the description carries the full behavioral burden. It never states required permissions, whether omitted fields are left untouched or cleared, or that this is a destructive mutation — all important for a write tool with zero 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?

A single tight sentence with the verb and resource front-loaded and no filler. It is efficient, though the brevity is partly under-specification rather than pure concision.

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

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

A four-parameter mutation tool with no annotations, no output schema, and 25% schema coverage needs considerably more from the description than one sentence. Critical information about required fields, side effects, and failure modes is absent.

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

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

Schema description coverage is only 25% (just matching_algorithm), but the description partly compensates by glossing 'match' as 'matching pattern' and naming the algorithm field. It still doesn't explain the required 'id', the meaning/format of the pattern value, or how it interacts with the chosen algorithm.

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 ('Update') and resource ('document type') plus the three mutable attributes, so an agent can distinguish it from the sibling create/delete/list/get_document_type operations. It stops short of explicitly naming those siblings or the conditions that separate 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?

No when-to-use guidance, no prerequisites (e.g., that the document type must already exist), and no mention of the create/delete/bulk_edit siblings that could be mistaken for it. The agent must infer usage from the verb alone.

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

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

With no annotations, the description carries the full burden. It usefully discloses patch semantics (unspecified fields are left untouched), which an agent cannot infer from the schema alone, but it says nothing about permissions, reversibility, side effects on existing rules, or error behavior for a 25-parameter mutation.

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

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

Two short, front-loaded sentences with no filler; the operation and its partial-update nature come first. It is efficiently written, though arguably under-specified for a tool of this complexity.

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

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

A 25-parameter mutation tool with 24% schema coverage, no annotations, and no output schema needs substantially more description than two sentences. Nothing tells the agent about the required id, the meaning of the many filter/assignment fields, or what a successful patch returns.

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

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

Schema description coverage is only 24% across 25 parameters, so the schema leaves most fields undocumented. The description compensates with nothing beyond the blanket "only supplied fields are changed" statement, providing no syntax, format, or meaning for fields like account, action_parameter, or filter_from.

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 (patch) and resource (Paperless mail rule) and clarifies it operates on an existing rule, which implicitly distinguishes it from create_mail_rule and get_mail_rule. It does not explicitly name those siblings, so it falls short of a 5.

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

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

"Only supplied fields are changed" implies the partial-update use case and tells the agent it need not send a full rule object, but there is no explicit when-to-use vs. alternatives guidance, no prerequisites, and no mention of required authentication or the required id field.

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?

With no annotations, the description carries the full behavioral burden for a mutation tool. It doesn't say which fields are optional vs required, whether updates are partial or full replacement, what happens on an unknown id, or what permissions are needed.

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 tight sentence with no waste, front-loaded with the verb and resource. It is efficient, though arguably terse given the missing behavioral 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 5-parameter mutation tool with no annotations, no output schema, and 20% schema coverage, the description is too thin — it should state required vs optional behavior, partial-update semantics, and error conditions. The field list alone leaves significant 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 coverage is only 20%, so the description partially compensates by naming the four updatable attributes (name, color, matching pattern, matching algorithm), which map to color, match, and matching_algorithm. However it adds no format or value semantics — notably nothing about the enum meaning of matching_algorithm beyond the schema's own description.

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

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

Clear verb (Update) plus resource (tag) and enumerates the mutable fields, so it's distinguishable from create_tag/delete_tag by name. It never explicitly references siblings, but the operation is unambiguous.

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

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

No guidance on when to use this versus bulk_edit_tags or update_document-style alternatives, no prerequisites (e.g. tag must already exist), and no note on whether unspecified fields are left unchanged.

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