file-analysis

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

Even with annotations carrying readOnlyHint/idempotentHint/destructiveHint, the description adds substantial behavioral context: only anchors in source_with_anchors are citable, missing required_sections blocks saving, ungrounded_sections need no anchors, and the tool forces the agent to write the draft itself. It also discloses the GR-02 error consequence with preview_save_report — meaningful behavioral detail that annotations cannot convey. No contradiction with the stated read-only, idempotent profile.

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 somewhat long but front-loaded with the core purpose before constraints, and organized into clear sections (purpose, constraints, args, returns, examples). Every sentence earns its place given the tool's complex blocking rules and sibling differentiation needs; the use/not-use examples are especially economical. Slightly heavier than ideal but well-structured for the complexity it must carry.

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 an output schema (BuildPromptResponse) covering the return values, the description properly focuses on usage, differentiation, and constraints. It covers when to invoke, what blocks downstream saving, how anchoring works, and the grade-C fallback path. Nothing an agent needs to call this tool correctly and avoid downstream failures 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 coverage is 100%, so the baseline is 3. The description's Args section largely duplicates schema text (path = file to analyze, start/end = block numbers, end inclusive, None = text length limit). It adds essentially no new meaning beyond the schema — the Args block is a near-verbatim restatement, so it earns the baseline without exceeding it.

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 by stating the tool collects all draft materials at once — template, anchored source text, and table of contents — establishing a clear verb-resource relationship. It further distinguishes itself from siblings by explicitly declaring 'no need to call read_document separately' and clarifying the tool only supplies format and source while the agent writes the draft. This unambiguous differentiation makes sibling confusion unlikely.

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 and when-not-to-use guidance: use it right after receiving an 'analyze this document' request; use read_document when viewing partial text; use read_document_image for grade C documents before drafting. It also specifies downstream blocking consequences (GR-02 for unlisted anchors, save blocked for missing required_sections), giving the agent concrete decision criteria for selecting this tool over alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable limitations: what cannot be verified (meaning, omissions, anchor appropriateness), that GR-05 is only a hint, and that passing the check does not imply correctness. This goes well beyond the structured fields and sets correct expectations.

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 clear headers and bullets, front-loading the core purpose and limitations. It includes useful examples and explicit caveats. It repeats the parameter definitions already present in the schema, which is minor redundancy, but overall it remains efficient and scannable.

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

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

For a read-only validation tool, this description is complete: it states what is verified, what is not verifiable, the meaning of not_verifiable, the normal handling of reworded text, and provides both usage and non-usage examples. The output schema (GroundingResponse) already defines the return structure, so no further details are needed.

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

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

Schema coverage is 100% and both parameters already include meaningful descriptions in the schema (path as 'original file', draft as 'full draft to verify'). The Args section in the description only repeats this information, adding no new semantic meaning. 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 states a specific verb and resource – 'checks whether each sentence of the draft is grounded on original anchors' – and enumerates the four concrete rules (GR-01 to GR-04). This clearly differentiates it from siblings like preview_save_report, which handle saving and approval.

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 provides both positive and negative usage conditions: 'use right after writing the draft, before saving' and 'do not use when a save plan and approval token are needed', naming the alternative tool preview_save_report. This leaves no ambiguity about when to invoke the 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?

Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable context beyond these: it discloses that opening the file costs the same as read_document but saves context, not time, and that it distinguishes scanned vs text PDFs. It doesn't describe pagination or response size details, but the output schema exists and the safety profile is already covered by annotations, so the added disclosure is meaningful.

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 front-loaded purpose ('본문 없이 구조와 확정 등급만 돌려줍니다'), followed by usage guidance, cost disclosure, args, return types, and examples. Every sentence earns its place – the cost disclosure and the scan-vs-text distinction are critical differentiators that an agent needs. The examples section with explicit 사용/사용하지 않음 cases is particularly 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?

Complete for a single-parameter read-only inspection tool. The output schema lists the return fields (grade, rationale, title tree, block count, char count, estimated call count, image-required anchors, format metadata), so the description needn't explain return values further. The cost/context tradeoff, the B? resolution flow, and the scan-vs-text distinction are all covered. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the single path parameter, including that it must be a relative path from scan_folder or an absolute path within root. The description's Args section adds nothing beyond the schema. Baseline 3 is appropriate since the schema carries the load and the description repeats it without adding new semantic detail.

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

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

The description states a specific verb+resource: inspects a document to return only its structure and confirmed grade, without the body text. It clearly differentiates from read_document by emphasizing it is to be called before it, and from scan_folder by explaining that it replaces extension-based 'B?' guesses with a confirmed grade. The purpose cannot be confused with 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?

