FynePDF

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful context beyond that — 'say once' signals a one-shot report consistent with idempotency, and 'for diagnosis' frames the intent — but it does not disclose whether the report is stored, what the caller should expect back, or any rate/one-call constraints.

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 very short sentences with no filler, so it is certainly concise. But brevity here tips into under-specification: the key scoping statement ('Not for conversation') is a fragment placed last, and the opening sentence is oblique about the actual 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. What is missing for an 11-parameter diagnostic tool is any account of what the diagnostic payload is for or how a caller should populate it, leaving the agent able to identify the tool's role but not to invoke it confidently.

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?

Eleven parameters with only 55% schema description coverage, and the description adds nothing about any of them — not the required 'app' and 'bridge' enums, not the diagnostic fields like trace/phase/frame. Since coverage falls below the 80% threshold, the description was expected to compensate for the undocumented parameters and does not.

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 conveys that this is a diagnostic channel through which in-chat cards report which host bridge they run in, and it distinguishes itself from the PDF-manipulation siblings by declaring it is 'not for conversation.' However, it never states a concrete verb for what the tool does with the report (records it? returns it? registers the card?), so the action itself remains vague.

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?

'For diagnosis. Not for conversation.' provides a rough when-to-use and when-not-to-use pair, which is more than most descriptions offer. But no alternative tool is named for conversational needs (e.g. ask_pdf), and no prerequisites or call conditions are given, so the routing guidance is implied rather than explicit.

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, non-destructive, idempotent behavior. The description adds meaningful behavioral detail: answers are grounded in the document, pages are cited, and 'verified: false' marks quotes that could not be found in the page text.

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 sentences, front-loaded with the core purpose, with zero waste. The second sentence efficiently explains the quote-verification semantics.

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, annotations cover safety semantics, and the schema documents file selection well. The description supplies the core behavior and verification detail; it could clarify sibling alternatives or single-document scope, but 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 80%, and the schema itself distinguishes file, file_id, file_url, and library_file_id. The description adds no parameter-level meaning beyond what the schema already provides, so the 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 uses a specific verb ('Answer a question') and resource ('the document'), and adds grounding/citation scope. It does not explicitly name how it differs from siblings such as summarize_pdf or search_docs, so it is clear but lacks 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?

It implies grounded document Q&A and constrains answers to the document only, but gives no explicit when-to-use/when-not guidance or alternative tool recommendation. The usage context is implied 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 the safety profile (not read-only, not destructive, not idempotent, closed-world), so the description's burden is lighter. Its only added behavioral signal is "The result says whether the target was met," which usefully warns that compression can miss its goal, but the description never says whether output is a new file or an in-place replacement, nor what happens with conflicting level/target inputs.

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 short sentences, front-loaded with the operation and immediately followed by the parameterization modes. No filler, no restatement of the title.

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 need not explain return values or the target-met flag, and it wisely does not. What is missing is the multi-source file input story and the interaction between the two compression modes, which matters for a six-parameter tool with a nested file object.

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 67% schema coverage, the baseline is 3; the schema itself documents file, file_id, file_url, and library_file_id. The description reinforces the level enum and the MB unit for target_size_mb but adds nothing about the three alternative file-input paths (attachment, FynePDF file_id, public URL, library file) or about precedence between level and target_size_mb.

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 ("Make a PDF smaller") and names the two operating modes, so the agent knows immediately what the tool produces. It does not name or contrast with any sibling, though none of the listed siblings (merge, split, ocr, protect) are plausibly confusable with compression.

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 "at a level (low, medium, high) or under a target size in MB" implies the two usage modes, but it never says when to prefer one over the other, whether they can be combined, or what happens if both are supplied. There is no explicit when-to-use or when-not-to-use guidance against 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 declare non-read-only, non-idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds genuine behavioral context: that table extraction is page-scoped and heuristic, that images come bundled in a ZIP rather than loose files. It does not say whether conversions are async, size-limited, or credit-consuming.

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 sentences, front-loaded with the core action and formats, then the routing rule to extract_data. The format enumeration is long but each gloss carries information not evident from the bare enum, so little 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 return values need no explanation, and the safety profile is in annotations. However, a 7-parameter conversion tool with four interchangeable-looking input sources and likely async job handling (get_job sibling) leaves an agent guessing on file-source selection and dpi applicability.

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 57%, so the description must fill gaps and only partly does: it expands the 'to' enum values (archival PDF/A, grayscale PDF, images as ZIP/PNG/JPEG), which helps pick an enum member. It says nothing about dpi, image_format, or the precedence between file, file_id, file_url, and library_file_id.

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 (turn) and resource (a PDF) plus the full set of output targets, glossing each format ('PDF/A (archival)', 'images (PNG/JPEG in a ZIP)'). It also explicitly separates itself from extract_data, so an agent can pick correctly without opening either schema.

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 names the alternative extract_data and the exact condition that selects it ('tables read by AI, scans, bank statements'), and implicitly contrasts with convert_to_pdf through directionality. It gives no guidance on choosing among the four file-input parameters or on when an async job lookup is needed.

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=false, openWorld=true, idempotent=false, so safety profile is known. The description adds useful behavior ('images one page each, in order') but says nothing about processing latency, job polling (get_job exists), or failure modes for a non-idempotent conversion.

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 sentences, zero filler, with the capability statement front-loaded and the disambiguation as a trailing clause. Every sentence 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?

