Server Quality Checklist

Tool Scores

• paperless_set_correspondentB
  3/5.0
  Behavior1/5

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

  The description claims to 'set' the correspondent, implying a write operation, but the annotations declare readOnlyHint=true. This is a direct contradiction, and the description does not clarify the actual behavior.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the privacy tier, and every sentence adds value without redundancy.

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

  Completeness2/5

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

  Given the contradiction between description and annotations, and no output schema, the description does not provide complete behavioral context. It lacks information about return values, side effects, or prerequisites.

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

  Parameters3/5

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

  Schema coverage is 100% with descriptions for both parameters. The description adds that the name is resolved to an ID internally, which is slight additional context beyond the schema.

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

  Purpose5/5

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

  The description clearly states 'Set the correspondent of a document by name (resolved to an ID internally)', providing a specific verb and resource, and distinguishes from sibling tools like paperless_set_document_type.

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

  Usage Guidelines2/5

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

  The description mentions 'PRIVACY TIER 1 (management)' but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or alternative tools are mentioned.

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

• paperless_list_tagsB
  3.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true. The description adds that it returns only metadata (Privacy Tier 1) and lists the fields. No further behavioral details like pagination or rate limits, which may be relevant but not required given the tool's simplicity.

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

  Conciseness5/5

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

  Extremely concise: two sentences with key information front-loaded (privacy tier). Every phrase adds value without redundancy.

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

  Completeness3/5

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

  For a simple list tool with one optional parameter, the description covers the core functionality. However, it omits potential details like pagination, sorting, or handling of large result sets, which could be beneficial.

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

  Parameters3/5

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

  Schema coverage is 100%. The description adds that the search filter is case-insensitive, which slightly enhances the schema's description. No other parameters to elaborate.

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

  Purpose4/5

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

  The description clearly states the tool lists all tags with id, name, and document_count. It specifies the optional case-insensitive name filter. However, it doesn't explicitly distinguish from sibling tools like paperless_list_correspondents, though the resource is different.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives. The description only mentions an optional filter but does not specify any conditions or exclusions.

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

• paperless_tag_documentB
  3.4/5.0
  Behavior1/5

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

  The description states the tool 'Sets' tags and 'REPLACES' the tag set, indicating a mutation, but annotations declare readOnlyHint=true. This is a direct contradiction, severely undermining transparency and trust.

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

  Conciseness4/5

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

  The description is three sentences long and front-loaded with the privacy tier. It is concise but could omit 'PRIVACY TIER 1 (management)' as it adds little. Overall, good structure with no unnecessary words.

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

  Completeness3/5

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

  The description explains the return value (applied tags) and the resolution of tag names, making it fairly complete given the tool's simplicity. However, the annotation contradiction introduces uncertainty about actual behavior, reducing completeness.

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

  Parameters4/5

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

  Schema coverage is 100%, and the description adds useful context: tag names are resolved to IDs internally, and unknown names are reported in 'unresolved'. This goes beyond the schema, providing clear semantics for each parameter.

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

  Purpose5/5

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

  The description clearly states the tool sets tags on a document, specifies that it accepts tag names resolved to IDs, and emphasizes that it replaces the entire tag set. This is specific and distinguishes from potential alternatives like adding or removing individual tags.

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

  Usage Guidelines3/5

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

  The description implies usage for setting tags but does not explicitly contrast with sibling tools like paperless_suggest_tags or provide when-to-use/when-not-to-use guidance. The 'PRIVACY TIER 1 (management)' label is vague.

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