The description gives explicit when-to-use instructions ('read_document 전에 부르세요'), specific use cases with examples (checking page count/TOC before reading a large PDF, resolving a 'B?' from scan_folder), and a clear when-not-to-use case (when body text is needed, use read_document). Alternatives are named directly, leaving nothing 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?

Annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by stating that paths outside the returned roots are rejected, and clarifies that the response includes limits (file size, scan count) and config file path. This goes beyond the annotations to inform the agent of critical scope constraints, though it does not cover all potential behaviors (e.g., rate limits), so a 4 is appropriate.

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 succinct and well-structured. It opens with the core purpose, immediately follows with a critical usage warning, then lists the return fields, and concludes with concrete usage examples. Every sentence serves a distinct purpose—providing purpose, constraints, return info, or usage guidance—with no redundancy or filler.

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

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

Given the tool has no parameters and an output schema exists, the description is complete. It covers the tool's role, usage constraints, and return contents, while the examples clarify edge cases. The agent has all necessary information to decide when and how to call this tool correctly.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage (trivially). The description compensates by explaining the output structure (roots, extensions, limits, config path), which is useful for understanding the tool's effect. Since there are no parameters to document, the description adds meaning beyond the schema by clarifying the return payload, meriting a 4.

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

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

The description clearly states the tool's purpose: 조회 (retrieve/list) the folders the server can open and the associated limits. It identifies the specific verb and resource, and explicitly differentiates itself from scan_folder by specifying when to use each. The examples further clarify its distinct role as the starting point for all operations.

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

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

The description provides explicit usage guidance: it declares itself as '모든 작업의 출발점' (starting point for all operations), instructs users not to guess paths and to only use paths under roots, and gives concrete scenarios for when to use (e.g., when another tool rejects with PATH_OUTSIDE_ROOT) and when not to (when you already have roots and need a file list, use scan_folder). This fully addresses when and when-not, with a named alternative.

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

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

Annotations already cover readOnly, idempotent, and non-destructive hints. The description adds significant behavioral context: the token is bound to the exact draft content, any edit invalidates it, and the tool prevents saving a different draft after preview. It also discloses overwrite behavior and the need to alert a human, going well 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 lead stating the core purpose and the 'does not write' caveat, followed by crucial token-binding and overwrite warnings, then an Args/Returns/Examples block. Every sentence adds value; it's thorough without being bloated.

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 gate-check tool with an output schema, the description covers all necessary context: the gate logic (structure and grounds checks), token binding, overwrite implications, and usage timing. It distinguishes from the sibling that covers grounds only, and the return type is mentioned. Nothing critical is missing for an agent to use 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 already describes both parameters (path and draft) fully, so the baseline is 3. The description adds meaningful context about the draft parameter—namely that the token is sensitive to any change in its content, which affects how the agent should treat it. It also clarifies path as the original file, matching the schema but reinforcing usage.

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: it verifies that a draft passes the save gate and issues an approval token, explicitly noting it does not write. It distinguishes itself from siblings by naming check_summary_grounding as the alternative for when only grounds are needed, and the context implies it precedes save_approved_report.

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 usage guidance: use it after passing grounds comparison and right before saving; do not use it when only grounds are needed, pointing to check_summary_grounding. It also warns about overwriting and instructs to inform a human first, covering both when-to-use and 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds rich behavioral context: the unified interface flattening all formats to a 1D block list, the 'unit' field clarifying block semantics per format, the grade C null-text signal and how to interpret it, and the anchor-citation contract for grounding. No contradictions 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 front-loaded with the core purpose and key behavior (anchors + range), uses bold labels and bullet-style separators for readability, and includes examples without padding. Every sentence earns its place—no fluff or repetition of schema fields.

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 an output schema exists (ReadDocumentResponse), the description doesn't need to detail return structure—it summarizes the key fields. It covers edge cases (grade C), cross-tool interactions (inspect_document, read_document_image, check_summary_grounding), and parameter semantics. For a tool with 3 params and rich sibling relationships, this is fully complete for correct invocation.

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

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

Schema coverage is 100% and each parameter has a description, so the baseline is 3. The description adds practical meaning beyond the schema: it explains the block concept (via 'unit'), gives a concrete example mapping 'PDF 3~8 pages' to start=3,end=8, and clarifies that end omitted reads to a character limit. This elevates it above the baseline.

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

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

The description states a specific verb (read) and resource (document body) with a key qualifier (citation anchors), and explicitly distinguishes itself from siblings: 'inspect_document' for metadata-only needs and 'read_document_image' for grade C files. An agent can immediately tell what this tool does and why it exists.

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 'when to use' (reading content with anchors), 'when not to use' (inspect_document for page count/title, read_document_image for grade C), and even explains the downstream dependency on check_summary_grounding that requires anchors. This leaves zero ambiguity about selection 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?