An output schema exists, so return values needn't be described, and the annotations carry the safety profile. The remaining gap is that a six-parameter, zero-required-input converter doesn't hint at which input field to pick or that conversion may be asynchronous.

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 adds only the meaning of 'url' as a public web page and the ordering semantics for images; it doesn't clarify the three overlapping file-input modes (files, file_ids, file_urls) or library_file_id.

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 ('Make a PDF') and enumerates supported input types (Word/Excel/PowerPoint, images, EPUB, web page). It also names the sibling it differs from (create_pdf), so the agent can distinguish it without opening 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?

Explicitly routes self-authored content to create_pdf, which is the main ambiguity for this tool. It doesn't mention the inverse tool convert_from_pdf or when a library/URL file should be preferred, but the usage context 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 only declare the mutation profile (readOnly=false, idempotent=false, destructive=false), so the description carries real weight and delivers: supported markup features (tables, headings, lists, URL images, page breaks), optional header/footer/page numbers, and the notable behavior that invoice totals are computed when omitted and validated when supplied. It does not mention failure modes, size limits, or what happens on arithmetic mismatch beyond 'checked'.

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-loads the core capability in the first clause, then layers the invoice/resume/letter shortcut and the usage trigger. The long parenthetical about amounts is dense but earns its place; the prose is slightly sprawling and could be trimmed without loss.

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 11 parameters, low schema coverage and an output schema (so return values need no explanation), the description covers the decisive paths well: content mode, structured-data mode, template matching and invoice math. Missing guidance on the styling/layout parameters is the only substantive gap for a tool this flexible.

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 only 27%, so the description must compensate, and it does so for the most consequential parameters: the markdown/html vs `data` choice, the need to set `template` to match, and the leave-out-or-supply rule for amounts, subtotal, tax and total. However `style`, `margin`, `page_size`, `page_numbers`, `header`/`footer` are never explained, leaving several layout parameters to bare enum values.

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 — turning authored Markdown/HTML (or structured fields) into a laid-out PDF, naming concrete document types (report, invoice, letter, resume). It implicitly separates itself from file-conversion siblings by emphasizing content 'you write', but never names convert_to_pdf or convert_from_pdf, so the sibling boundary is inferred rather than stated.

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?

Gives a clear routing rule: for invoice, resume or letter, prefer `data` with a matching `template`, because layout and arithmetic are handled. It also states the trigger condition ('whenever the person wants a document they can download, print or send') and a handoff from extract_data. It stops short of any explicit when-not-to-use or alternative-tool exclusion.

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 two non-obvious behaviors: pages are 1-indexed, and in reorder mode any page left out is dropped (a data-loss consequence the agent must warn about). It does not mention whether the source file is preserved or what the output is, but the annotations plus output schema cover part of that.

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?

