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

Discloses in-memory mutation, no disk write until save_pdf, return formats, coordinate system, and prerequisites. No contradiction with annotations.

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

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

Three paragraphs with front-loaded purpose, efficient behavioral details, and usage guidelines. No redundant sentences.

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

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

Covers preconditions, mutations, errors, return format, and alternatives. With output schema present, return description is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description adds some value (e.g., coordinate origin) but mostly repeats schema info.

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

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

The description clearly states the verb 'append' and resource 'open create_pdf session' and positions it as step 2 of 3, distinguishing it from sibling tools like annotate_pdf.

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 when to use (after create_pdf, before save_pdf) and when not (use annotate_pdf for existing files). Provides clear workflow context.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds that it is read-only and details return JSON structure for each check, going beyond annotations. 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.

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

Two paragraphs, well-organized. First paragraph describes output, second provides usage guidance. No fluff or redundancy. Could be slightly more concise but still efficient.

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

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

Given the tool's complexity (4 parameters, 2 enums, output schema), the description thoroughly covers behavior, return structure, and use cases. Annotations and schema further enrich completeness.

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 baseline is 3. Description adds context by explaining each check value and when compare_path is required. Provides meaning beyond schema enums.

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

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

The description clearly states the tool inspects structural health or conformance, not content. It distinguishes from siblings like read_pdf and extract_text by specifying that it does not read content.

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

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

Explicitly states when to use: verify well-formed, archival-grade, or identical. Also provides exclusions: use read_pdf for titles/author/page counts and extract_text for text. Clear alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that it overwrites the output file, returns JSON with status/error for out-of-range pages or coordinates, and explains the coordinate system. This provides useful context beyond annotations, though it does not detail potential side effects like file locking.

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

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

The description is three sentences plus a brief usage note, conveying all essential information without redundancy. It front-loads the core action and follows with behavior and alternatives, making it efficient and easy to process.

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

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

Given the detailed input schema and annotations, the description covers all necessary context: purpose, behavior, error handling, coordinate system, and alternatives. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Input schema has 100% coverage, but the description adds value by explaining the return format ({status, annotation_type} or {error, code}) and clarifying that width/height only apply to 'highlight'. This goes beyond the schema descriptions, compensating for the high coverage baseline.

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

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

The description clearly states the tool stamps a sticky note or highlight onto an existing PDF page, with specific verb 'stamp' and resource 'page of an existing PDF'. It distinguishes from sibling tools by mentioning manipulate_pdf for page reordering and create_pdf for authoring new PDFs, making the purpose 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 description explicitly states when to use: 'Use this to mark up a document.' It provides clear alternatives: 'To reorder/rotate/overlay whole pages use manipulate_pdf; to author a new PDF use create_pdf.' It also notes that output_path is overwritten, guiding correct invocation.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds detailed return structure per format (JSON with content/format or chunks with index/page_numbers/heading_context), and confirms read-only nature, exceeding what annotations provide.

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

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

The description is concise: two paragraphs. First paragraph covers purpose and return format. Second paragraph provides usage guidelines. No unnecessary words, front-loaded with key information.

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

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

Given 5 parameters (2 required), output schema present, and sibling tools, the description covers all essential aspects: purpose, return format, usage guidance, and behavioral notes (read-only). It is complete and useful for an agent.

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

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

Schema coverage is 100% so each parameter is documented. The description does not add additional parameter-level semantics beyond the schema, but it explains how parameter choices affect output format (e.g., overlap applies only to chunks). This is adequate for the baseline.

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

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

The description clearly states the tool converts a whole PDF to a text representation for LLM use, specifying verb (convert) and resource (PDF). It distinguishes from siblings like extract_text and extract_entities by mentioning alternative use cases.

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

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

Explicitly states when to use this tool ('when you need structure or chunking') and when to use alternatives ('for raw reading text use extract_text; for per-run coordinates use extract_entities'). Provides clear decision guidance.

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

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

Adds significant context beyond annotations: returns session_id/status/page_size, no file written, session in memory with TTL, not idempotent. Annotations already indicate no idempotency, but description adds specific behavioral detail.

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

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

Efficient and well-structured: first sentence states purpose, then return info, then workflow and alternatives. 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?

Covers purpose, workflow, return values, behavioral notes (TTL, idempotency), and alternatives. Adequate for a simple session creation tool with good schema and output schema.

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

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

Input schema has 100% description coverage for all three parameters, so description adds minimal extra meaning. Schema already defines title, author, page_size clearly.

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

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