• paperless_set_document_typeA
  3.5/5.0
  Behavior1/5

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

  The description indicates a write operation ('Set the document type'), but the annotation readOnlyHint=true claims read-only behavior. This is a direct contradiction. Additionally, the description states 'No content is read or returned,' which adds context but does not resolve the contradiction.

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

  Conciseness5/5

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

  The description is a single, concise sentence that efficiently conveys the purpose and key behavior without unnecessary words.

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

  Completeness3/5

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

  The description is mostly complete for a simple set tool, but it lacks information about the return value or success indication. The contradiction with annotations also reduces completeness.

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

  Parameters4/5

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

  The schema already describes both parameters (document_id and name) with clear descriptions, so the schema coverage is 100%. The description adds value by explaining that the name is 'resolved to an ID internally,' which clarifies the mapping.

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

  Purpose5/5

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

  The description clearly states the action ('Set the document type'), the resource ('a document'), and the method ('by name, resolved to an ID internally'), which distinguishes it from sibling tools like paperless_set_correspondent and paperless_tag_document.

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

  Usage Guidelines3/5

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

  The description does not explicitly state when to use this tool vs alternatives or when not to use it. The context of 'management' is implied but no exclusions are given.

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

• paperless_list_document_typesA
  3.7/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true. The description adds that it returns only metadata (id, name, document_count) and is privacy tier 1, providing useful behavioral context beyond annotations without contradiction.

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

  Conciseness5/5

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

  The description is a single sentence with an additional note about privacy tier. It is front-loaded with the main action and key details, with no unnecessary words.

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

  Completeness4/5

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

  For a simple listing tool with one optional parameter and no output schema, the description covers the essential: what it lists, fields returned, privacy level, and filter behavior. It does not mention ordering or pagination, which is acceptable.

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

  Parameters4/5

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

  Schema coverage is 100% with a description for the 'search' parameter. The description adds that the filter is case-insensitive and substring-based, which adds meaningful nuance beyond the schema's substring filter description.

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

  Purpose4/5

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

  The description clearly states it lists all document types with specific fields (id, name, document_count). However, it does not explicitly differentiate from sibling listing tools like paperless_list_correspondents or paperless_list_tags, missing a chance to distinguish purpose.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives. The privacy tier mention hints at data sensitivity but does not provide when/when-not conditions or reference sibling tools.

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

• paperless_search_documentsA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true. Description adds valuable context: privacy tier, server-side full-text search, and explicit statement that OCR content is never returned. No contradictions.

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

  Conciseness4/5

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

  The description is single paragraph but well-structured and front-loaded with purpose. It contains all essential information without unnecessary words, though could be slightly more organized with bullet points.

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

  Completeness4/5

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

  Given 8 optional parameters, no output schema, and high schema coverage, the description sufficiently explains what the tool returns and how it operates. It mentions privacy and server-side search, which are important contextual details.

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific semantics beyond the schema. It lists return fields but that does not compensate for parameter details.

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

  Purpose5/5

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

  The description clearly states it searches documents and returns metadata only, with a specific list of returned fields. It distinguishes itself from siblings by emphasizing that it never returns OCR content, unlike paperless_get_document_content.

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

  Usage Guidelines4/5

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

  Explicit guidance: 'Use this to find and reference documents without pulling their text into context.' This implies when to use and suggests not using when text is needed, but does not explicitly name alternatives.

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

• paperless_suggest_tagsA
  4.2/5.0
  Behavior4/5

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

  Annotations already mark readOnlyHint=true. Description adds that IDs are resolved to names and that no OCR content is used, providing extra behavioral context beyond what annotations convey.

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

  Conciseness5/5

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

  Two sentences, each adding value. Front-loaded with main purpose, immediately followed by key behavioral note. No wasted words.

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

  Completeness4/5

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

  Given the tool's simplicity (single integer parameter, no output schema), the description covers the functionality and privacy concern. Lacks detail on output format, but for a suggestion tool this is acceptable.

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

  Parameters3/5

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

  Only one parameter (document_id) with 100% schema coverage (description 'Paperless document ID.'). The description does not add additional meaning beyond the schema, but baseline is 3 due to high coverage.

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

  Purpose5/5

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

  Clearly states the tool returns built-in suggestions for multiple fields (tags, correspondents, etc.) for a document. The verb 'suggest' and resource are specific, and it distinguishes from siblings like paperless_list_tags or paperless_tag_document.

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

  Usage Guidelines4/5

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

  Provides useful context: suggestions are server-side, no OCR content enters context. This implies appropriate use cases (when you need suggestions without exposing content). Could be more explicit about alternatives or when not to use, but current guidance is strong.

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

