Razi Document Tools

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

With no annotations provided, the description carries the full burden and over-delivers: output is never inlined but arrives as a stored URL with ~24h retention, compression is lossy at a fixed 'ebook' preset with no quality knob, compression is not guaranteed (fallback saves almost nothing, originals returned unchanged), images/videos are rejected, and there are rate limits, paid compute, and latency warnings. This is exemplary failure-mode and side-effect disclosure.

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 long, but every sentence earns its place — algorithm, fallback behavior, retention window, rate limits, input constraints, and workflow are all non-redundant. The core purpose is front-loaded and the information is densely packed; only minor tightening would be possible without losing substance.

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

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

For a tool with no annotations and no output schema, the description covers input acquisition, output delivery format, quality profile, failure modes, rate limits, and latency. An agent has everything needed to call it correctly and set user expectations; nothing material 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 schema exposes zero parameters (baseline 4), and the description goes well beyond it by documenting `fileUrl`: it must live in razi.pro's storage, third-party URLs are rejected, and it is obtained via the REST API. The one flaw is that this parameter is absent from the input schema entirely, so the prose and the formal contract don't align — an agent could be confused about whether fileUrl is a legal argument at the MCP layer.

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 opening sentence uses a specific verb + resource: 'Shrink a PDF's byte size while keeping it a PDF', with explicit use-case context ('for email limits or slow connections'). This is unmistakably distinct from the sibling tools (text extraction, merging, parsing, splitting), so an agent can tell them apart without opening any 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?

Clear context is given for when to use the tool (email limits, slow connections) and hard constraints are spelled out: PDFs only, third-party URLs rejected, and the required prerequisite workflow (upload via REST API first). It stops short of explicitly routing to alternatives or stating when-not-to-use, but the stated constraints and workflow give actionable 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?

No annotations are provided, so the description carries the full burden and fully meets it: it discloses best-effort accuracy, misreads under blur/skew/contrast, no layout preservation, paid compute with a 20-calls/hour/IP cap, and the upload restriction that third-party URLs are rejected. This is exceptionally transparent for a tool with no 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?

One dense paragraph, front-loaded with the core usage condition and then covering limitations, quota, and URL handling without redundancy. Every sentence contributes a distinct fact an agent needs to invoke this correctly.

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

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

Despite having no annotations and no output schema, the description tells the agent the return shape ({ text, language, confidence? }), failure modes, quota, and the exact way to supply the image via a razi.pro-storage URL. The only incompleteness is that fileUrl is described but missing from the input schema, which could confuse schema-driven invocation.

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

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

The schema already fully documents language (100% coverage), and the description adds the important operational caveat that one language per call is allowed and naming the wrong one degrades accuracy. It also documents fileUrl in prose, but that parameter is absent from the input schema, so the guidance is helpful yet not aligned with the structured 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 precise verb and resource: it runs OCR on images and returns a best-effort transcription, explicitly contrasted with parse_document. The phrase 'Use this ONLY when the text exists as PIXELS' makes its job unmistakable and distinguishes it from sibling tools.

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

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

Gives explicit when-to-use ('text exists as PIXELS') and when-not-to-use conditions ('If the file already stores real characters, this is the wrong tool'), names the exact alternative (parse_document), and provides a robust deciding heuristic: 'what the bytes contain, never the file extension'. It also adds rate-limit and payment context for operational selection.

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?

With no annotations provided, the description carries the full disclosure burden and fully delivers: format-specific handling (PNG/JPEG embedded untouched, others re-encoded), page-geometry defaults (nothing scaled/cropped/letterboxed), rate ceilings (100 files, 50MB, 20 calls/hour/IP), explicit failure mode (HTTP 400 naming the offending file, never a blank-page substitution), REST-vs-MCP output differences, and an expiring-storage-link policy. This is exceptional transparency for an unannotated tool.

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 core purpose is front-loaded in the first sentence, and every subsequent sentence contributes a distinct piece of non-redundant information: format conversion rules, PDF splicing, page sizing, rate limits, error behavior, output delivery, and the fileUrls prerequisite. The description is long (~170 words) but the tool is genuinely complex; the density is justified, though its sheer volume and run-on structure prevent a 5.

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?

Everything an agent needs to call this correctly is present: accepted input formats and their treatment, the mandatory fileUrls-in-own-storage mechanism and how to mint them, per-call and per-IP ceilings, failure semantics, and the return value (raw bytes over REST, persistent-link over MCP). Given that no output schema exists, the description's coverage of the output shape is essential — and provided.

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

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

Schema coverage is 100% and both parameter descriptions in the schema are already rich (margin units, pageSize geometry including point dimensions). The description adds contextual framing — default pixel-dimension pages, centering on a fixed portrait sheet — that links the params to the assembly workflow, but it introduces no new parameter semantics beyond what the schema already documents. 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?

Opens with a precise verb+resource+behavior statement: 'Assemble pictures into one PDF, a page per picture, in the order supplied.' It is immediately distinguishable from the PDF-manipulation siblings (merge_pdf, split_pdf, compress_pdf) by being the image-to-PDF direction, and it reinforces the distinction by describing the mixed-input PDF-splicing behavior.

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 clear prerequisites and constraints an agent must honor: files must be fileUrls inside razi.pro's own storage, minted by POSTing to /api/v1/tools/execute first, external links are refused, and MCP carries no attachments. This effectively tells the agent how and when to invoke the tool, but it never names sibling tools or states explicit when-not-to-use conditions, so it stops short of 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?

