Razi Tools

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 clearly states the return format (JSON { operation, result }), the extra 'unit' field for 'change', that arithmetic is exact with no rounding, and that it involves no model. It also mentions the limitation on ratios. While it does not discuss error handling beyond the schema's note on 'change' when value1=0, the key behavioral traits are transparently 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 three sentences with zero fluff. The primary purpose is front-loaded, the return format is given immediately, and the operational nuances are compressed into two final sentences. Every sentence earns its place, making it highly efficient 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 four operations and no output schema, the description covers the essential context: it states the return structure, the special 'unit' for 'change', the exactness of arithmetic, and the limitation on ratios. It also points to the schema for parameter semantics. The only minor gap is that it doesn't mention potential edge cases (e.g., division by zero in 'of' when value2=0), but the schema covers the 'change' error case, so overall it is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a valuable hint that value1/value2 semantics depend on the operation and advises reading their descriptions, but it does not add substantive meaning beyond the schema. The schema already provides per-operation explanations for each parameter, so the description's contribution is minimal but helpful.

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 exactly what the tool does: 'Run one of four percentage calculations on two numbers.' It names the resource (percentage calculations), the verb (run), and the scope (four operations). It also distinguishes from siblings, which are all encoding/decoding/formatting tools, so there is no ambiguity. The return format is mentioned upfront, making the purpose even clearer.

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 practical usage guidance: it notes that value1/value2 meanings depend on the operation and instructs the agent to read their descriptions before calling. It also explicitly states what is NOT supported ('Ratios and general expressions are not supported'), which helps avoid misuse. Since no sibling tool does similar work, explicit alternatives are not needed, but a more direct 'use this when you need percentage calculations' would strengthen the 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 present, so the description must carry the full burden, and it does: it discloses position-based matching, the lack of LCS behavior, the absence of patch output, whitespace/case significance, CRLF/LF normalization, and local execution cost. This is exemplary transparency beyond the structured 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?

Four dense sentences with no filler: return shape first, then algorithm behavior, then limitations, then normalization/execution details. Every sentence contributes essential information for correct invocation.

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 fully specifies the return contract, algorithm semantics, edge-case handling, and cost characteristics. An agent has everything needed to select and call the tool correctly.

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

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

Schema description coverage is 100% and the property descriptions already map text1 to baseline/before and text2 to revised/after. The main description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

Begins with a specific verb and resource ('Compare two blocks of text line by line') and immediately states the exact JSON return shape. The contrast with generation-oriented siblings like generate_text and draft_email is clear without ambiguity.

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?

Clearly states the tool is position-based and not an LCS diff, and explicitly rules out character-level, word-level, and unified-diff use cases. It does not name a sibling alternative, but none of the sibling tools are diff tools, so the guidance is sufficient.

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, the description carries the full burden and does so thoroughly. It discloses lossy behavior below quality 1.0, HEIC/SVG conversion, the 5MB threshold that changes the return shape (bytes vs JSON), the rate limit of 30 calls/hour/IP, and the rejection of third-party URLs.

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 adds a distinct operational constraint: input format handling, quality semantics, size-based output switching, rate limits, and upload workflow. The description is dense but each clause 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?

The description compensates well for the missing output schema by spelling out both possible return shapes, plus input restrictions and rate limits. However, it instructs the agent to 'pass `fileUrl`' while the input schema has no such property, leaving the central invocation mechanism unresolved.

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 of 3 applies. The description adds useful nuance (e.g., 'Lossy for webp, jpeg and avif at any quality below 1.0'), but most parameter meaning already comes from 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 opening sentence states a specific verb and resource: 'Re-encode a single raster image to webp, jpeg, png or avif, optionally resizing it and/or converting it to grayscale.' This clearly distinguishes compress_image from the sibling generation and QR-code tools, and the scope is unambiguous.

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

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

Provides clear context for when to use the tool: 'Raster images only' with PDF/video explicitly rejected, and a mandatory prerequisite of passing a razi.pro-hosted fileUrl obtained via REST. It does not explicitly name alternatives, but the exclusionary guidance is strong enough for an agent to route correctly.

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 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the return shape, the re-encoding validation behavior, the UTF-8 constraint, and the rejection of non-Base64 input. This is thorough and prevents false expectations.

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

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

