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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds real behavioral context on top: confidence is a model probability and null means unknown, not low, and pages_needing_vision flags pages whose text layer is missing so nothing returned for them is real content. It also discloses the page-limit behavior and the furniture default.

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 result shape, then block fields, then the caveat, then Args; each part is useful. The block-field enumeration is long but earns its place because the output schema's field meanings are otherwise opaque; minor trimming possible but nothing is 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?

Even though an output schema exists, the description explains the non-obvious field semantics (confidence nullability, bbox origin, span fields) and the pages_needing_vision caveat, which the schema cannot. For a 3-param, closed-world read tool, 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 coverage is 0%, so the description must carry all parameter meaning, and it does: path is the absolute path on this machine, pages is 0-based with omit-meaning-whole-document and the server limit, and include_furniture is explained with the rationale for its false default. This fully compensates for the undocumented schema.

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

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

States a specific verb and resource ('A local PDF as blocks, in reading order') with provenance per block, so the agent knows exactly what comes back. It does not contrast itself with siblings like extract_text or extract_markdown, which repeat the same 'extract from PDF' framing, so the boundary is left to inference.

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

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

Usage context is implied rather than stated: 'local PDF', 'reading order', and the default exclusion of furniture give hints, and it explains the page-window and server page limit. But there is no explicit when-to-use-this-vs-extract_tables/extract_markdown guidance, which is exactly where an agent stands when choosing among the eight siblings.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds valuable non-obvious behavior: the whole document is read even when a page subset is requested, running heads and page numbers are dropped, and a server page limit exists. Return shape is partly deferred to the output schema.

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

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

Purpose is front-loaded in the first sentence, then formatting behavior, then a structured Args block. The markdown-conversion paragraph is slightly long but each clause (headings, lists, tables, page comments, running heads) conveys real behavior.

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?

An output schema exists, so return values needn't be spelled out, yet the description still explains the markdown structure well enough to interpret results. The one gap is guidance on sibling selection (extract_text vs this tool) for a task that overlaps with several siblings.

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 0% schema description coverage, the description must carry all parameter meaning, and it largely does: path is an absolute local path, pages are 0-based with omit-for-all semantics and a server page limit, and quality's two valid values are named with their meaning. It could be clearer on default pagination fallback when pages exceeds the limit, but coverage is strong.

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 (extract) and a precise output format (markdown, reading order) with a clear resource (local PDF). It implicitly differentiates from extract_text/extract_tables by naming its output as reading-order markdown, though it never names those siblings directly.

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

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

The args section says to omit pages for the whole document and explains when quality='balanced' applies (models installed), which implies usage conditions. But there is no explicit guidance on when to choose this tool over extract_text, extract_tables, or extract_blocks, all present as siblings.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context such as the absolute-path requirement, the server page limit, and the output structure including header rows and spanning-cell 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 front-loaded with the tool's purpose and is organized into output-shape details followed by an Args section. It is somewhat longer than necessary given the output schema, but the extra detail about table structure and spanning cells earns its place.

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

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

For a two-parameter, read-only extraction tool with an output schema, the description covers the essential purpose, both parameters, page scoping, and non-obvious table semantics. It does not address edge cases such as scanned PDFs or encrypted files, but those are secondary for this 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 description coverage is 0%, so the description must carry parameter meaning, and it does: `path` is defined as an absolute local path, and `pages` as 0-based pages to inspect with omission meaning the whole document. The only minor gap is that the actual server page limit is not stated.

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 this tool returns tables from a local PDF as rows of cell text, which is specific enough to distinguish it from text or markdown extraction in practice. However, it does not explicitly name or contrast the sibling tools, so it falls short of the top score for sibling differentiation.

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

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

The tool's usage is implied by its table-focused purpose, and the description explains that `pages` can be omitted to process the whole document. It does not explicitly say when to use this tool instead of `extract_text`, `extract_markdown`, or `extract_blocks`.

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 closed-world access, so the safety profile is covered. The description adds useful behavioral detail: page delimiters use ``<!-- page N -->`` with 0-based numbering, scanned pages return nothing, and output is capped by the server's page limit. It doesn't state the actual limit, which is the only real gap.

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

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

The tool's purpose and its key distinction from extract_markdown come first. Each later sentence carries necessary information: the page-marker format, the routing for scans, and the parameter meanings. Nothing is wasted.

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?

An output schema exists, so the description needn't explain return values. It still documents the page-marker delimiters that structure the output, which is the one detail an agent needs. With every parameter covered and the sibling alternatives named, nothing needed for correct invocation 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 0%, so the description has to explain the parameters, and it does. 'path' is documented as the PDF's absolute path on this machine, and 'pages' as the 0-based page numbers to return, omit for the whole document. That adds meaning the schema does not capture.

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

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

The description gives a specific verb and resource: the plain-text layer of a local PDF, page by page. It also names the sibling it is not ('use extract_markdown for that'), so an agent can distinguish it from extract_markdown and extract_blocks without opening their schemas.

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

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

It states both when to use it and which alternative to use instead: 'No reading-order repair and no structure: use extract_markdown for that.' It also routes the agent to get_metadata for pages with no text layer that are probably scans.

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 the annotations, the description discloses key behavioral constraints: the input PDF is never changed, `out_path` must be inside an allowed root, must not already exist unless `overwrite` is true, and symlinks are refused. It also explains partial success behavior—only `set` fields are written, `unknown` fields are named, and nothing is written when no field is set.

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 action, then adds behavioral constraints and a compact Args section. Every sentence earns its place by covering a distinct rule or parameter, with no filler.

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

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