Beyond annotations (readOnly, idempotent), the description discloses that it returns binary data (the only tool to do so), resizes images to 1568px on the long side, and warns that the read content is not a direct quote, requiring the '(이미지 판독)' marker. It also describes error behavior for vector-only pages, providing rich behavioral context.

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

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

The description is well-organized with clear sections (intro, args, returns, examples). The core purpose is front-loaded in the first sentence, and each subsequent sentence contributes essential details (format, resizing, usage, return) without redundancy. It is appropriately sized for the tool's 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?

With no output schema, the description compensates by explaining the return format (a list with image and guidance string) and noting it deviates from structured responses. It covers error cases for vector-only pages, provides usage examples, and explains how to handle the result in summaries, making it complete for an agent to call correctly.

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

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

The schema already provides complete descriptions for both 'path' and 'page' (100% coverage), including the note that page is ignored for png. The description only paraphrases these, adding no new semantic meaning beyond the schema's existing clarity, so it meets the baseline but does not exceed it.

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 it reads documents without text as images, with a specific verb ('직접 판독합니다') and resource ('텍스트가 없는 문서'). It distinguishes itself from the sibling 'read_document' by explaining it is for images/scanned PDFs and specifically for grade C files, making its 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?

Explicit usage guidance is provided in the Examples section: use when 'read_document' returns grade C, and do not use for grade A/B files, where 'read_document' is more accurate. It also explains when it is applicable (scanned PDFs, embedded images) and when it is not (vector-only pages).

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?

Goes far beyond the destructiveHint/readOnlyHint annotations: discloses that it re-validates all gates independently of the preview, specifies failure codes (DRAFT_NOT_CLEAN, APPROVAL_TOKEN_MISMATCH), explains overwrite behavior, and reveals the append-only audit log that preserves prior hashes and never modifies/deletes existing records. 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?

Front-loaded with the most critical facts (only write tool, approval required), then proceeds through gate re-checking, overwrite/audit behavior, and closes with a valuable use/don't-use Examples section. Every sentence earns its place; the length is justified by the destructive nature of the 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?

Complete for a destructive write tool: it ties into the preview_save_report workflow, states approval requirements, error conditions, overwrite and audit semantics. An output schema (SaveResponse) exists so return values need no elaboration, and allowed roots are covered by the list_allowed_roots sibling. Nothing essential is missing.

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

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

Schema description coverage is 100%, with all three parameters already well documented, including the constraint that draft must exactly match what was passed to preview_save_report. The description's Args section largely mirrors the schema, adding little new meaning, so the baseline 3 applies — the schema carries the burden.

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 ('output_root') and explicitly positions itself as the only write tool on the server, clearly distinguishing it from its read-only siblings including the paired preview_save_report. An agent immediately understands what this tool does and how it differs.

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

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

Provides explicit when-to-use guidance ('only after the user has explicitly approved', approval is human-only) and when-not-to-use examples (preview BLOCKED, or continuing without approval). Clarifies that a READY preview is not permission to save — it only means the gate was passed — which directly prevents misuse.

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

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

Annotations already cover read-only and non-destructive behavior, but the description goes beyond them by disclosing that it does not open files, uses stat info only (hence fast), cannot distinguish scanned vs text PDFs, and that truncation occurs when total_matched != returned. These are non-obvious behaviors an agent needs to know to interpret results correctly.

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 clear sections (Args, Returns, Examples) and front-loaded with the primary purpose and speed caveat. It is slightly longer than strictly necessary, but every sentence contributes either to usage guidance or behavioral transparency. The use of bold and code formatting aids readability without padding.

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 an output schema present, the description correctly focuses on when to use, limitations, truncation handling, and sibling routing. It covers all operational concerns an agent would have: speed, PDF-type ambiguity, pagination/truncation, and path conventions. Nothing critical is missing for correct invocation.

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

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

The input schema already documents all three parameters with full coverage (100%). The description does not add new semantic value beyond restating parameter purposes; it does give usage context for extensions (optional filter) and the folder default, but these are also in the schema. This matches the baseline for high 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 ('list') and resource ('documents in a folder'), and immediately distinguishes itself from siblings by noting it does not open files. It also clarifies it only reads stat information, which sets it apart from inspect_document. This is a clear, non-tautological purpose statement.

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

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

The description provides explicit when-to-use ('what's in this folder?' before selecting analysis targets) and when-not-to-use (when page count or title structure is needed → inspect_document). It also gives a conditional routing rule: if expected_grade is 'B?', use inspect_document. This is comprehensive usage guidance with named alternatives.

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