Three concise sentences with no wasted words. The main purpose is front-loaded, followed by validation behavior, then exclusion and alternative routing. Every sentence adds value.

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

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

Complete for a simple one-parameter utility. It explains the return format, failure modes for invalid input and binary data, and how to choose an alternative tool. 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 input schema already documents the only parameter in detail, including whitespace tolerance, padding behavior, and URL-safe alphabet exclusion. The description reinforces this but adds little new parameter-level meaning beyond what the schema provides.

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 ('Decode a Base64 string back to UTF-8 text') and clearly differentiates itself from the sibling decode_jwt. An agent can immediately tell this tool is for raw Base64 decoding, not JWT handling.

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 says 'For a JWT use decode_jwt' and warns that percent-escape strings are not Base64 and will be rejected. This gives the agent both positive and negative usage guidance and names the alternative 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?

With no annotations provided, the description carries the full burden and delivers: it discloses that signatures are NEVER verified, signatureVerified is always false, claims must be treated as untrusted attacker-controlled input, expiry is derived from exp and null when absent, and output is structured JSON objects rather than a table. This goes well beyond the 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?

The description is front-loaded with the core purpose and return shape, then covers critical security caveats and alternatives. Every sentence adds necessary information; no fluff or repetition of schema 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?

Despite having no output schema, the description fully documents the return object fields and their semantics. It also covers failure-prone edge cases (Bearer prefix, segment count), security implications, and the sibling tool route, making it complete for an agent to invoke 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 100% and already describes the token format well. The description adds extra meaning by explaining that it handles base64url padding, splits segments, and contrasting with decode_base64, providing context the schema alone does not convey. Slight deduction because most parameter-level detail is already 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?

The description opens with a specific verb and resource: 'Decode a JWT's header and payload for inspection.' It clearly differentiates itself from decode_base64 by noting it splits the three segments and handles base64url padding, so an agent can distinguish it from its sibling without ambiguity.

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 names the alternative tool decode_base64 and states the condition for choosing it ('for a bare Base64 string'), contrasting with this tool's additional JWT-specific behavior. It also gives practical usage constraints such as the Bearer prefix not being stripped and the three-segment requirement.

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, the description fully discloses behavior: error on malformed escapes, handling of '+', and the exact output format. It covers edge cases and limitations, making the tool's behavior predictable.

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?

Each sentence adds meaningful information without redundancy. The description is compact yet thorough, covering purpose, behavior, edge cases, and relationship to sibling tools 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 description is self-contained: it specifies the return format (JSON with 'decoded' key), error behavior, and non-goals, making it sufficient for an agent to use the tool without additional context. No output schema is provided, so this description fills that gap effectively.

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

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

Although the schema already describes the 'encoded' parameter, the tool description adds valuable context: it gives an example ('query-string value'), clarifies UTF-8 requirements, and specifies the impact of malformed input, enriching the schema beyond its baseline.

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

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

The description clearly states the tool's function: reversing percent-encoding with decodeURIComponent, and explicitly differentiates it from encode_url and other URL-related tools by specifying its 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 provides explicit guidance on when to use this tool: as the inverse of encode_url, and clarifies what it does not do (e.g., no Base64/JWT decoding, '+' remains literal), preventing misuse.

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

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

With no annotations provided, the description carries full behavioral disclosure. It reveals pricing implications ('Paid model call'), rate limits and refusal status (401), output length cap (~400 tokens), caching behavior, and the important side-effect guarantee that nothing is sent. This is unusually transparent.

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?

Every sentence adds value: purpose, output shape, side-effect guarantee, sibling routing, rate limits, token cap, and caching. Information is front-loaded and the description stays compact despite covering many operational details.

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 covers the return format, behavioral constraints, rate limits, caching, and usage boundaries. An agent has enough information to decide whether to call this tool and to interpret the response.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about the brief ('A sentence or two is enough') but does not materially expand parameter semantics beyond the schema. 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?

