file-analyzer-mcp

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description exceeds this by disclosing the recursive behavior, the effect of max_depth and max_entries limits, and the truncation flag in the response. This is useful behavioral context beyond what annotations convey, although it does not detail error handling or performance 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 a usage-oriented introduction followed by explicit Args and Returns sections. It front-loads the purpose and usage guidance, then gets into parameters. It is efficient and not bloated, though the Korean text is slightly verbose in listing parameter behaviors already present in the schema.

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

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

For a tool with an output schema, the description does not need to explain return types in detail; it still summarizes the key fields (tree_text, extension_stats, truncated). It also covers the main execution limit (truncation) and instructs the agent on the next step. Missing any explicit error-handling or prerequisites, but given the annotations and schema, this is adequately complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning. The description restates these meanings with slightly more operational context (e.g., '트리 최대 깊이 (기본 5)' vs the schema's '트리를 내려갈 최대 깊이'). No additional syntax or format details are added. Per guidelines, baseline is 3, and the description does not meaningfully exceed that 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 uses a specific verb ('recursively scans') and resource ('folder'), and clearly states the output (tree and per-extension statistics). It also frames itself as the starting point for file analysis, which distinguishes it from the sibling read_* tools that operate on individual files. The purpose is unambiguous and immediately scoped.

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 tells the agent when to use this tool ('starting point for file analysis') and how to proceed afterward: 'after first grasping folder scale, use list_supported_files to extract only actually readable files.' This routes the agent to the correct sibling for follow-up, providing clear when-to-use guidance and 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds useful behavioral details: it filters by extension, returns a specific response type with relative_path/absolute_path/extension/bytes, and mentions recursion depth and entry limits. It also explains that the returned paths are meant to be passed to sibling read tools, which is valuable context not in annotations. 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 compact: a purpose sentence, an integration hint, then a concise Args/Returns section. It avoids fluff and front-loads the core purpose. The Args/Returns format is standard and scannable. Slight redundancy with the schema (defaults repeated) but not wasteful. Good structure for an agent to parse.

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

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

Given the tool's moderate complexity (3 params, output schema present), the description covers the essentials: what files are included, what the output contains, and how to consume the output. The output schema likely details the response structure, so not explaining return values in detail is fine. The main missing piece is a note about error handling or edge cases (e.g., inaccessible folders), but that's minor for a list 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 the description doesn't need to explain all parameters, but it adds context beyond the schema: it explains max_depth and max_entries in the context of traversal (max depth and max files/folders to explore), and describes the return fields. The line '각 항목의 absolute_path를 ... 그대로 넘기면 됩니다' adds integration guidance. This adds meaning beyond the schema's basic parameter 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: it filters a folder for specific file types (pdf/docx/pptx/svg/png) and returns a list of paths. The verb 'list' is specific, the resource is 'supported files within a folder', and the file types are enumerated. It also distinguishes itself from siblings like read_pdf/read_docx by noting it returns paths to pass to those readers, and from analyze_folder_structure by focusing on supported file types rather than general structure.

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

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

The description tells the agent to pass the absolute_path values from the result to the read_* tools, which is a clear usage directive. It doesn't explicitly say when NOT to use it (e.g., when you need all files regardless of type), but the context signals and sibling list imply alternatives. The guidance is present but could be more explicit about when to choose this over analyze_folder_structure.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral details such as the max_chars truncation, the extraction of text/headings/tables, and the specific error conditions (PATH_NOT_FOUND, FILE_TOO_LARGE, etc.), which go beyond the annotations and provide valuable runtime 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-organized with clear sections (purpose, limitation, args, returns, raises) and is front-loaded with the core action. While slightly verbose, every sentence is informative and earns its place, making it concise for the amount of context provided.

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

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

Despite having an output schema, the description still explains the return structure (ReadDocxResponse with text, headings, tables) and enumerates all possible errors. Combined with the fully documented parameters and annotations, nothing essential is missing for an agent 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?

Schema description coverage is 100%, so the schema already documents both parameters. The description repeats the parameter meanings (file_path: docx 파일 경로, max_chars: 본문 최대 글자 수) without adding new details, making this a baseline score.

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 ('Word(.docx) 문서의 본문 문단, 제목, 표'), clearly distinguishing it from sibling tools like read_pdf and read_pptx by naming the exact file format. It also explicitly excludes .doc, making its scope 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 provides a clear usage context: it is for .docx files only, and specifically instructs the agent to convert .doc files before retrying. It does not compare against alternative readers, but the format-specific guidance is enough to direct correct usage.

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 carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing the return structure (list of [metadata, image content]), the metadata fields (width/height/mime_type), the explicit non-summarization behavior, and the specific ToolFailure error codes. 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 front-loaded with the core purpose, then delivers the critical behavioral caveat (no summarization) before structured Args/Returns/Raises sections. It is well organized with minimal wasted text, though the error-enum listing adds modest length without deep explanatory 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?

For a single-parameter read tool with no output schema, the description covers purpose, parameter, return format with metadata fields, caller responsibility, and error codes. The only notable gap is that FILE_TOO_LARGE implies a size threshold that is never specified, but overall this is reasonably complete for its low complexity.

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

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

Schema description coverage is 100% (file_path is documented as '읽을 .png 파일 경로' in the schema). The description restates the parameter nearly identically without adding format, constraints, or usage nuances beyond the schema. Baseline 3 is correct when the schema carries the full parameter documentation.

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 (PNG image), and explicitly clarifies what it does NOT do (summarize the image), which separates it from document-reading siblings like read_pdf and read_docx. The purpose is unambiguous and self-contained.

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

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

The description implies usage context through the file-type distinction among siblings (read_pptx, read_pdf, read_svg) and clarifies that the caller must do the summarizing. However, it never names an alternative tool or gives an explicit when-to-use/when-not-to-use condition, leaving the routing to inference from the file extension.

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?

Discloses the default 30-page cap, the truncation detection method (total_pages vs end_page), OCR slowness, return structure (ReadPdfResponse with pages, text_source, likely_scanned), and specific error types (PATH_NOT_FOUND, FILE_TOO_LARGE, etc.). Adds meaningful context beyond the readOnly/idempotent annotations and covers operational nuances.

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?

Well-structured with clear sections: purpose, usage advice, Args, Returns, Raises. Front-loaded with purpose and usage guidance. Every sentence contributes value; no filler or redundancy. The length is justified by 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?

Covers input (file_path), pagination behavior, OCR details, return value structure, and error conditions. The presence of an output schema and complete parameter descriptions means nothing essential is missing. An agent can invoke the tool correctly with this description alone.

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 covers all 5 parameters with descriptions (100% coverage). The description adds behavior beyond the schema: the default page_end cap of 30, the OCR slowness warning, and the guidance to re-call with ocr=True when likely_scanned. This supplements the schema with practical usage details.

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 (extracts), resource (PDF), and scope (page-by-page text). Distinguishes from sibling tools like read_pptx and read_docx which handle different file formats. The purpose is unambiguous and directly actionable.

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 instructs using page_start/page_end for long PDFs to save context and explains the default 30-page limit with truncation detection via total_pages vs end_page. Also advises calling with ocr=True when likely_scanned is true. Does not explicitly contrast with sibling tools, but the file-type difference is implied and the guidance is concrete.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds substantial behavior beyond that: the default 60-slide cap, the extraction of speaker notes, the expected response structure (slides[] with slide_number/title/text/notes), and specific ToolFailure codes (PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION). This informs the agent about limits and failure modes that annotations do not convey.

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

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

The definition uses well-organized Google-style sections (purpose, constraint, Args, Returns, Raises) with front-loaded purpose and zero filler. The Args section is somewhat redundant with the schema's own descriptions, which slightly reduces the efficiency score.

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?

Since an output schema exists and the description separately explains the slides[] return shape, return values are doubly covered. Parameter meanings are in the schema, the .ppt limitation is disclosed, error codes are enumerated, and the default range behavior is stated — nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description's Args section restates parameter meanings (file_path path, slide_start default 1, slide_end default up to 60) that the schema already documents, adding marginal value beyond reinforcing defaults.

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

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

The description states a specific verb and resource: 'PowerPoint(.pptx)에서 슬라이드별 제목, 본문, 스피커 노트를 추출한다' (extracts title, body, speaker notes per slide). It explicitly names the .pptx format, which distinguishes it from sibling tools that target other formats (read_pdf, read_docx, read_svg, read_image).

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?

Clear usage context is provided: the .ppt exclusion ('옛 형식(.ppt)은 지원하지 않습니다') serves as a when-not, and the guidance to paginate large presentations via slide_start/slide_end is actionable operational direction. However, it does not explicitly name sibling alternatives (e.g., 'use read_pdf for PDF files'), so routing is implied by format naming rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: it explicitly states that the tool does not rasterize vectors (a critical non-destructive behavior), lists the specific output fields (element_counts, text_content, title/description), and enumerates possible failures (PATH_NOT_FOUND, NOT_A_FILE, etc.). This fully discloses operational behavior without contradicting 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 clear sections (Args, Returns, Raises) and a concise note on rendering limitations. It is not overly verbose, and the core purpose is stated first. The only minor inefficiency is the redundancy of repeating file_path in Args when the schema already documents it, but overall the structure is 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?

Given the tool's simplicity (one parameter) and the presence of an output schema (ReadSvgResponse), the description is exhaustive. It covers the input, output fields, potential error conditions, and a key behavioral limitation. Including the Raises section ensures the agent knows what failures to anticipate. Nothing essential is missing for correct invocation and interpretation of results.

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

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

There is only one parameter (file_path) and the input schema already provides a full description ('읽을 .svg 파일 경로'), giving 100% schema coverage. The description repeats the same information in the Args section without adding new semantics like format constraints or examples. Since the schema carries the burden, a baseline of 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 it extracts SVG size, per-tag structure statistics, and text elements. The verb '추출한다' (extracts) plus the specific resource (SVG) makes the purpose precise and distinct from sibling tools like read_pdf or read_docx, which target different formats.

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 explains that SVG is XML and can be understood without rendering, and importantly notes that it does not rasterize vectors, so diagrams with little text can only be gauged via element_counts. This gives strong context for when to use the tool and what limitations to expect, though it does not explicitly name alternatives or state when not to use it. The context is sufficient for an agent to decide appropriately.

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