zFinia Intelligence

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

With no annotations, the description carries the burden and it discloses the key side effect: payment of 1000 atomic USDC on Base via exact x402, and that the MCP itself does not pay. It does not detail payment mechanics or failure behavior, but the cost warning is substantial and non-obvious.

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

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

Three short sentences front-load the core action and outputs, then add the critical scope exclusion and payment requirement. Every sentence earns its place with no filler.

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

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

For a three-parameter tool with an output schema, the description covers inputs, scope, and the paid nature of the call. The main residual gap is the precise role of large_text and how the x402 payment is expected to be arranged, but nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must add meaning. It names all three parameters and constrains the colors to #RRGGBB, but it does not explain how large_text affects the WCAG thresholds or what values are expected beyond the schema's examples.

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 ('Return') and names the exact outputs (contrast_ratio, wcag_aa, wcag_aaa) plus the input scope (one #RRGGBB pair). It also disclaims interface-wide claims, which helps separate it from any broader accessibility audit tool.

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

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

It clearly frames the tool as per-pair WCAG contrast checking ('one caller-supplied #RRGGBB pair') and explicitly rules out interface-wide accessibility claims. It does not name sibling alternatives or spell out when not to call beyond that scope, 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?

With no annotations, the description carries the full burden. It discloses that it does not fetch data and specifies a payment requirement (3000 atomic USDC on Base via exact x402) and that MCP does not pay. However, it does not state whether the operation is read-only, idempotent, or has any other side effects, leaving some behavioral aspects unaddressed.

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, each adding distinct information: purpose, data-fetch negative, and payment requirement. It is dense and front-loaded, with no fluff, though slightly jargon-heavy. It earns a high score for efficiency.

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 covers purpose, usage contexts, and payment, but omits parameter semantics and details about the output codes. An output schema exists, which may mitigate return-value explanation, but the tool's complexity (5 parameters, multiple enums) suggests the description should clarify what the incompatibility codes mean and how to interpret them. It is adequate but not fully 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 0% and the description provides no explanation of any parameters (source_fields, target_fields, comparison_mode, canonicalization, contract_version). While the schema has enums and examples, the description fails to add semantic meaning to these inputs, leaving the agent to infer from the schema alone.

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

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

The description states a specific action ('Gate caller-supplied field contracts') with clear contexts (ingestion, migration, CI, M2M handoff) and an explicit outcome (returns compatible plus stable incompatibility codes). It clearly distinguishes the tool from its siblings, which target unrelated domains (accessibility, outcome routing, machine economy, contract regression, catalog evidence).

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 use cases ('before ingestion, migration, CI, or machine-to-machine handoff') and even notes a non-use ('Does not fetch data'), which prevents misuse. However, it does not mention any alternative tools or when not to use this tool beyond that single negative, so it lacks explicit exclusionary 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, the description carries the full transparency burden, and it delivers: it discloses that tools/call quotes first and may return PAYMENT_REQUIRED, that batches pay sequentially on live rails, that POST /v1/router/quote is unpaid, that the MCP does not fetch URLs, that MCP does not pay, and that GET /v1/router is free. This is unusually detailed 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 tightly packed and front-loaded with the decisional use case, then moves into input semantics and payment behavior. It is dense but contains minimal filler; the only cost is that some clauses, like the price list in parentheses, are terse enough to require careful parsing.

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 9-parameter router with nested objects and an output schema, the description covers the essential selection and invocation context: objective handling, input restrictions, payment behavior, protocol choices, and free/introspection endpoints. Minor gaps remain for how required_output and buyer_metadata interact with routing, but the enums and output schema reduce the need for further elaboration.

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 only 56%, so the description meaningfully compensates by explaining objective aliases, top-level field folding, fg/bg aliases, and how #RRGGBB pairs in the objective become contrast inputs. Enum-based parameters like latency, evidence, and preferred_protocol remain self-explanatory, and max_price and inputs already have schema descriptions, so the overall parameter semantics are strong.

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 an explicit, specialized purpose: use this tool when you need an outcome but do not already know which zFinia utility to call. It specifies the key input ('Send objective') and aliases, and clearly positions it as a router rather than a direct utility, distinguishing it from sibling tools like accessibility_contrast_calculator.

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 first sentence gives a crisp when-to-use rule with an implied exclusion: if you already know the utility, you should not use this router. It also adds practical usage constraints around payment rails, quote behavior, URL fetching, and protocol options, helping an agent decide whether and how to invoke 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 no annotations provided, the description carries the disclosure load. It discloses the payment requirement (10000 atomic USDC on Base via x402), that MCP does not pay, and that empty items is a valid response. It omits failure behavior or authorization requirements, so it is solid but not exhaustive.

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 short sentences, each carrying a distinct fact: when to use, what returns, empty-valid, and payment responsibility. There is no verbose prose or schema repetition; it can be skimmed in a few seconds.

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 covers the main loop (cursor → delta → nextCursor), the edge case of empty results, and the cost/payer model. It does not explain how to actually pay via x402, but given the presence of an output schema and detailed parameter coverage, the agent has enough context to call the tool 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 covers most parameters (75%), so the baseline is a 3. The description adds a small amount by framing the cursor as integral to the polling workflow ('returns delta items and nextCursor for the next poll'), but it does not enrich the meaning of maxItems or the exact relationship between since and cursor beyond what the schema already states.

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 returns delta items and nextCursor for polling, and scopes it to machine-economy changes after a prior zCursor check. However, it does not explicitly distinguish itself from sibling tools, so an agent must infer that sibling tools are unrelated from their names.

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 opening sentence gives an explicit trigger: use it when the agent has already checked zFinia and needs only material changes since the last cursor. It does not state exclusions or name alternative tools to use when the precondition is not met, missing a small opportunity to route the agent away.

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

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

Annotations are absent, so the description carries the full burden. It discloses a critical behavioral trait: 'Pay 50000 atomic USDC on Base via exact x402. MCP does not pay.' It also states it does not fetch URLs and produces reproducible evidence, adding value beyond the schema's structured fields.

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 terse, information-dense sentences. Purpose is front-loaded, followed by payment requirement and exclusion, with zero filler or redundant phrasing.

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 nested parameters and no annotations, the description covers purpose and payment but omits the role of policy and merchant_service_id. The schema provides detailed examples and there is an output schema, so return values are handled. Still, an agent would need to deeply inspect the schema to understand how policy shapes the comparison.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter meaning. It only refers to 'baseline/current merchant payment and field contracts,' which maps to baseline and current, but leaves merchant_service_id and policy entirely unexplained. No guidance on how policy constraints affect the comparison.

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: 'Compare caller-supplied baseline/current merchant payment and field contracts before deployment.' It also lists what it returns (reproducible rule evidence and fixes) and what it does not do (URL fetching or security audit), which clearly differentiates it from siblings like data_compatibility_checker.

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: 'before deployment' and explicitly excludes 'URL fetching or security audit,' telling the agent when not to use it. However, it does not name alternative tools for those excluded tasks, 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 provided, the description carries the full burden and meets it: it discloses the payment side effect (amount, token, network, mechanism), the 'authorized' precondition, the explicit 'No URL fetching' boundary, and the SHA-256 provenance computation. These are the material behavioral facts an agent needs; only minor mechanics (how authorization is verified) remain undisclosed.

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

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

A dense, compact paragraph with no filler. The core conversion purpose is front-loaded, followed by the critical boundaries (no fetching, payment). Every sentence earns its place; 'MCP does not pay' is an efficient clarifying clause. Slightly dense in a single run-on structure but appropriately terse overall.

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

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

An output schema exists, so return values need no restating. The description covers the essential operational facts: payment requirement, no-fetch restriction, authorization precondition, and output format. The only notable gap is the unstated mechanism/verification for the 'authorized' precondition, which is minor given the richness already present.

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

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

Schema coverage is 0%, so the description must compensate. It explains 'html' well (must be schema.org Product JSON-LD embedded in product-page HTML) and 'No URL fetching' disambiguates 'source_url' as provenance metadata rather than a fetch target. However, it never explicitly defines 'source_url' as the canonical URL the HTML was obtained from, leaving its exact role partially inferred.

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: 'Convert caller-supplied authorized public product-page HTML containing schema.org Product JSON-LD into normalized Product/Offer evidence with SHA-256 provenance.' It names inputs, output format, and a distinctive trait (SHA-256 provenance). The siblings (contrast_calculator, compatibility_checker, machine_economy_changes_since) are clearly unrelated, and 'No URL fetching' further disambiguates the operation.

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 operational context: the caller must supply the HTML ('caller-supplied'), the tool does not fetch URLs, and a payment of 100000 atomic USDC is required via exact x402 with the note 'MCP does not pay.' It lacks explicit when-not-to-use or named alternatives, but the sibling set is so distinct that no exclusions are needed.

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