States a specific verb and resource: 'Write a business email body from a short brief.' It immediately clarifies scope by saying the result is the body only, no subject line, no recipient, and nothing is sent. This clearly differentiates it from generate_text and humanize_text.

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 selection guidance: 'Choose this over generate_text when the output should be a whole email; use humanize_text to rewrite an email you already drafted.' This tells the agent exactly when to pick this tool and when to pick an alternative.

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

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

With no annotations provided, the description carries the full disclosure burden and meets it thoroughly: it states the return shape ('Returns JSON { encoded }'), alphabet and padding, the URL-safety caveat, local execution, no size limit beyond the request body, and that it is reversible rather than encryption. This is far beyond what the schema alone provides.

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?

Every sentence carries distinct information: use cases, return format, URL-safety caveat, non-encryption, and operational limits. The main action is front-loaded before caveats, and there is no repetitive 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?

For a single-parameter utility, the definition covers purpose, use cases, output format, caveats, and operational constraints, enough for an agent to invoke it correctly even without an output schema. The sibling list is small and the description already differentiates from decode_base64, making the context complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description confirms the input is UTF-8 text and notes raw binary cannot be passed, but that information already exists in the schema's parameter description; it adds no new semantic detail beyond contextualizing the encoding.

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: 'Encode UTF-8 text as standard Base64,' specifying the exact alphabet and padding. This clearly distinguishes it from sibling tools such as decode_base64 (reverse operation) and decode_jwt, leaving no ambiguity about the tool's function.

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 explicitly names use cases ('embedding binary-unsafe content in JSON, data URIs, HTTP headers or Basic auth') and explicit when-not-to-use conditions: the output is not URL-safe, '+' and '/' must be percent-escaped, and the tool does not do that. It also clarifies it is not encryption and points to decode_base64 as the reverse operation, giving an agent clear selection 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?

With no annotations provided, the description carries the full burden. It discloses the exact encoding function, which characters are escaped, the JSON return shape, the limitation to URL escaping, and common misuse cases. This is thorough behavioral 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 front-loaded with the core purpose, then uses short readable sentences to cover scope, exclusions, and alternatives. Every sentence adds distinct value without redundancy.

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?

Although there is no output schema, the description states the return format as JSON { encoded }. It covers behavior, limitations, use cases, and reverse operation, making the tool fully usable by an agent without additional 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?

Schema coverage is 100% and the parameter description already explains the allowed character set and intended input. The tool description adds context about survival in transport, structural character escaping, and non-URL alternatives, which enriches the meaning 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 states a specific verb and resource: percent-encode a string using encodeURIComponent. It also explicitly distinguishes itself from decode_url and clarifies that it is not for whole addresses, making sibling differentiation clear.

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 guidance: for a single query-string value or path segment, not for a whole clickable URL. It also names when not to use it and suggests Base64 for other contexts, plus points to decode_url for reversal.

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 burden of disclosing behavior, and it does so thoroughly: no image downloads, redirect handling up to 3 hops, no JS execution, no HTTP status verification, user-agent identification, error codes, caching behavior, and rate limits. This is comprehensive beyond what structured fields would reveal.

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 dense but every sentence adds essential operational detail. It front-loads the return shape and main scope, then layers in limitations, errors, and caching. No filler or repetition; the length is justified by the tool's behavioral complexity.

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

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

There is no output schema, so the description must explain the return format, and it does so in detail with field names, types, and conditional presence. It also covers failure modes, edge cases, caching, rate limits, and alternatives, making it fully sufficient for an agent to invoke 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?

Although the schema already describes the url parameter at 100%, the description adds valuable semantics: bare domains are accepted and assumed https, and the URL is the verbatim cache key, meaning different spellings cause duplicate fetches. This extra context helps the agent avoid misuse.

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

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

The description clearly states the tool's verb and resource: read a web page's metadata without downloading images. It also distinguishes itself from siblings by explicitly naming fetch_site_logo and screenshot_url as alternatives for icon resolution and visual capture.

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: it is the fast, cheap counterpart to fetch_site_logo, and it tells the agent to call fetch_site_logo when a logo/favicon/icon is wanted and screenshot_url when the page's appearance is needed. It also notes limitations such as no JavaScript execution.

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 behavioral burden and does so thoroughly. It discloses that JavaScript is not executed, the crawler identifies itself as RaziMetadataBot, HTTP status is intentionally not checked, candidates are measured rather than trusted, SVG/ICO dimensions may be missing, results are cached for 24 hours, and rate limits apply. This far exceeds what annotations would typically provide.

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 operational or decision-relevant information. It is front-loaded with the core purpose, then systematically covers ranking, alternative usage, return shape, edge cases, errors, caching, and rate limits. There is no filler or repetition of the schema.

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

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