For a four-parameter mutation tool that writes files and has an output schema, the description covers the essential preconditions, partial-success behavior, and safety constraints. Nothing an agent needs in order to call it correctly appears to be 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?

Although the schema has 0% description coverage, the description fully documents all four parameters. It explains `path` and `out_path` as absolute paths, maps `values` to field names with the exact value types expected (string, list of strings for multi-select), and clarifies `overwrite` semantics.

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

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

The description opens with a specific verb and resource: 'Fill the form fields of a local PDF and write the result to a new file.' It clearly distinguishes this from sibling extraction tools and from list_form_fields by naming the latter as the source of field names.

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 a clear usage context by tying `values` to field names from `list_form_fields`, implying the need to discover fields first. It does not explicitly name alternatives or when-not-to-use cases, which keeps it from a 5.

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 safe, read-only, idempotent nature of the call. The description adds meaningful behavior beyond that, especially the special case where password-protected documents return only 'encrypted: true' and 'needs_password: true'.

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 a clear purpose and then moves into useful field semantics. It is somewhat longer than necessary because an output schema already exists, but the field-specific details such as 'pages_needing_vision' and encryption behavior earn most of the space.

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

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

For a simple one-parameter metadata tool with annotations and an output schema, the description is complete enough to call correctly. It covers the required path semantics and the important encrypted-document edge case.

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 has 0% description coverage, and the description fully compensates by explaining that 'path' is the PDF's absolute path on the local machine. This is the only parameter and its key constraint is stated 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?

The description clearly defines the tool as returning metadata about a local PDF before reading/extracting it, and the field list makes the resource scope concrete. It distinguishes the tool from extraction siblings by framing it as a pre-read inspection step.

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

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

The phrase 'before reading it' implies when to use the tool, but no sibling alternatives are named and there are no explicit when-not-to-use conditions. The guidance is inferable 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds semantics the annotations cannot: the enumerated field types, 0-based page indexing, null when a field has no page widget, and that an empty list means no AcroForm exists — all behaviorally useful. It omits failure modes (encrypted or malformed PDFs), which keeps it off a 5.

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

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

The purpose is front-loaded in the first line, then the return-shape details follow in a compact block. The field-by-field prose partly duplicates an existing output schema, but each clause still carries meaning (0-based pages, fully qualified names), so there is little true waste.

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

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

For a one-parameter read tool with annotations and an output schema, this covers what an agent needs: what it returns, what empty means, and the absolute-path requirement. The remaining gap is routing — no statement of when to prefer this over get_metadata or the extract_* siblings.

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

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

Schema coverage is 0% — the single `path` property has no description at all — so the description must compensate, and it does by specifying 'the PDF's absolute path on this machine', which tells the agent a relative path is insufficient. That is the one constraint an agent could plausibly get wrong, so the gap is adequately filled.

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

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

States the resource precisely — the interactive form fields of a local PDF — and ties it to the sibling fill_form by noting the name is what fill_form takes. It is phrased as a noun fragment rather than a verb ('list'), and it does not explicitly distinguish itself from get_metadata or the extract_* siblings, but the resource is unambiguous.

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

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

Usage is only implied: the mention that `name` is the fully qualified name fill_form consumes hints at the inspect-then-fill workflow. There is no explicit guidance on when to choose this over get_metadata or extract_* tools, and no stated prerequisites such as the file needing to exist or be unencrypted.

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 establish the tool as a safe read-only, idempotent operation, and the description adds important behavioral detail: matching is case-insensitive on the text layer, scanned pages cannot match, and snippets are limited to the first twenty matching pages. This is substantive context beyond the 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 behavior and then adds precise output and matching details. Every sentence contributes useful information without repetition or 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?

Given the simple two-parameter schema, rich annotations, and the existence of an output schema, the description is complete. It covers what is searched, matching limitations, snippet limits, and the downstream extraction workflow.

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

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

Schema description coverage is 0%, so the description must explain parameter meaning, and it does: path is the PDF's absolute path on this machine, and query is the text to look for as written. It lacks syntax or format edge-case guidance, but both required parameters are meaningfully documented.

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: searching a local PDF's pages for a query and returning snippets. It distinguishes itself from extraction siblings by describing a search/match operation rather than full-document extraction.

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

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

It gives a clear usage context by explaining that snippets help an agent decide which pages to read in full with extract_markdown. It does not explicitly contrast itself with extract_text or other siblings, but the intended workflow is clear.

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 establish read-only and idempotent behavior, and the description adds a genuinely useful caveat: only `no_text_layer` is currently measured, while `low_confidence_table` and `figure` are always false. It does not mention cost or whether pages are rendered, which would be nice but is secondary.

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

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

Front-loaded with the core question and tight overall. It spends a few lines explaining output fields that the output schema already covers, which is slightly redundant but does convey the caveat that two of the reasons are stubs.

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-only tool with an output schema, the description supplies what is missing: parameter format, what 'needs_vision' means, and the current measurement limitation. Only the absence of routing guidance against sibling extraction tools keeps it from being fully complete.

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

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

Schema coverage is 0%, so the description must carry the parameter — and it does, specifying that `path` is an absolute path on the local machine, which prevents relative-path or URL attempts.

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 purpose: identify which pages of a local PDF warrant a vision model, and why. It is clearly an analysis/advisory operation, distinct from the extract_* siblings, though it never names them explicitly.

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

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

Usage is implied — call it when deciding whether to route pages to a vision model — but there is no explicit when-to-use/when-not guidance or reference to alternative tools such as extract_text or extract_tables that might already cover a page.

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