No annotations are provided, so the description carries the full burden. It discloses the stored-URL output valid for about 24 hours, no inlining over MCP, unchanged page content, rejection of third-party URLs, the absence of an MCP upload channel, and the 20-merges-per-hour rate limit. This is rich behavioral context.

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

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

The description is long but every sentence earns its place: core action first, then output behavior, exclusions, alternatives, input sourcing, and rate limit. There is no filler and the structure is easy for an agent to parse.

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

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

For a tool with no annotations, no input schema, and no output schema, the description is nearly self-sufficient. It covers invocation inputs, constraints, response format via stored URL, alternatives, and operational limits. The only minor omission is the exact response envelope, but the provided detail is sufficient for correct invocation.

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

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

The input schema is empty, so the description is the sole documentation for parameters. It explicitly names `fileUrls`, describes it as an array of URLs in razi.pro's own storage, rejects third-party URLs, and explains the REST API multipart alternative. This more than compensates for the missing 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 states a specific verb and resource: 'Concatenate two or more PDFs into a single PDF, in the order supplied, and return the merged file.' It also distinguishes itself from sibling tools like compress_pdf, split_pdf, and images_to_pdf, so an agent can identify the correct operation without inspecting other 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 gives explicit when-to-use and when-not-to-use guidance: use compress_pdf for compression, split_pdf for page selection, and images_to_pdf when any input is a picture. It also states rejection conditions such as fewer than two files and non-PDF inputs, making alternative selection and invocation rules unambiguous.

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?

With no annotations provided, the description carries the full burden and discharges it exceptionally: exact error codes (400 for unsupported/unreadable/encrypted files, 422 with metadata.imageOnly for image-only PDFs, 413 for over-limit), concrete limits (50MB, 300 pages, 10 calls/min), the layout-not-preserved caveat, extension-based detection rather than byte inspection, third-party URL rejection, and the REST upload prerequisite. This fully discloses the tool's failure modes and operational 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?

The description is long, but nearly every sentence carries a distinct operational fact (formats, error codes, limits, rate limit, URL constraints), and the most important content — use case and OCR distinction — is front-loaded. It loses one point for minor redundancy: the scanned/photographed-PDF concept is introduced in the OCR contrast and then restated in the 422 case, and the upload flow sentence is dense enough to warrant splitting.

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

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

Given an empty schema, no annotations, and no output schema, the description must cover selection, invocation, and failure behavior on its own — and it does. It specifies the return shape (text plus per-format metadata fields), every rejection path with its status code, page separator format for PDFs, size/page limits, the rate limit, and the exact mechanism for obtaining a valid fileUrl. For a moderately complex tool with rich edge cases, nothing an agent needs to call it correctly is missing.

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

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

The schema is empty (0 params), so the baseline is 4 and the description must compensate — and it exceeds that baseline by documenting the effective parameter fileUrl in prose: it must be a URL in razi.pro's own storage, third-party URLs are rejected, and it is obtained by uploading via the REST API (POST /api/v1/tools/execute). This gives the agent complete information about the argument it must supply despite the schema defining nothing.

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: 'it decodes them and returns JSON { text, metadata } verbatim' for files that 'ALREADY store text as characters.' It explicitly differentiates from the sibling extract_text_ocr ('That exactness is the whole difference'), and enumerates the exact supported formats (.txt, .pdf text layer). An agent can immediately tell what this tool does and how it differs from its siblings.

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

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

Provides explicit when-to-use guidance ('Use this when the file ALREADY stores its text as characters'), explicit when-not-to-use guidance ('should only ever be pointed at a photo, screenshot or scan' for extract_text_ocr), and names the alternative tool twice — including the specific 422 case where 'extract_text_ocr is the tool for it.' No inference 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers output format (single PDF vs ZIP), link-based delivery with roughly one-day expiry, verbatim page copying, no size reduction, no rasterization, upload restrictions, and rate limits. This is exceptionally transparent for a tool with zero 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 long but every sentence carries distinct, non-redundant information. It front-loads the core purpose, then efficiently covers output format, delivery mechanism, behavioral limitations, upload constraints, and rate limiting. 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?

Despite having no output schema, the description fully explains what the agent will receive (link vs bytes, ZIP vs PDF, expiry). It also covers prerequisites (REST API upload, fileUrl format) and constraints (third-party URLs rejected, rate limit). For a single-parameter tool, 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?

The schema already describes the ranges parameter in full detail (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining that multiple ranges produce a ZIP and that a single range returns that PDF directly, clarifying how the parameter's cardinality affects the result.

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: 'Extract page ranges from one PDF into new PDFs.' It clearly states the tool's core function and distinguishes it from siblings by explicitly noting that it does not reduce file size (compress_pdf) and cannot rasterize pages (a browser-only feature).

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use compress_pdf for size reduction, and rasterization is browser-only. It also specifies the required input source ('fileUrl' in razi.pro storage, obtained via REST API) and notes the 20-splits-per-hour rate limit, so an agent knows exactly what to prepare and expect.

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