Given the tool's complexity and the absence of an output schema and annotations, the description is remarkably complete. It defines the exact JSON return shape, the candidate object fields, fallback behavior, error codes with meanings, timeout and page-size limits, caching semantics, and rate limits. An agent has enough information to invoke the tool correctly and interpret the result.

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

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

The input schema already describes both parameters with 100% coverage, including bare-domain handling, redirect limits, the rehost CDN behavior, CORS/hotlink context, and separate caching per setting. The description adds useful context about candidate fields and ranking, but it does not materially extend the meaning of the parameters beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Get a company's logo from its website URL.' It then describes the exact detection strategy and distinguishes itself from the sibling fetch_page_metadata by noting it also returns all page-metadata fields. An agent can immediately understand what this tool does and how it differs from nearby 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 description explicitly names the alternative tool and gives the decision rule: 'Use that tool instead if you do NOT need the logo: it skips the image downloads entirely and is much faster.' It also explains that this tool makes a separate fetch_page_metadata call unnecessary. This is clear, actionable guidance with a named alternative.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the exact return shape, that invalid JSON is rejected with a parser error rather than returning valid:false, and that round-tripping normalizes the document (losing comments, trailing commas, duplicate keys, and precision on large integers). This is exceptional behavioral transparency.

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 purpose, then efficiently covers output format, error handling, and normalization in three concise sentences. Every clause adds value; there is no redundancy or fluff.

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

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

For a simple two-parameter tool with no output schema, the description fully explains the return object, error behavior, and side effects (normalization). Nothing an agent needs to correctly call and interpret the tool is missing.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents their meaning. The description adds no new parameter-specific detail; it focuses on output and behavior. Baseline of 3 is appropriate when schema covers everything.

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 ('Validate and re-print') and resource ('a JSON string'), and specifies the output structure. It clearly distinguishes itself from the sibling tools (calculate_percentage, decode_base64, etc.) by focusing on JSON formatting and validation.

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 clearly implies the tool is for validating and formatting JSON strings, and the mention of normalization and error behavior sets expectations. However, it doesn't explicitly name alternative tools or state when not to use it; given the siblings are unrelated, this is a minor gap.

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, the description carries full behavioral disclosure. It reveals the return format (JSON { outline }), the fact it writes only a skeleton, that it is a paid model call with a token cap, rate limiting, and caching behavior. This is substantial and actionable 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 dense but every sentence contributes unique information: purpose, return format, scope and alternatives, cost/token cap, rate limit and caching. It is front-loaded with the core function and keeps all sentences relevant.

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

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

For a simple two-parameter tool with no annotations and no output schema, the description covers all necessary ground: what it does, what it returns, how it differs from siblings, and operational constraints. Nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that a large section count yields thinner sections due to the token cap, which is behavioral context tied to the 'sections' parameter that the schema does not provide.

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

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

The description clearly states the tool produces a markdown heading structure for a blog post with specific components (title, introduction, sections, conclusion, FAQ). It explicitly distinguishes itself from generate_text and humanize_text, making the resource and scope unmistakable.

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

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

The description provides explicit guidance: use this tool for the skeleton only, and use generate_text for body prose and humanize_text for reworking existing text. This gives clear when-to-use and when-not-to-use signals relative to siblings.

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

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

No annotations are provided, so the description carries the disclosure burden. It does well by revealing deterministic outputs, fixed word-list behavior, reserved email/phone domains, and per-type return shapes. It could explicitly state that no data is persisted or that the operation is side-effect-free, but this is a minor gap for a fake-data generator.

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 sentences, all information-dense. Purpose is first, return shape follows, then behavioral warnings and the sibling alternative are packed in without redundancy.

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 with only two parameters and full schema coverage. The description covers the output format, deterministic behavior, restricted fake-value domains, and points to the correct sibling for prose generation. 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 coverage is 100%, so the parameters are already documented. The description adds real value by explaining the deterministic sequence behavior across counts and by clarifying that 'user' returns an object while other types return strings—semantics beyond 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?

