Razi Web Tools

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

With no annotations provided, the description carries the full burden and delivers: it discloses the return shape ('Returns JSON { decoded }'), specifies error behavior for malformed or truncated escapes, and documents the literal-plus behavior. This goes well beyond a bare function statement and prepares an agent for failure modes.

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 sentences, each earning its place: operation, return shape, error behavior, plus-handling caveat, and alternative routing. The primary action is front-loaded, and there is no redundancy with the input 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?

For a simple single-parameter pure function, this is complete: it states what the tool does, what it returns, how it fails, an important edge-case, and which sibling tools cover related but different encodings. No output schema is provided, but the description supplies the return shape itself.

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% for the 'encoded' parameter, so the schema already documents the input type and UTF-8 requirement, giving a baseline of 3. The description adds meaningful context beyond the schema by explaining the error condition for malformed escapes and the '+' handling decision, raising it to a 4.

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 precise, specific action: 'Reverse percent-encoding with decodeURIComponent', naming the exact resource (percent-encoded strings) and the transformation applied. It also distinguishes this tool from other decode families by explicitly routing Base64 and JWT inputs to different tools, removing any 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 gives clear input expectations (percent-encoded strings) and explicitly names alternatives for other input types: 'For Base64 input use decode_base64; for a JWT use decode_jwt.' It also flags an important nuance—'+' is not converted to a space—which helps the agent decide when historical form-encoding behavior is needed.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the escaping algorithm (encodeURIComponent), that structural characters like : / ? # & = are escaped, and the return shape JSON { encoded }. It also clarifies the practical effect on a whole address, which is the key gotcha.

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 earns its place: definition, return format, the whole-address caveat, the alternative tool, and the decoding counterpart. The main action is front-loaded and there is no fluff or repetition beyond the necessary emphasis.

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

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

For a one-parameter pure function with no annotations and no output schema, the description is fully complete: it states purpose, scope, behavior, return format, alternatives, and reverse operation. Nothing an agent needs to decide or invoke 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?

Even though the schema already covers the parameter 100%, the description adds crucial meaning beyond the schema by clarifying that the 'url' parameter is not a real URL but a value/segment. It also explains the escaping coverage of the parameter, reinforcing and extending the schema's 'Everything outside...' note with concrete structural characters.

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: 'Percent-encode a string with encodeURIComponent' and states the purpose (so reserved characters survive transport inside a URL). It also distinguishes from siblings by noting the encoded output is for a single value/segment, not a whole clickable address, and names decode_url as the reverse.

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 states when to use the tool ('for a single query-string value or path segment') and when not to ('NOT for a whole address you still want to be clickable'). It also gives an alternative for other contexts ('use encode_base64 instead' for JSON, headers, or data URIs) and points to the sibling 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 behavioral disclosure, and it does so thoroughly: no image downloads, no JavaScript execution, client-rendered pages may expose little, results cached for 24 hours, and a rate limit of 20 calls per minute per IP. It also surfaces the redirect-resolving finalUrl behavior, adding meaningful operational context beyond 'read metadata'.

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 earns its place: capability, key return value, relationship to siblings, when to choose alternatives, technical limitations, caching, and rate limits. It is front-loaded with the primary purpose and wastes no words.

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 tool with no output schema and no annotations, the description is remarkably complete: it lists the returned metadata, the redirect behavior, the no-JS limitation, the caching policy, the rate limit, and the correct alternative tools. An agent has enough context to select, invoke, and interpret the result 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%, so the schema already fully documents the single url parameter including the bare-domain and https-assumption behavior. The description adds no additional parameter-specific semantics, so the baseline 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?

The description opens with a specific verb and resource: 'Read a web page's metadata without downloading any images', then enumerates exactly what metadata is returned (title, description, siteName, canonical URL, language, theme colour, generator, feeds, OpenGraph and Twitter tags). It also clearly differentiates itself from sibling tools by naming fetch_site_logo and screenshot_url as the alternatives for logo and visual appearance.

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 routing guidance: 'Use fetch_site_logo instead when the caller wants a logo, favicon or icon' and 'use screenshot_url for that' regarding visual appearance. It also frames this tool as the 'fast, cheap counterpart' for metadata-only needs, making the selection criteria clear.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, and it does so thoroughly: it downloads and measures candidates, ignores possibly-wrong declared sizes, returns unfetchable candidates with an error field, handles SVG without dimensions, includes page metadata, caches results for 24 hours, and enforces a rate limit. This level of detail is exceptional for a tool without structured annotations.

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

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