One front-loaded sentence with the resource and indexing rule first, then the operations. The nested parentheticals get slightly dense, but no clause is filler — each maps to a distinct operation.

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 an 8-parameter, 4-mode tool with a nested file object and an output schema, the description covers the operation semantics and the 1-based indexing that are the main sources of misuse. The three file-input variants (file_id, file_url, library_file_id) are left entirely to the schema, which is acceptable given their descriptions.

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 75% schema coverage the baseline is 3, and the description earns an extra point by tying parameters to operations — `pages` means targets for delete/keep but the full ordered list for reorder, and rotate operates on all pages or a range. `angle` is still only defined by its enum in the 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 (change pages) and resource (a PDF), then enumerates all four operations the `operation` enum supports: delete, keep, reorder, rotate. That enumeration is what separates it from siblings like split_pdf, merge_pdfs, or compress_pdf, which each do a different page-level job.

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 operation list implies when the tool is appropriate, but there is no explicit routing: nothing says 'use split_pdf instead if you want separate files' or 'use this when page targets are from the 1-based index'. Usage is inferable from the operation names 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: AI-based validation, arithmetic checks for invoice totals and statement balances, cell-by-cell table extraction, and the difference between json output and spreadsheet-file creation for excel/csv.

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 and front-loaded with the core action, then quickly covers extraction modes and output implications. Every clause contributes useful information without unnecessary repetition.

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 complexity of 8 parameters, nested file object, output schema, and annotations, the description is largely complete for the main extraction modes and output behavior. It is less complete on input source selection and the instructions parameter, but the schema covers some of those gaps and the output schema removes the need to describe return values.

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 63%, so the schema carries much of the parameter documentation. The description adds meaning for the type enum options and output behavior, but it does not explain file source parameters like file_id, file_url, library_file_id, the nested file object, or instructions, leaving several parameters reliant on schema text.

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 — read structured data from a PDF with AI — and enumerates the distinct extraction modes (invoice, statement, tables, schema). An agent can distinguish this from siblings like ask_pdf or summarize_pdf based on the structured extraction focus.

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 clearly explains the available extraction modes and output choices, giving useful context for selecting type and output. However, it does not explicitly name alternatives such as ask_pdf for questions or ocr_pdf for scanned documents, nor does it state when not to use 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 already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that the download link is fresh and valid for one hour, but it does not mention permission requirements, failure modes, or what happens if the file is unavailable.

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 a single compact sentence with no redundant information. It front-loads the main outcome and includes the important link-expiry detail 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?

The tool is simple, annotations cover the safety profile, and an output schema exists, so the description does not need to explain return values. However, it does not compensate for the undocumented file_id parameter or provide usage context relative to sibling tools, leaving the definition only minimally 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?

There is one parameter, file_id, and the schema has 0% description coverage for it. The description does not explain the parameter at all, so it fails to compensate for the lack of schema-level documentation, even though the parameter name itself is fairly self-explanatory.

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 identifies the resource and outcome: a file's details plus a fresh download link. It is specific enough to distinguish this from list-oriented siblings, but it does not explicitly contrast with alternatives such as preview_file or list_files.

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 retrieval when a file's details or download link are needed, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. It leaves the agent to infer the choice among get_file, preview_file, and list_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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuinely non-obvious behavior beyond them: this is a long-poll that blocks up to 50 seconds by default. It stops short of saying what happens on timeout (pending result? error?), which matters for a blocking call.

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 short sentences with no filler, and the blocking behavior is front-loaded after the purpose. Slightly terse for a polling tool but efficient rather than padded.

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?