The description states a specific verb and resource: 'Produce placeholder person records for testing and fixtures.' It details the return shape and explicitly contrasts with generate_text for lorem-style prose, making it easy to distinguish from the siblings.

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

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

The description says when to use the tool (testing/fixtures) and explicitly names generate_text as the alternative for prose. It also scopes the tool to 'people only,' giving a clear boundary for when not to use it.

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 zero annotations provided, the description carries the full burden of disclosure and does so exceptionally well. It reveals the return format (PNG inline under 1MB, otherwise a 24-hour stored URL), auth requirement (signed-in account, 401 for anonymous), rate limit (20 images/hour), latency (tens of seconds), provider fallback chain, non-determinism, absence of seed/size control, and lack of permanent hosting. This is rich behavior context beyond any structured field.

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 given there are no annotations and no output schema to lean on. It is front-loaded with the core purpose, followed by return format, exclusions, alternatives, auth, rate limits, latency, and provider behavior. Minor redundancy exists between 'no two calls give identical output' and 'not automatically hosted anywhere permanent,' but both convey distinct 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?

For a tool with no annotations and no output schema, the description is nearly complete: purpose, return format, retention, exclusions, alternative tool, auth requirements, rate limits, latency, provider variability, and determinism are all covered. Minor gaps include specific error responses beyond 401 and exact pricing for 'paid compute,' but these fall outside typical MCP description expectations.

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

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

Schema description coverage is 100%, so the schema fully documents both prompt and negativePrompt, including the caveat that negativePrompt only works on the Replicate fallback. The description adds no parameter-specific semantics beyond reinforcing that provider variation exists, which the schema already notes. Baseline 3 is appropriate since 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 first sentence states a specific verb and resource: 'Generate a new image from a text description with a diffusion model.' It further distinguishes itself by explicitly stating what it cannot do ('cannot edit, upscale or restyle a picture you already have') and naming compress_image as the sibling for existing files, so an agent can tell it apart from all three siblings without opening their schemas.

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

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

The description explicitly guides routing: 'Use compress_image to re-encode or resize an existing file,' which covers the most likely confusion since both tools handle images. It gives clear when-not-to-use context ('invents an image from scratch'). However, it does not explicitly compare against generate_qr_code or split_image, leaving that differentiation to inference from tool names.

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 behavioral disclosure burden and does so thoroughly. It reveals that output is a base64 data URI rather than a hosted link, emphasizes that nothing is stored and the image cannot be fetched later, states it runs locally at no cost, and clarifies the writing-only limitation. It also warns about density/scannability tradeoffs for long payloads.

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

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

The description is well-structured and front-loaded with the essential purpose, followed by output format, privacy implications, and limitations. Every sentence carries valuable information, and there is no redundancy or filler.

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

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

Given that there is no output schema, the description compensates by clearly specifying the return shape and the nature of the dataUrl. It also covers privacy, cost, side effects, and payload constraints, making the tool fully understandable for an agent without requiring additional context.

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

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