• paperless_extract_fieldA
  4.3/5.0
  Behavior4/5

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

  No annotations beyond title, so description carries full burden. Discloses that OCR text is fetched into MCP server, parsed locally, only extracted values returned, and full content never enters model context. Also explains extraction_pattern behavior. Does not cover error scenarios or performance, but privacy aspect is well-covered.

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

  Conciseness4/5

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

  Single focused paragraph, front-loads privacy tier and purpose. Every sentence adds value; no fluff. Could benefit from slight structuring (e.g., separating usage notes) but overall efficient.

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

  Completeness4/5

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

  Given no output schema, description adequately explains return values (extracted value(s) or matches for regex). Covers privacy, examples of extraction patterns, and extensibility. Missing details on error handling or performance, but sufficient for a focused extraction tool.

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

  Parameters4/5

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

  Schema coverage 100%, but description adds significant value: explains that extraction_pattern can be built-in named extractors (listing examples) or custom regex, and that regex returns all matches with capture group 1 if present. This goes beyond schema descriptions.

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

  Purpose5/5

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

  Description states specific verb ('extract') and resource ('specific field from a document'), distinguishes from siblings like paperless_get_document_content by emphasizing local extraction and privacy tier.

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

  Usage Guidelines4/5

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

  Clearly indicates when to use: for extracting specific fields from a document, with privacy restrictions. Implicitly excludes full-document retrieval (siblings handle that). Lacks explicit when-not-to-use but context is clear.

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

• paperless_download_documentA
  4.4/5.0
  Behavior5/5

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

  Describes the materialization of the file on server host, includes privacy tier warning. Annotations are minimal (only title), so description carries full burden and does so effectively.

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

  Conciseness5/5

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

  Two concise sentences plus a warning line. No wasted words. Front-loaded with purpose.

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

  Completeness4/5

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

  Covers purpose, usage, and behavioral details. No output schema, but return value (file path) is mentioned. Could elaborate on path format, but sufficient for the simple tool.

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

  Parameters3/5

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

  Input schema has 100% description coverage for both parameters. Description adds little beyond 'original document binary (PDF)' which is already implied by the schema descriptions.

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

  Purpose5/5

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

  Description clearly states it downloads document binary to server filesystem and returns file path. Verb 'download' and resource 'document' are specific. Distinguishes from sibling tools that handle metadata, text extraction, or tagging.

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

  Usage Guidelines4/5

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

  Explicitly states 'Use only when the user explicitly needs the actual file rather than metadata or text.' Provides clear when-to-use guidance, though doesn't name alternative tools directly.

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

• paperless_get_document_contentA
  4.6/5.0
  Behavior5/5

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

  Discloses PRIVACY TIER 3 and warns that full OCR text enters model context. No annotations to contradict; description adds crucial privacy context.

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

  Conciseness5/5

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

  Four concise sentences with front-loaded purpose and key information. No redundancy, every sentence adds value.

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

  Completeness4/5

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

  Covers purpose, privacy, and usage guidelines adequately. Lacks mention of return format or error handling, but sufficient for a simple one-parameter tool.

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

  Parameters3/5

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

  Schema description coverage is 100% for the single parameter 'document_id'. Description adds no extra parameter details beyond schema, achieving baseline.

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

  Purpose5/5

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

  Explicitly states 'Returns FULL document content' and specifies usage for reading, summarizing, or analyzing documents. Clearly distinguishes from sibling metadata tools.

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

  Usage Guidelines5/5

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

  Provides explicit when to use (user asked to read/summarize/analyze) and when not to use (finding/organizing, refer to Tier 1 metadata tools).

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