The description is dense but every sentence adds information an agent needs: what is fetched, how ranking works, return shape, error behavior, SVG caveat, metadata inclusion, sibling alternative, caching, and rate limits. It is front-loaded with the core purpose, 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?

The tool has no output schema and no annotations, yet the description fully compensates by specifying the return object structure, candidate fields, ordering, error semantics, and rate-limit/caching behavior. For a two-parameter tool with rich output behavior, this is complete enough for an agent to invoke it correctly and interpret results.

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, but the description adds meaningful guidance beyond the schema: it explains why rehosted URLs are preferred (hotlink blocking and CORS issues), confirms the default, and describes the trade-off of setting rehost to false. This pushes it above baseline, though the schema already documents the mechanics of both parameters well.

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: 'Get a company's logo from its website URL.' It clearly differentiates itself from fetch_page_metadata, one of its sibling tools, by stating what this tool uniquely does (image candidate discovery and measurement) and what the sibling does instead.

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 fetch_page_metadata as the alternative to use when the logo is not needed, explains why it is faster, and notes that fetch_site_logo already includes page metadata so callers do not need both. This gives an agent a clear decision rule.

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

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

The description fully discloses behavioral traits: fresh browser with no cookies/credentials, 7-day caching, fallback to 'thumbio' when the renderer is unavailable, the high cost of holding a browser worker, and rate limits (10/min, 100/day per IP). This goes well beyond what annotations would cover.

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?

While the description is detailed, every sentence carries essential information—constraints, side effects, or practical tips. No fluff or redundancy; the structure flows logically from the core action to limitations and edge cases.

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

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

Even without an output schema, the description specifies the return format (JSON with url, width, height, format, bytes, cached, source). It also covers key edge cases like page truncation and dark mode limitations, so an agent has all necessary context to invoke and interpret 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?

Every parameter is described with concrete semantics: url requires public http(s), width/height have ranges and defaults, format is an enum, delayMs explains its purpose for animations, darkMode notes its effect depends on site implementation, and fullPage explains the 12000px truncation. The 100% schema coverage is fully leveraged with meaningful context.

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 starts with 'Capture a screenshot of any public web page', naming a specific action and resource. It clearly distinguishes this from URL utilities like decode/encode or metadata fetching, making the tool's purpose unambiguous even without sibling comparisons.

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?

Explicit guidance is given on when not to use the tool: 'cannot be used to poll a page for changes' and 'public pages only... anything behind a login is unreachable'. It also offers usage tips like using delayMs for animations and notes the 12000px truncation for fullPage, giving practical direction.

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 burden and does so thoroughly: it discloses permanence ('does not expire'), irreversibility ('cannot be edited or deleted through this API'), accepted schemes, non-hosting behavior, rate limiting, and the JSON return shape. This is unusually complete behavioral disclosure for a short-link creation 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?

Every sentence earns its place: purpose, return shape, permanence, constraints, non-hosting clarification, and rate limit. It is front-loaded with the core action and avoids 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?

Despite having no output schema and no annotations, the description covers return format, constraints, limitations, rate limiting, and an explicit alternative for the file-upload case. For a two-parameter tool whose schema already handles parameter details, nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already fully documents url and customCode, including validation rules and conflict behavior. The description adds overall context but does not materially improve parameter-level understanding beyond what the schema provides, so the baseline 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?

Description states a specific verb and resource: 'Create a permanent razi.pro short link that redirects to a long URL, and count its clicks.' This clearly differentiates from siblings like encode_url/decode_url and makes the tool's function immediately obvious.

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 this shortens an existing address and does not host anything, directing agents to 'use upload_file to get a URL for a file first.' It also gives a concrete rate limit ('30 links per hour per IP'), giving clear context for when this tool should and should not be used.

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