Razi Web Tools

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

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?

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.