Clearly states it opens an in-memory PDF building session as the first step of authoring a PDF. Distinguishes from siblings by outlining the workflow and explicitly mentioning alternatives for annotating or filling existing PDFs.

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 workflow (create_pdf → add_pdf_content → save_pdf) and warns against using it for annotating/filling existing PDFs, directing to annotate_pdf or manage_forms.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: output structure (JSON with fields), coordinate system (PDF points, bottom-left origin), and explicitly states 'Read-only.' No contradiction with annotations.

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

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

The description is three sentences: first sentence states purpose, second explains output, third gives usage guidelines. It is concise, front-loaded with key information, and every sentence serves a 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?

The description explains the output structure in detail (JSON with path, entities, entity_count, page_count, and entity fields). Output schema exists but description covers it sufficiently. For a 1-parameter tool, all necessary context is provided.

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

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

Schema coverage is 100% with a clear parameter description in the schema itself. The tool description does not repeat or add significant value beyond the schema's definition of the 'path' parameter. Baseline 3 is appropriate.

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

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

The description clearly states 'Extract every text run of a PDF together with its layout geometry.' It distinguishes from siblings by explicitly naming alternatives: 'use extract_text' for reading text without coordinates, and 'use convert_pdf' for Markdown or RAG chunks.

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

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

The description gives explicit usage context: 'Use this for layout-aware tasks...' and clearly states when not to use it by specifying alternatives, e.g., 'If you only need the reading text without coordinates, use extract_text; for Markdown or RAG chunks use convert_pdf.'

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

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

Even though annotations already mark readOnlyHint=true and idempotentHint=true, the description adds further behavioral context. It states the tool is 'read-only' and describes the return JSON structure ({text, page_count} and 'page' when a specific page is requested). It also mentions that out-of-range page indices return an error. This goes beyond the annotations without contradicting them.

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

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

The description is exceptionally concise: three sentences. The first sentence states purpose, the second describes return format and readonly nature, and the third provides usage alternatives. No filler or redundant information. Every sentence earns its place, and the structure is front-loaded with the core action.

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

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

Given the tool's simplicity (3 parameters, 1 required, simple output schema), the description is complete. It covers return format, error behavior (out-of-range page), and usage context vs. siblings. The output schema exists but the description still explains return fields. All necessary information for correct invocation is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some extra context beyond the schema: it mentions that 'page' parameter accepts a 0-based index and that out-of-range values return an error (already partly in schema but reinforced). It also implies that 'password' is for encrypted PDFs. However, it does not detail each parameter extensively; the schema already does that well. The added value justifies one point above baseline.

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

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

The description clearly states the tool's purpose: 'Extract the raw, unformatted text of a PDF as a single string.' It identifies the verb (extract), resource (raw text of PDF), and output format (a single string in JSON). The title 'Extract plain text' reinforces this. It also distinguishes from siblings by specifying when to use convert_pdf (for Markdown structure) and extract_entities (for coordinates and font). This is specific and differentiates among 12 sibling tools.

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

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

The description explicitly says 'Use this when you want the plain reading text.' and provides clear alternatives: 'if you need Markdown structure or chunking for LLM/RAG pipelines use convert_pdf; if you need each text run with its on-page coordinates and font use extract_entities.' This gives concrete when-to-use and when-not-to-use guidance, making it easy for the agent to select the correct tool.

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

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

The description honestly discloses limitations: 'fill' creates a new overlay rather than mapping onto original AcroForm widgets, 'read' returns text runs not declared AcroForm field objects, and 'validate' only enforces non-empty rule. Annotations already indicate destructiveHint=true, but the description adds valuable context beyond annotations.

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

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

The description is well-structured with a clear overview, return types listed by operation, behavioral details, limitations, and sibling references. Every sentence is informative and earns its place. It is concise yet complete.

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

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

Given the tool's complexity (4 operations, 5 parameters, output schema, annotations), the description covers all essential aspects: return values per operation, side effects (overwriting), limitations, and usage context. No gaps remain for an AI agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds meaningful context: it explains which parameters are required per operation and provides detailed format for 'fields' (e.g., {name, type:'text', x, y, width, height, default_value?}). This goes beyond the schema's minimal descriptions.

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 explicitly states 'Create, fill, read or validate PDF form fields,' clearly identifying the verb (multiple operations) and resource (PDF form fields). It distinguishes from sibling tools like manipulate_pdf and extract_text in the last sentence.

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

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