Output schema exists so return values needn't be described, and annotations cover safety. What's still missing is the timeout outcome and re-poll strategy, which an agent needs to use a 50-second blocking endpoint 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 parameter meaning; it partially does by revealing the default wait of 50 seconds, which the schema does not state. However, wait_seconds=0 semantics (presumably non-blocking poll) and the job_id 'job_' format/where to obtain it are never explained.

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 ('Check a job ... get its files when it's done'), which is unambiguous. No sibling tool polls job status, so differentiation isn't needed, but the description never mentions where job ids come from or what a 'job' is in this PDF-centric toolset.

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?

'Check a job that was still running' implies the usage context (you already have a job id from a prior async call), but there is no explicit when-to-use/when-not, nor guidance on re-polling versus blocking. Usage is only inferable.

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 disclose the side-effecting (readOnlyHint=false), open-world, non-idempotent profile. The description adds real value beyond that: it lists what content types are accepted, states the source must be publicly reachable, and promises a file_id back. It omits size limits and the fact that repeated imports create new files.

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?

A single well-formed sentence that front-loads the action and the source constraint, then the outcome. No redundant or filler content.

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 presence of an output schema removes the need to document return values, and the core happy path is covered. But for a network-fetching write tool, the undocumented optional file_name parameter and the absence of any failure-mode or size-limit note leave 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 description coverage is 0%, so the description carries the full burden, and it explains only that a URL is involved. The optional file_name parameter (name override, 200-char cap) is never mentioned, and there is no hint about URL format or whether signed/authenticated links work.

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 ("Fetch ... into FynePDF") plus the accepted formats and the returned handle (file_id). The phrase "from a public link" implicitly separates it from upload_file, but no sibling is named 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?

"Public link" implies the tool is for externally reachable URLs, which is a useful usage constraint, but there is no explicit when-not guidance and no alternatives (upload_file, get_file) are named for local or already-stored 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered elsewhere. The description still earns credit by disclosing the payload of each entry -- what each action takes, what it makes, and its credit price -- which tells the agent this is a metadata catalog rather than an executor. Return format and size are left to the output schema, which exists.

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?

A single sentence, front-loaded with the verb and resource, with the per-entry contents appended in a compact parenthetical clause. Nothing is wasted and nothing important is buried.

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 zero-parameter, read-only catalog tool with an output schema and full annotation coverage, this is nearly sufficient -- the agent knows it gets a list of actions with inputs, outputs, and cost. The only real gap is the missing cue about when in a workflow to consult it, which is a usage concern rather than a completeness one.

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 has zero properties, so the baseline is 4 and there is nothing to document. The description correctly implies the call takes no arguments by describing it as a pure enumeration. No contradiction or omission.

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 (list) plus the resource (every action FynePDF can run on a file) and even enumerates what each entry contains: inputs, outputs, and API-credit price. That is far more precise than the title alone. It stops short of 5 because it never distinguishes itself from siblings such as app_ready or the many action-style tools (compress_pdf, ocr_pdf, etc.), which an agent could easily confuse with a catalog call.

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?

There is no statement of when to call this (e.g. before invoking an action to discover its name or cost) or when not to. The usage is only weakly implied by the word 'list'. Naming no alternative and giving no precondition makes routing to this tool guesswork.

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, closed-world, so the safety profile is covered; the description still adds real behavior beyond them, notably the 24-hour window (files older than that will not appear) and the fact that uploads, imports and results are all included. It does not describe pagination or what happens when the window contains more than 50 files, which is the remaining 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?

Two compact sentences, with the scoping constraints (24 hours, newest first, source types) front-loaded before the use case. Dense but each clause carries information; 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. With only two fully documented optional parameters, the description supplies what structured fields cannot: the recency window and the intended lookup workflow. Only pagination/truncation behavior is unaddressed.

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 reinforces that the query is a name match ('by its name') but adds no syntax, matching rules, or guidance on limit beyond what the schema already states (default 10, max 50).

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 names the resource (files on FynePDF), the scope (last 24 hours), the ordering (newest first), and the sources folded in (upload box, other uploads/imports, results). That is enough for an agent to understand that this is a recent-activity listing, though the verb is implied rather than stated and no sibling (e.g. list_library_files) is named as the contrasting scope.

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 concrete use case with a selecting condition: find the file_id of a file the person says they uploaded, matched by name. There is no explicit when-not guidance and the near-sibling list_library_files is never mentioned, so the agent gets a positive trigger but no routing rule against the 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 declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: results are ordered newest first, pinned items appear on top, and returned ids are reusable as library_file_id in other tools. It does not cover pagination or limit 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?

Two short sentences with no waste. The core result set and ordering are front-loaded, followed by the useful library_file_id routing hint.

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 and annotations cover safety, so the description need not explain return values or side effects. It provides the essential ordering and id-reuse context, though it could say more about the limit parameter and how filtering works.

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 only 50%: query is documented as 'Part of a file name,' but limit has no description. The tool description does not explain limit or query semantics, so it fails to compensate for the undocumented input parameter.

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 identifies the resource: files saved in the person's FynePDF Library, with newest-first and pinned-on-top ordering. It distinguishes this from generic file listings by naming the Library, though it does not explicitly contrast with siblings like list_files or search_docs.

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 one useful cross-tool guideline: pass an id as library_file_id to any tool. However, it does not say when to use this tool versus list_files or search_docs, nor does it mention any prerequisites or exclusions.

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 that this is a non-read-only, non-destructive, non-idempotent operation. The description adds useful behavior beyond that by noting the output includes bookmarks named after each part and that input ordering is respected. It does not describe permissions, limits, or error behavior, so a 3 is appropriate given annotation coverage.

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 two concise sentences with the core action front-loaded and the ordering/bookmark details immediately following. Every sentence adds useful information without repetition 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?

With an output schema present and annotations covering safety semantics, the description supplies the key behavioral details an agent needs: merge ordering and bookmark output. It does not mention edge cases such as supplying no files or mixed-source constraints, but it is otherwise 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 description coverage is 100%, so the baseline is 3. The description adds important cross-parameter semantics that the schema does not: when multiple input arrays are supplied, they are combined in the fixed order file_ids, then files, then file_urls. This prevents ambiguity for an agent deciding how to pass inputs.

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: "Join PDFs into one." It also clarifies the resulting ordering and bookmark behavior, making the tool's function immediately clear and distinguishable from siblings like split_pdf or compress_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 implies when to use the tool (when PDFs need to be joined) but does not explicitly state when to choose it over alternatives such as split_pdf, create_pdf, or edit_pages. No exclusions or prerequisites are given, leaving usage guidance at an implied level.

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 this is a non-destructive, non-idempotent write with no open-world access, so the safety profile is covered. The description adds that a text layer is written into the document, but omits whether the original is preserved or overwritten, and says nothing about OCR being potentially slow or run as a job (the presence of get_job suggests async handling).

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?

A single sentence, front-loaded with the action and effect, with zero filler. Nothing could be removed without losing 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?

An output schema exists, so return values need no explanation. However, for a tool with four alternative optional input sources and nested objects, the description leaves the agent to infer how to supply the file and whether the operation is synchronous. Adequate but with clear gaps given the schema 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%, so the schema already explains file_id, file_url, library_file_id and the nested file object. The description adds no guidance on the fact that all four are optional and represent alternative input sources. Baseline 3 applies when the schema does the documentation work.

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 effect — 'add a text layer to scanned pages' — plus the resulting benefit. An agent can tell this is OCR, not conversion or data extraction. It does not name any sibling tool it must be distinguished from, so it stops short of 5.

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 'scanned pages' implicitly tells the agent to use this on image-only PDFs, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as convert_from_pdf or extract_data. Prerequisite of already having a file from upload_file/import_file_from_url is only in the schema, not the description.

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 fully covered. The description adds only that output is rendered images of the 'first pages' — useful, but it says nothing about cost, latency, or how many pages render by default, and the return shape is covered by 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?

Two short sentences with zero padding, and the output description is front-loaded before the routing advice. Nothing here repeats the annotations or the title verbatim.

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 output schema and annotations cover return shape and safety, so the description's remaining job is the parameters, which it omits entirely. Adequate for routing, thin for actually invoking with a page count.

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 carries the burden, yet it never mentions the `pages` parameter, its 1-5 range, or the `file_id` prefix pattern. 'First pages' hints at a default but gives an agent no signal that the page count is requestable and capped at 5.

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?

Names the specific resource and output form ('first pages of a PDF as images') and scopes it to FynePDF's result viewer, which separates it from general file tools. It's a noun phrase rather than a verb-led sentence, but an agent can still tell what it returns without opening the schema.

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 the negative case ('Not needed in conversation') and names the alternative ('use get_file for a link'), which is the routing information an agent needs. The positive trigger is only sketched as 'FynePDF's result viewer', so when an agent should actually call it is left partly implicit.

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 carries real behavioral weight the annotations do not: a password is required to open a locked file, unlock requires knowing the existing password, and flatten irreversibly "burns" fields and annotations so they "can't be changed." That last point sits in tension with destructiveHint=false, though the tension is plausibly resolved by the tool emitting a new file rather than mutating the original — worth noting, not a hard contradiction. It does not say what happens on a wrong password or whether the original is preserved.

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 parallel clauses, mode name first, zero filler — the dense fragment format is front-loaded and easy to scan. It is arguably over-terse for a six-parameter tool with a nested file object, which is the only deductible point.

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 need not be explained, and the mode semantics are covered. However, with four interchangeable-looking file-source parameters and a nested file object, the description should say which source to supply and when (uploaded attachment vs. file_id vs. library_file_id vs. public URL); that routing guidance is entirely absent.

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?

Coverage is 67%, and the description meaningfully clarifies two things the schema does not: the semantics of the operation enum, and that password means "to open the file" (lock) or "the password you already know" (unlock), which the schema leaves entirely blank. The four file-source parameters (file, file_id, file_url, library_file_id) get no mention at all, so roughly half the input surface is undescribed.

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 per mode (lock/unlock/flatten) against a clear resource (a PDF), and the per-mode clauses make the tool's scope unmistakable. It does not differentiate from adjacent siblings such as redact_pdf, sign_pdf, or edit_pages, which is the only thing keeping it below a 5.

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?

"unlock: remove a password you know" implies a prerequisite (you must already possess the password), and the three operation definitions implicitly tell the agent which mode fits which situation. But there is no explicit when-to-use/when-not framing, no mention of alternatives when a PDF is already unprotected, and no guidance on choosing between this and redact_pdf for removing content.

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 flag destructiveHint=true and idempotentHint=false; the description adds genuinely new behavior — the result is verified and nothing is returned if any target text survives, and the original file is preserved. It stops short of stating permissions or what a failure response looks like, keeping it below 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?

Three short sentences, front-loaded with the key differentiator ('for real, not just cover it'), then the two targeting modes, then the safety/verification guarantee. 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?

An output schema exists so return shape needn't be covered, and the verification behavior is a strong addition. But for a destructive 8-parameter tool with four optional, mutually substitutable file sources and unexplained flags, the description leaves too much selection logic to inference.

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 description maps its two modes onto the 'text' array and the 'find' string, adding meaning the schema leaves thin (the array has no description). However, with 63% coverage and 8 parameters, it says nothing about match_case, remove_metadata, or how file / file_id / file_url / library_file_id are chosen between.

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 ('Remove text for real') plus the two ways to specify targets, which no sibling (smart_edit, stamp_pdf, protect_pdf) does. An agent can distinguish true redaction from covering content without opening the schema.

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 explains the two invocation modes (exact text vs. AI-described target), which is real usage guidance, but never says when to prefer this over siblings like smart_edit or protect_pdf, nor any preconditions. Usage is implied rather than routed.

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=false and destructive=false. The description adds useful behavioral context that the annotations don't convey: the 24-hour deletion window and the persistence effect of saving. It doesn't clarify idempotency behavior (annotation says non-idempotent) or permissions, but the retention rationale adds real value.

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?

A single front-loaded sentence with no filler; the effect and the reason are both stated economically. Nothing to trim.

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 explained, and the annotation profile covers safety. But the description is thin on parameters for a tool whose schema descriptions are empty, leaving an agent to guess what file_id vs file_name semantics are.

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% with two parameters (file_id required with pattern ^file_, file_name optional). The description mentions neither parameter nor what they mean, so it fails to compensate for the documentation gap; the pattern and naming must be inferred from the schema alone.

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 ('Keep') and a specific resource ('FynePDF Library'), and distinguishes itself from list_library_files/upload_file by describing the retention effect. Clear what the tool does, though it doesn't explicitly name sibling alternatives.

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 purpose clause implies when to use it (to preserve a result beyond the 24-hour window), giving an implicit trigger condition. However, there's no explicit when-not guidance and no named alternative for those wanting to upload or list rather than persist.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that: no query syntax, no ranking or result-limit behavior, no indication of what a hit looks like or how errors surface.

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?

One sentence, front-loaded with the verb and scope, and the domain list is compact rather than padded. No sentence 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?

For a one-parameter read-only search with rich annotations and an output schema, the description covers what is searchable, which is the main thing an agent needs. Minor gaps remain around query formulation and result behavior, but nothing critical 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?

The single query parameter has 0% schema description coverage — only minLength 1 and maxLength 200 are stated. The description does not say whether the query is natural language or keywords, nor whether it matches across all listed domains or one, so it fails to compensate for the coverage gap.

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?

Names a specific verb (Search) and resource (FynePDF API and MCP documentation) and enumerates the covered domains: actions, parameters, pricing, files, jobs and errors. That verb+scope is enough to separate it from every sibling (which are all PDF file operations), though the description never explicitly says so.

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 this to look up API/action/parameter details — but there is no explicit when-to-use or when-not-to-use statement. The ambiguity with the sibling list_actions (both relate to actions) is left unresolved, so the agent must infer which one answers a given question.

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 that the tool is non-read-only, non-destructive, non-idempotent, and closed-world. The description adds useful behavior beyond annotations by naming accepted image formats, the default placement, and the top-left coordinate origin, but it does not clarify whether the original PDF is modified or a new signed file is created.

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 a single front-loaded sentence with no filler. It conveys the core action, supported image formats, default placement, and coordinate system efficiently.

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 tool has 12 parameters, nested file and signature objects, and only 50% schema description coverage. The output schema and annotations reduce the burden, but the description still does not explain the multiple input routes for the PDF and signature or the page/width options, leaving meaningful gaps for a complex mutation 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 50%, and the description usefully explains placement semantics for position and x/y, including the default bottom-right and points measured from the top-left. However, many of the 12 parameters—such as file/file_id/file_url, library_file_id, signature_url, signature_file_id, and width—are not addressed, so the description only partially compensates for the coverage gap.

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, 'Stamp,' and resource, 'a signature image ... on a page,' including supported formats and placement modes. It clearly distinguishes this from generic PDF editing, though it does not explicitly differentiate itself from the sibling stamp_pdf tool.

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?

There is no explicit guidance on when to use this tool versus alternatives such as stamp_pdf or smart_edit. The signing use case is implied by the verb and resource, but the agent must infer when this tool is the right choice.

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 (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world), the description discloses the plan-then-verify-then-execute pipeline and the dry-run escape hatch, which is genuinely useful behavioral context. It doesn't say whether a new file is produced or the source is modified, nor what happens when the instruction can't be fulfilled.

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 tight sentences: the first leads with a concrete example of the instruction, the second explains the plan/execute model and the dry-run flag. 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?

With an output schema and annotations present, the description needs only to explain the planning/execution model and dry-run behavior, which it does. It could still clarify output vs. in-place mutation and the failure mode for unsupported instructions.

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 already high (83%), and the description adds real meaning to the two most important inputs: 'instruction' is natural language describing the desired change (with an example), and 'run=false' returns only the plan. The file-source parameters are left entirely to the 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?

The description gives a concrete verb (edit), resource (PDF), and a distinctive mechanism: natural-language instruction turned into a checked plan of FynePDF actions that is then executed. The example instruction makes the tool's scope tangible. It does not explicitly distinguish itself from 'edit_pages' or 'redact_pdf', so it stops short of a 5.

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 clear operating context: describe the change in plain language and the tool plans then runs it, with 'run false' acting as a documented dry-run/preview mode. No alternatives (e.g. edit_pages for structured operations) are named, so there is no exclusion 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this produces output rather than mutating the source. The description adds the output shape (ZIP of parts), but says nothing about where the ZIP lands (library vs ephemeral), size/page limits, or whether the original is preserved.

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 sentences, zero filler, with the resource and both modes front-loaded and the return value last. Every clause carries information an agent needs.

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 6 parameters, zero required, and three overlapping file-source options, the definition should say that exactly one file source and one splitting mode must be supplied. That coordination rule is absent, and combined with a nested `file` object it is the main remaining gap; the output schema covers return-value details.

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 67%, and the description specifically compensates for the two undocumented parameters: it gives concrete `ranges` syntax examples ('1-3', '4', '5-9') and names `max_part_mb` as the alternative axis. It leaves the file-source parameters (file_id, file_url, library_file_id) to the schema, which does document them, so this is a solid but not exhaustive contribution.

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 ('Split a PDF') and enumerates the two operating modes plus the return artifact ('a ZIP of the parts'). No sibling does splitting, so disambiguation is implicit rather than stated, which keeps it just below a 5.

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 two modes (explicit `ranges` vs size-capped `max_part_mb`) are surfaced, which implies when each applies, but the description never says whether they are mutually exclusive, whether one is required, or when to prefer split over edit_pages/merge_pdfs. Usage is inferable but not guided.

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 it is a non-destructive, non-idempotent mutation and that an output schema exists, so the safety profile is covered. The description usefully adds that the watermark hits every page and that both operations can run in one call, but does not warn that repeated invocations stack stamps (consistent with idempotentHint=false) or what the output artifact is.

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 short sentences with no padding; the combinability statement is front-loaded and the format-string caveat immediately follows where it is needed.

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 and annotations present, the description only needs to convey the operational model, and it does state the two modes and their combination. The remaining gap is sparse guidance on file-source selection and failure modes when neither operation is requested.

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 67%, and the description adds genuinely non-schema detail for the page-number format string ('%d' used twice, with an example). However, it says nothing about the four mutually exclusive file-source parameters or the watermark styling options (color, opacity, rotation, size), which remain undocumented on the description side.

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+resource (number pages, stamp a text watermark on every page) and clarifies the operations can be combined. It is clearly distinguishable from any sibling (no other tool stamps or numbers pages), though it does not explicitly name a sibling it is not.

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?

There is no guidance on when to use this versus alternatives, no preconditions (e.g., which of file/file_id/file_url/library_file_id to supply), and no note that at least one of page_numbers or watermark should be provided since nothing is required.

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, so the safety profile is covered. The description adds only that results carry page citations, which is a return-value detail already implied by the output schema; it says nothing about processing limits, how the different file inputs behave, or handling of scanned/non-text PDFs.

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?

A single short sentence with no filler, though it leads with the output artefact rather than the verb. Nothing is wasted, but there is very little there to front-load.

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 six parameters, a nested file object, four mutually redundant file-location inputs and a large sibling set, the description should at least steer the agent on input selection and on summarization versus grounded Q&A. Annotations and the output schema cover safety and return shape, but the selection guidance gap is not covered anywhere the agent will look.

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 83%, so the schema already documents file_id, file_url, library_file_id, focus and the nested file object; the description adds nothing further. The real ambiguity is which of the four file-locating inputs to use, and the description does not address it. Baseline 3 applies when the schema does the heavy lifting.

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 sentence describes the shape of the output ('a plain summary and key points, each with the pages it comes from') rather than stating the action and resource directly; the name and title carry the verb. It gives no differentiation from near-neighbours like ask_pdf, extract_data or search_docs, which also consume a PDF and return derived 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?

There is no guidance on when to choose this over ask_pdf (targeted Q&A), extract_data (structured fields) or search_docs. No prerequisites, no mention of what kinds of documents suit a summary, and no exclusions.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description adds useful operational context: conditional drop-zone availability, multi-file ordering, signed upload_url plus curl generation, and that the file_id only works after the PUT completes. It does not mention authentication or rate limits, but the behavioral lifecycle is well disclosed.

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 and then efficiently covers the two modes, multi-file behavior, and the ChatGPT alternative. It is dense but appropriately sized for a dual-mode upload tool, with little wasted text.

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 and annotations already present, the description supplies enough context to call the tool correctly: drop-zone mode, multi-file handling, signed upload_url generation, and file_id timing. The main gap is not mentioning the URL-import sibling as an alternative, which is minor given the tool's scope.

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 50%: file_name is documented in the schema, while size_bytes has no schema description. The description mentions both parameters together and explains their effect (returning a signed upload_url and curl command), which adds useful combined semantics, but it does not compensate for size_bytes' missing format or validation details beyond the 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?

The description opens with a specific verb and resource: "Bring a file into FynePDF." It clearly explains the two upload modes (drop zone / signed upload_url) and multi-file behavior. It does not explicitly distinguish itself from the sibling import_file_from_url for URL-based imports, so sibling differentiation is incomplete.

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 concrete usage conditions: drop zone where supported (Claude, ChatGPT, VS Code), multiple files at once for merge, and file_name + size_bytes for sandbox PUT uploads. It also tells ChatGPT users they can pass attached files directly instead. It lacks explicit when-not guidance and does not route URL imports to import_file_from_url.

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