• paperless_get_statisticsA
  4.6/5.0
  Behavior5/5

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

  Description goes beyond the readOnlyHint annotation by detailing the privacy tier and confirming no document content involvement. It lists the specific statistics returned, giving a clear picture of behavior without surprises.

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

  Conciseness5/5

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

  Single sentence, front-loaded with the key privacy tier indicator, followed by a succinct list of what is returned. No extraneous information.

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

  Completeness4/5

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

  Given the tool's simplicity (no parameters, no output schema), the description provides a complete overview of the returned statistics. It lacks explicit mention of return format, but that is standard. Sufficient for an agent to select and invoke correctly.

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

  Parameters4/5

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

  With zero parameters and 100% schema coverage, there is no parameter info to add. However, the description adds value by explaining what the tool returns, which is not evident from the empty schema alone. Baseline is 4 for zero parameters.

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

  Purpose5/5

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

  Description clearly states the tool returns library-wide statistics including totals and breakdowns. It distinguishes itself from sibling tools by explicitly noting 'metadata only' and 'no document content involved', differentiating from document-level tools like paperless_get_document_metadata.

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

  Usage Guidelines4/5

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

  While it doesn't explicitly state when to use versus alternatives, the description implies this is for aggregate statistics and safe metadata queries. The sibling tool names provide context, but more explicit guidance on when not to use (e.g., for document specifics) would improve clarity.

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

• paperless_get_document_metadataA
  4.7/5.0
  Behavior5/5

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

  The description discloses that the underlying endpoint includes OCR content but the tool strips it before returning. This adds behavioral context beyond the 'readOnlyHint' annotation, which is consistent with the safe read nature of the tool.

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

  Conciseness5/5

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

  The description is concise, front-loaded with a critical privacy tier warning, and organized in a clear, readable format. Every sentence adds necessary context without verbosity.

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

  Completeness5/5

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

  Given the tool's simplicity (1 parameter, no output schema), the description fully covers what the tool returns, what it strips, and how to use it. It is contextually complete for an agent to invoke correctly.

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

  Parameters3/5

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

  The single parameter 'document_id' is fully described in the schema with 100% coverage. The description does not add new semantic information beyond what the schema provides, so it meets the baseline with no extra value.

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

  Purpose5/5

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

  The description clearly states the tool returns full metadata for one document and lists specific fields (title, correspondent, etc.). It also distinguishes itself from the sibling tool 'paperless_get_document_content' by noting that this tool strips the OCR content field.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool (for metadata only) and when to use the alternative 'paperless_get_document_content' (if actual text is needed). This provides clear guidance to the agent.

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

• paperless_list_correspondentsA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description adds two behavioral traits: the 'metadata only' privacy disclosure and the case-insensitive filter behavior. No contradictions exist.

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

  Conciseness5/5

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

  The description is extremely concise: a single sentence with a prefix that adds essential privacy context. No unnecessary words or repetition.

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

  Completeness5/5

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

  For a simple list tool with one optional parameter and no output schema, the description fully covers the purpose, returned fields, privacy implications, and filter behavior. It leaves no significant gaps.

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

  Parameters4/5

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

  With 100% schema coverage, the baseline is 3. The description adds the value 'case-insensitive' to the filter parameter, which is not in the schema description, providing meaningful extra context.

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

  Purpose5/5

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

  The description clearly states the tool's action ('list all correspondents'), the specific resource, and the fields returned (id, name, document_count). It is distinct from sibling tools like paperless_list_document_types and paperless_list_tags due to the explicit resource name.

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

  Usage Guidelines4/5

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

  The description provides a usage context via 'PRIVACY TIER 1 (metadata only)', indicating it is safe for privacy-sensitive use. It does not explicitly mention when not to use or contrast with sibling tools like paperless_search_documents, but the context is clear enough.

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