The description provides explicit guidance on when to use which operation (e.g., 'For page-structure edits use manipulate_pdf; to read prose use extract_text') and notes that 'create'/'fill' write and 'read'/'validate' are read-only. It also explains required parameters for each operation.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false. The description reinforces this by stating it 'overwrites any existing file' and describes return JSON for success and error cases. It adds specific behavioral details beyond annotations, such as the return format and overwrite behavior.

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

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

The description is concise (6 sentences), well-structured, and front-loaded with purpose. Each sentence earns its place: purpose, return format, per-operation requirements, sibling links. No fluff.

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

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

Given the tool's complexity (6 operations, 7 parameters), the description covers all operations and required parameters. It mentions return format, and with an output schema present (context signals), further details are not needed. It is fully adequate.

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

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

Schema description coverage is 100%, so every parameter already has a description. The tool description adds value by grouping parameters per operation in a compact summary, which aids quick understanding of dependencies. This goes beyond the schema by providing operational context.

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

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

The description clearly states that the tool restructures PDF pages and writes new PDFs, listing six specific operations. It distinguishes itself from siblings by explicitly saying 'Use this for page-level structure' and pointing to alternatives for other tasks (annotate_pdf, manage_forms, secure_pdf).

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

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

The description provides explicit when-to-use guidance ('page-level structure') and when-not-to-use with sibling references. It also lists per-operation required parameters (e.g., 'merge→input_paths'), helping the agent decide which parameters are needed for each operation.

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

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

Annotations already declare readOnlyHint and idempotentHint; description reinforces read-only nature, details return object structure, and explains behavior for encrypted files without password. No contradiction.

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

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

Five sentences with clear structure: purpose, return format, read-only emphasis, use cases with alternatives, and edge case handling. No unnecessary 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?

Covers tool purpose, return data, read-only behavior, usage guidance with alternatives, and edge cases. Output schema exists; description complements it fully. No 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 100%, but description adds context: explains include_page_details reduces response size and how password parameter affects output for encrypted files. Adds value beyond 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?

Description clearly states 'Read a single PDF's document-level metadata' with specific verb and resource, distinguishes from sibling tools like analyze_pdf and extract_text, and lists exact return fields.

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

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

Explicitly states when to use ('inspect what a PDF is before deciding how to process it') and when not to (use analyze_pdf for structural validation, extract_text for actual text). Also covers edge case of encrypted files.

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

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

The description discloses key behaviors beyond annotations: overwrites existing file, deletes the session making session_id unusable, and returns JSON {status, path, page_count} or error. Annotations already indicate destructiveHint=true, but the description adds specific details. No contradiction with annotations.

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

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

The description is five well-structured sentences. It front-loads the core action, then explains behavior, return format, constraints, and alternatives. No redundant or extraneous information.

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

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

Given the tool's complexity and available annotations, the description covers all essential aspects: purpose, lifecycle (step 3 of 3), behavior, return values, error handling, prerequisites, and alternatives. It is complete for an agent to understand when and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual meaning: explains that session_id must come from create_pdf/add_pdf_content, that output_path can overwrite, and that encryption only applies when both passwords are provided. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Render an open create_pdf session to a PDF file (step 3 of 3, terminal).' It specifies the verb (render/save), resource (PDF session), and its terminal nature. It distinguishes from siblings by noting that only sessions from create_pdf/add_pdf_content are finalized, and mentions alternative tools for encryption (secure_pdf) and annotations (annotate_pdf).

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?

Explicit usage guidelines are provided: 'Only finalizes sessions created via create_pdf/add_pdf_content.' It also gives when-not-to-use: 'To encrypt an already-saved PDF use secure_pdf; to add annotations use annotate_pdf.' This clearly directs the agent to alternatives and conditions.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false. Description adds detailed behavioral context: encrypt overwrites output_path, rebuilds document and may drop images/embedded fonts/vector graphics. No contradiction with annotations.

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

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

Description is somewhat lengthy but well-structured with clear sections. Front-loaded with operation summary, then output details, then caveats. Slightly verbose but all sentences add value.

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

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

Tool has 6 parameters, output schema exists describing return JSON per operation. Description covers output structure, caveats, and usage alternatives. Complete and actionable 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?

With 100% schema coverage, baseline is 3. Description adds value by explaining which parameters are required for each operation, and the overwriting behavior of output_path. Goes beyond schema descriptions.

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

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

Description clearly states three distinct operations (encrypt, report encryption status, verify signatures) with specific verbs and resources, and distinguishes from sibling tool save_pdf for authoring use cases.

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 when to use each operation, provides caveats about image/font loss for encrypt, and recommends alternative save_pdf for authoring PDFs. Full guidance on when-not-to-use.

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