The input schema already has 100% description coverage for all three parameters, so the description does not need to repeat parameter details. It adds useful behavioral context about long payloads becoming denser and less scannable, but this reinforces rather than meaningfully extends the schema's own guidance.

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 'Render text or a URL as a QR code image,' a specific verb and resource that clearly identifies the tool's purpose. It further distinguishes itself by noting it is writing-only and cannot decode a QR code, setting it apart from any potential sibling ambiguity.

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 clearly states when to use the tool: to render text or a URL as a QR code. It also gives a when-not condition, explicitly noting it cannot read or decode an existing QR code, and advises shortening payloads before encoding. However, it does not explicitly name a sibling tool as an alternative, only referring vaguely to 'other means.'

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 does so thoroughly. It discloses that the query is never executed or checked against a database, that names are guessed unless supplied, that results are cached, that there are rate limits and a 401 refusal, that the call is paid, and that output is capped around 500 tokens. This is exemplary 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 dense but every sentence adds necessary operational or behavioral detail. It is front-loaded with the core purpose, then returns the contract, limitations, cautions, quotas, and caching behavior. No filler is present.

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 generation tool with no output schema and no annotations, the description is remarkably complete. It covers the return format, what is not returned, execution behavior, schema knowledge limitations, cost, rate limits, token cap, and caching, leaving little ambiguity for an agent choosing or invoking the tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful context beyond the schema. It explicitly notes that dialect is accepted for forward compatibility but not passed to the model, and it advises the caller to include table and column names in description because the model otherwise invents plausible ones.

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: 'Translate a natural-language request into a SQL statement.' It clearly identifies the tool's function and distinguishes it from text-focused siblings like generate_text and draft_email by naming SQL and the expected { sql } return shape.

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 actionable guidance: include table and column names in the request, review output before running, and be especially careful with writes. It does not explicitly name alternatives or state when not to use the tool, but the context is clear enough for an agent to decide when SQL generation is appropriate.

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 it delivers: return shape ('Returns JSON { text, provider, cached }'), approximate behavior ('phrased into the prompt rather than enforced'), cost ('a paid call'), and limits ('15 calls per minute per IP; capped at roughly 1,500 tokens; identical requests may return a cached result'). This is rich behavioral disclosure for a non-deterministic 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?

Dense but every sentence earns its place: purpose → return format → behavioral caveats → sibling routing → operational limits. The most decision-relevant information (scope and alternatives) is front-loaded ahead of the caveats, and there is no filler or 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?

For a non-deterministic, paid, rate-limited tool with no annotations and no output schema, the description covers everything an agent needs: return format, approximation behavior, caching, rate limits, token cap, and alternative tools. The schema handles the parameters; the description handles the rest.

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

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

Schema coverage is 100% and each parameter already carries a detailed description covering defaults, the enum values, and the prompt-hint semantics. The description reinforces these traits ('type, length and count are phrased into the prompt rather than enforced') but adds little per-parameter meaning beyond what the schema already states, so the baseline 3 applies.

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 ('Generate filler prose') plus the exact use case ('for mockups and placeholder content'), and enumerates the three flavours (lorem ipsum, random copy, sentences). The closing sentences name the sibling tools it is not (generate_fake_data, draft_email, humanize_text), so an agent can distinguish it from every alternative without opening their schemas.

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

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

Explicitly routes to alternatives with conditions: 'For placeholder people ... use generate_fake_data, which is exact, free and deterministic', 'For a real email use draft_email', and 'to rework existing text use humanize_text'. It also states operational constraints (15 calls/minute, ~1,500 token cap, caching). Nothing is left to inference.

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

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

With no annotations provided, the description carries the full burden, and it delivers richly: it discloses the JSON return shape, the meaning-vs-wording preservation caveat, the authentication requirement with 401 rejection, the paid-model nature, input/output limits and truncation, the rate limit of 30 calls/hour, and the possibility of cached results for identical 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?

Although relatively long, every sentence earns its place: core function, output shape, verbatim-use warning, sibling routing, auth, cost, limits, rate limit, and caching. It is dense but logically ordered and front-loaded with the purpose, not 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?

Given the absence of annotations and an output schema, the description is remarkably complete for a paid, restricted, truncation-prone tool. It covers input constraints, output format, failure modes (401, 413 implied), rate limits, caching, and the semantic caveat, leaving no critical gap for an agent to call it safely.

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 repeats the 10,000-character input cap and adds output-truncation context, but it adds no meaning for the level parameter beyond the schema's already-complete enum explanation. It does not compensate beyond the baseline.

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

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

The description opens with a specific verb and resource ('Rewrite text you already have so it reads less like model output'), clearly distinguishing it from generation tools. It explicitly names siblings generate_text and draft_email and states that 'this one only transforms text it is given,' so an agent can disambiguate it from the other tools in the set.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It says to use generate_text for new prose and draft_email for whole emails, and warns against using this tool on text that must stay verbatim such as quotes, legal copy or code. This directly routes the agent to the correct sibling.

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?

No annotations are present, so the description carries the burden. It discloses fresh browser/no credentials, 7-day caching, parameter clamping, 429/403/502 errors, rate limits, 50s render budget, and thumbio fallback behavior that ignores some options. This is far beyond the bare minimum.

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

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

Front-loaded with purpose and return shape, then fallback and constraints; every sentence adds a distinct fact (auth state, caching, clamping, error codes, cost). No fluff or unnecessary repetition despite the length, which is justified by the tool's complexity and absence of annotations.

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 complex 7-param tool with no output schema and no annotations, the description covers return values (including legacy key), source variants, edge cases (fullPage null height, truncation at 12000px), error codes, rate limits, and cost. An agent has all the context needed to decide when and how to call it.

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 extra context not in the schema: delayMs consumes the same 50-second budget, thumbio fallback ignores fullPage/format/darkMode/delayMs, and height is null for fullPage captures. This is meaningful but not essential given the schema's strong descriptions.

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

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

States a specific action ('Capture a screenshot') with a clear resource ('any public web page') and rendering detail (headless browser with JS/fonts/lazy images). This distinguishes it from the sibling fetch_page_metadata and fetch_site_logo, which are about metadata/logo, not rendering.

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-not conditions: public pages only (no login), no polling due to 7-day cache, and HTTP/private-address restrictions. Does not name alternative sibling tools or say 'use fetch_page_metadata instead', so it stops short of a full 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses permanence, JSON return shape, counted visits, inability to edit/delete, lack of reachability checking, anonymous ownership, and the 30-per-hour rate limit. This is exemplary transparency.

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, covering lifecycle, return values, constraints, and operational limits. The core purpose is front-loaded, and the content is ordered logically from what the tool does to its limitations.

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 no annotations and no output schema, the description fully compensates by explaining the exact return payload, link permanence, non-editable behavior, anonymous creation, accepted schemes, and rate limiting. There is no meaningful gap that would prevent an agent from using it correctly.

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

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

Schema description coverage is 100%, and the schema already explains URL normalization, accepted schemes, customCode constraints, collision behavior, and the random code format. The tool description adds useful context about the response and ownership, but it does not need to add parameter-level meaning because the schema already provides it.

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

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

The description opens with a specific verb and resource: 'Create a permanent razi.pro short link that redirects to a long URL.' It also clarifies what the tool is not for, such as hosting files or checking destination reachability, which distinguishes it clearly from siblings like encode_url or fetch_page_metadata.

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 strong context: only http/https targets are accepted, the URL must already be public, no sign-in is needed, and a rate limit applies. However, it does not explicitly name sibling tools or state when to prefer this over them, so some inference is still 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, the description carries the full behavioral disclosure burden and does so thoroughly: ZIP is not inlined, URL expires in ~24 hours, automatic mode is paid and variable, 400 on no detection, panels are cropped not resized, jpeg/webp use quality 90, 20 calls/hour/IP, third-party URLs rejected, and REST upload is required first.

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 dense and every sentence carries useful information, with the core purpose front-loaded. However, it is a long single paragraph that could be more scannable if modes, limitations, and rate limits were split into bullets, though the length is largely justified by the number of critical caveats.

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 no annotations and no output schema, the description is exceptionally complete: it covers return format, retention, failure behavior, cost, variability, rate limiting, input restrictions, and the upload flow. Almost nothing an agent needs to invoke the tool correctly is left to guesswork.

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 documents all three parameters, and the description adds meaningful semantics: rows/cols only take effect together, omitting both enables automatic detection, and format defaults to lossless PNG with quality-90 lossy options. The description also mentions passing 'fileUrl' even though that parameter is absent from the schema, which is a minor inconsistency.

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 states a specific verb and resource: cut a storyboard, collage, or grid image into separate panels and return them as a ZIP in reading order. It also explicitly distinguishes itself from compress_image by saying it does not shrink a file and cannot take a PDF apart.

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 mode-selection guidance: provide both rows and cols for a deterministic free division, or omit both for vision-based detection with tradeoffs. It names compress_image as the alternative for shrinking files and states the paid-compute rate limit and upload prerequisite.

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.