Mart402

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

Goes beyond annotations by disclosing cost ($0.05/document), that inputs are validated before payment (no charge on invalid input), and that OCR is hallucination-guarded. Annotations already cover idempotency and non-destructiveness, so this adds real value; it could say more about failure modes or what the enrich step returns, but the paid-call semantics are unusually well covered.

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 the pipeline summary, then cost, then selection guidance. Dense but every clause carries information; the parenthetical asides make it slightly busier than necessary, keeping it just short of 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?

With an output schema present the return values need no explanation, and annotations cover the safety profile. The description supplies purpose, cost, selection rule, and alternative, so nothing an agent needs to invoke 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?

Schema coverage is 100%, so all three parameters (url, enrich, x_payment) are already documented. The description echoes the optional enrich step but adds no syntax, format, or constraint detail beyond the schema, 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+resource chain (parse PDF invoice, extract fields, verify arithmetic, optional enrich) and explicitly distinguishes itself from the sibling parse_document by input type ('for text only use parse_document'). An agent can select it without opening either 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?

Gives an explicit when-to-use condition ('when a PDF is an invoice/receipt and you want parse + field extraction + arithmetic verification in one paid call') plus a named alternative (parse_document) for the text-only case. Both the selection rule and the exclusion are stated.

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?

Adds real behavior beyond the annotations: $0.03/company pricing, "unresolved lookups never charged", per-field evidence with confidence scores, and honest nulls. These are exactly the cost/quality characteristics annotations cannot express. It doesn't restate the idempotent/openWorld hints, and there is no contradiction with readOnlyHint=false (a paid call is reasonably non-read-only).

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 enough that the core purpose lands early, but it opens with a sentence fragment ("Company name/domain/URL to a verified profile...") and repeats "per-field evidence + confidence" in two separate places, wasting one of its few sentences.

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?

With an output schema present, return values need no explanation, and the description supplies the sources, pricing, null/charge policy, and the country_hint trigger. The x402 payment flow is delegated to the x_payment schema field, which is acceptable but leaves the payment round-trip implicit in the prose.

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 restates that the input is a name/domain/URL and adds the reason for country_hint ('jp' for Japanese companies), but that value-add is marginal over the schema's own "ISO country hint for registry lookups, e.g. 'jp'". The x_payment mechanism is left entirely to 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?

States a concrete transformation (company name/domain/URL into a verified profile) and names the actual primary sources (GLEIF LEI, Japan NTA corporate-number registries). This is far more specific than a generic 'look up company', though it never explicitly contrasts itself with the sibling jp_company_profile, leaving some ambiguity for an agent choosing between them.

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?

"Choose this when you have a company NAME or DOMAIN and need a registry-grounded profile" gives a clear triggering condition, and it tells the agent to pass country_hint 'jp' for Japanese companies. It lacks an explicit when-not or a named alternative (e.g. jp_company_profile), 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?

Annotations already declare openWorldHint=true, idempotentHint=true, destructiveHint=false, so the burden is partly lifted. The description adds genuinely non-structured behavior: automatic JS rendering, robots.txt compliance, and tiered pricing with a cache discount. It does not explain the x402 payment handshake beyond what the schema says, so not a full 5.

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 compact sentences, zero filler: purpose first, cost/behavior second, routing last. Every clause carries information an agent uses for selection or 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?

Output schema exists, so return values need not be described. Given the tool's complexity (payment, modes, caching), the description covers purpose, cost, behavioral traits, and sibling routing, leaving nothing critical to 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%, so baseline is 3, but the description adds economic meaning to mode selection ('$0.005 fast / $0.01 rendered; cached results half price') and ties caching to cost, which the schema's ttl description does not. Minor friction: it says 'rendered' while the enum value is 'heavy', leaving the mapping implicit.

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 ('Extract a web page to clean Markdown + metadata') with the output artifact named. It explicitly carves itself out from structured_extract (schema filling) and pdf_info/parse_document (PDFs), so an agent can route without opening sibling 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?

Explicit selection rules: 'Choose this when you need a web PAGE as clean Markdown to read yourself', with named alternatives for the two nearest competing intents. Both the use case and the when-not conditions are stated.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds genuinely non-structured context: the call is free, and it returns payment config, error codes, and rate limits — useful in an x402/pay-per-call ecosystem. It stops short of saying whether the catalog is cached or how often it changes.

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 single telegraphic sentence with the resource front-loaded and the cost signal last; nothing is wasted. The fragment style ('Free.') is slightly clipped but still unambiguous and appropriately sized for a zero-arg tool.

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?

With zero parameters, rich annotations, and an output schema that already documents return values, the description needs only to identify the resource and its scope — which it does. Enumerating the returned categories (prices, payment config, error codes, rate limits) is a helpful bonus rather than a requirement.

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 tool takes zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to disambiguate. No parameter detail is required or missing.

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 names a specific resource (Mart402 product catalog) and enumerates what it contains: products, prices, payment config, error codes, rate limits. An agent can tell this is a discovery/metadata endpoint rather than a data-processing tool. It does not distinguish itself from the one plausible sibling, search_x402_services, which is a minor gap.

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 only usage signal is the trailing word 'Free,' which implies a cost advantage over paid x402 siblings but never states when to call this versus search_x402_services. There is no statement of prerequisites, ordering, or when-not-to-use.

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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely behavioral fact not present in annotations: the call is free and requires a receipt_id issued by a prior paid response. It omits whether receipts expire or whether the re-fetched payload is identical, but with annotations carrying safety this is solid.

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 sentence, front-loaded with the action and resource, with the clarifying parenthetical placed after the essential information. Every 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?

An output schema exists, so return values need not be described, and annotations cover the safety semantics. The description supplies purpose, parameter provenance and cost behavior; only minor operational details (receipt lifetime, pagination/error behavior on an invalid id) are absent.

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 schema already documents the single parameter including its 'rcpt_...' format. The description's provenance note ('from a paid response') largely restates the schema's own wording, so it adds little beyond the structured field. 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 ('Re-fetch a previously paid result') plus the selection key ('by receipt id'), and adds the key differentiator that this path is free. No sibling tool overlaps, so an agent can identify this as the free retrieval path for a paid result without opening the 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?

The description tells the agent the precondition (you must hold a receipt_id) and where that id comes from ('every paid response carries receipt_id'), which implies the when-to-use condition: retrieving a result already paid for rather than paying again. It does not explicitly name an alternative or a when-not-to-use case, but the context is 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuinely useful behavioral context beyond that: the payload is a *recorded* production response, it is free, and it is flagged with sample:true, which tells the agent the data is illustrative and not live processing of its own input.

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 first sentence is well front-loaded and earns its place, but the trailing 'Available: ...' clause reprints all 28 enum members that already appear in the schema, roughly doubling the length with zero added 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented. The description covers what the sample is, where it comes from, and how it is flagged, leaving only minor gaps (e.g. whether the sample corresponds to the same shape as the live paid call).

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 single 'product' parameter is a fully enumerated, documented string, so the schema carries the semantics. The description's product list simply restates the same enum values verbatim and adds no syntax, format, or selection meaning beyond it — baseline 3.

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+resource ('Free recorded sample response for a paid product') and makes the scope explicit: it returns a preview of the exact response shape rather than doing the work. This cleanly separates it from the paid sibling tools (document_pipeline, enrich_company, ocr_image, etc.), which an agent can distinguish without opening either 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?

Gives a clear selection context: 'see the exact response shape before paying anything', i.e. call this when previewing a paid product's output rather than invoking the paid tool. It does not name an explicit alternative or a when-not-to-use condition, so it falls short of the top band.

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?

Beyond the annotations (idempotentHint=true, openWorldHint=true), it adds cost ($0.01/call), the billing guarantee (errors and unverified rules are never billed), determinism, and that sources are cited. The schema's x_payment note plus the description's framing make the payment handshake clear. Nothing here contradicts the 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?

Front-loaded with the core definition, then cost, then the sibling routing rule. Slightly repetitive — the social-insurance/withholding-tax scope is restated in the 'Choose this...' sentence — but 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?

An output schema exists so return values needn't be explained, and the payment/pricing behavior is fully covered. The one gap is that previous_month_after_si_yen is optional yet described as determining the tax rate, without saying how the calculation proceeds when it is absent.

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?

With 100% schema coverage the baseline is 3, but the description adds a real semantic linkage the schema only hints at: the withholding rate is looked up from the previous month's salary after social insurance, explaining why previous_month_after_si_yen matters and why ytd_bonus_yen feeds the annual cap. It does not clarify what happens when that non-required parameter is omitted.

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 computation (net bonus pay = social insurance + withholding tax) with the governing rule (official rate table, keyed to previous month's salary). It explicitly distinguishes itself from the sibling jp_payroll_net by scope (single bonus vs annual totals), so an agent can route correctly without opening the 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?

Explicit selection guidance: 'Choose this for ONE bonus payment' and 'For annual totals use jp_payroll_net.' Both the when-to-use condition and the named alternative are given, leaving nothing 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?

Beyond the annotations, the description discloses pricing ($0.003/call), determinism, primary-source citation, and a billing policy that errors and unverified rules are never charged. That is meaningful behavioral context for a paid endpoint. It does not explain the readOnlyHint=false flag or payment handshake flow, which the schema's x_payment field covers instead.

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?

Capabilities are front-loaded, followed by price, guarantees, and the mode contract — a sensible priority order. The mode mapping duplicates text already present in the schema's mode description, which is minor redundancy rather than noise.

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?

With an output schema present and full schema coverage, the description need not explain return values, and it covers all five modes and their required inputs. Only the optional x_payment flow and defaults like saturday_off are left entirely to the schema, which is acceptable.

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% across all 10 parameters, so the schema already documents each field including the mode enum. The description's mode-to-param mapping adds orientation but is largely a repeat of the mode parameter's own schema description, so 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 opening sentence names specific capabilities: Japanese holidays, business-day arithmetic, statutory filing deadlines with holiday shift, and wareki conversion. No sibling (jp_payroll_net, jp_consumption_tax, jp_social_insurance, etc.) covers holiday calendars or day arithmetic, so an agent can route here unambiguously.

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 mode-to-parameter contract ('add -> from, days; between -> from, to; holidays -> year; deadline -> kind, base_date; wareki -> date') tells the agent exactly how to configure a call for each use case. It gives clear context but no explicit when-not or alternative-tool guidance, since no sibling offers overlapping functionality.

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 already declare openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is partly covered; the description adds the per-call cost ($0.03/site) and the source constraint (page must be the company's own site, not a directory/lookup). It does not state in prose that a payment header is required for actual execution, though the price mention and the x_payment schema field imply the paid flow. No contradiction with 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?

Three dense sentences with no filler: cost, capability, and routing rule all front-loaded. The opening fragment ('Japanese company site to a standard profile JSON') is grammatically elliptical, which costs a point but does not obscure meaning.

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 the description is not obligated to explain return values, and annotations cover the safety hints; the field list and the enrich_company routing make it sufficient for correct invocation. The only minor gap is that the prose never says the call is payment-gated, leaving that entirely to the x_payment schema description.

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 a baseline of 3 applies, but the description adds real selection semantics for the url parameter — it must be the company's OWN site, not a name or domain query — which the schema's generic 'Absolute http(s) URL of the input' does not convey. The x_payment parameter is left entirely to the schema, which is acceptable given its detail.

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?

Names a specific transformation (page -> standard profile JSON) and enumerates the exact output fields (name, address, representative, capital, contact), so the agent knows precisely what it gets. It also explicitly contrasts itself with the sibling enrich_company, making the two tools distinguishable without opening either 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?

States the selecting condition ('when you have the URL of a Japanese company's OWN site') and the negative case with the alternative to use instead ('for name/domain lookups use enrich_company (country_hint: jp)'). This is explicit when-to-use / when-not-to-use routing that most definitions lack.

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?

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses cost ($0.01/call), the billing guarantee that errors and unverified rules are never billed, and that output is deterministic and cites primary sources. Those are meaningful behavioral traits an agent cannot get from the annotation block; only the x402 payment mechanics are left to 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?

Purpose, pricing, guarantees, and mode routing are front-loaded and the whole thing is compact. The only waste is the long 'Required by mode...' clause, which duplicates the schema's mode description almost word-for-word.

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?

With nine parameters, nested objects, an output schema, and annotations, the description supplies the missing commercial context (price, billing rules, deterministic sourcing) plus mode routing. It is nearly complete; a hint about as_of selecting the rules version and the uncharged x_payment discovery flow would close the gap, though the latter is covered in the schema.

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 every parameter, including the mode->parameter mapping. The description reproduces that mapping verbatim rather than adding syntax, formats, or defaults that the schema lacks, so this is the baseline 3 case.

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?

It names a specific domain (Japanese consumption tax) and enumerates concrete capabilities: per-rate invoice rounding, qualified-invoice validation, simplified taxation, and the 20% special case. That scope cleanly separates it from neighbors like jp_crypto_tax, jp_retirement_tax, and verify_invoice, so an agent can pick it without opening the 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?

The mode->parameter mapping implicitly tells the agent which mode fits which input shape (invoice lines vs. document vs. taxable sales), which is real routing guidance. However, it never states when to prefer this tool over alternatives such as verify_invoice or quote_parse, nor any prerequisites, so usage guidance is only implied.

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 cover the safety profile (idempotent, non-destructive, openWorld), and the description adds genuinely useful behavioral context beyond them: per-call cost ($0.05/call), determinism, primary-source citation, and the billing guarantee that errors and unverified rules are never charged. It stops short of describing rate limits or the output shape, but the pricing/billing disclosure is the key unknown for a paid call.

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 compact sentences, front-loaded with the purpose before cost and correctness claims. Every clause carries information, though the closing billing/guarantee language leans slightly promotional.

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 not be described, and the schema fully documents all parameters. Combined with annotations covering safety and the description covering cost, determinism, and verification basis, an agent has everything needed to invoke 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%, so the schema already documents all seven parameters, including the x_payment header and its unpaid-requirements behavior. The description adds method-level semantics (fees deductible, what counts as a disposal) but no per-parameter syntax or format detail beyond the schema, so 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?

The description states a specific computation (Japan crypto-asset realized income) with the two supported cost methods (total_average, moving_average) and defines what counts as a disposal (sell/spend/exchange). This clearly distinguishes it from the other jp_* tax calculators in the sibling list without the agent needing to open 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?

It names the two available methods but gives no guidance on when to pick total_average vs moving_average, nor any prerequisite or when-not-to-use condition relative to siblings like jp_consumption_tax or jp_retirement_tax. Usage is only implied by the tool's domain.

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?

Adds substantial context beyond the annotations: per-call price ($0.02), billing policy (errors and unverified rules are never billed), determinism, and source citation behavior — none of which appear in the annotation block. It also implies the payment/auth path that explains why readOnlyHint is false, since the call is billed.

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 the core purpose and pricing, and the routing sentence comes before the exclusion. The list of wall types is repeated twice (opening line and 'Choose this for' sentence), a minor redundancy that keeps it from 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?

An output schema exists, annotations cover idempotency and world-openness, and the schema fully documents params — the description supplies the remaining decision-relevant facts (cost, billing, determinism, alternative tool). Nothing an agent needs to select and 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?

Schema description coverage is 100%, so year, as_of, x_payment, and annual_income_yen are already documented in the schema. The description only reinforces the annual-income input implicitly and adds no format or constraint detail beyond it. 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: it 'locates the income walls (tax, social insurance, spousal, student dependent) for an annual income.' It explicitly names the sibling it is not (jp_payroll_net) and what that sibling does instead, so an agent can distinguish it without opening either 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?

Gives an explicit trigger phrase ('how much can be earned before ...' questions) and an explicit exclusion with a named alternative ('does not compute take-home pay (use jp_payroll_net)'). Both the when and the when-not are stated.

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 declare it is idempotent and non-destructive, but the description adds genuinely useful behavioral facts the annotations cannot: a $0.005 per-call cost, deterministic output, primary-source citation, and a billing policy that errors/unverified rules are never charged. That pricing and billing behavior is material for a pay-per-call service; it stops short of describing result format or rate limits.

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?

Two sentences, front-loaded with the computed outputs, with the cost and billing guarantee packed economically into the second. 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?

Annotations and an output schema exist, so return values need not be explained. The description covers purpose, cost, and billing policy, but is silent on what distinguishes the two payment methods or how prepayment interacts with them, which is the kind of nuance an agent would benefit from.

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 echoes the two enumeration values (level payment/principal) and mentions prepayment effect, but adds no format or semantic detail beyond what the schema already documents.

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 names a specific resource (mortgage) and its outputs: schedules under level payment/principal methods, total interest, and prepayment effects. This clearly separates it from the adjacent Japanese-finance siblings (jp_payroll_net, jp_consumption_tax), though it never explicitly names an alternative 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?

There is no statement of when to use this tool versus siblings, nor any prerequisite or exclusion. The agent can infer the domain from 'mortgage schedules', but no routing guidance is provided.

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 annotations covering safety hints, the description still adds real behavioral context: a concrete price ($0.015/call), a determinism guarantee, primary-source citation, and a billing policy that errors and unverified rules are never charged. The schema's x_payment field covers the payment handshake. It loses a point for not clarifying that this is a side-effect-free calculator while readOnlyHint=false, which could make an agent wonder whether calling it mutates anything.

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?

Pricing and the two modes are front-loaded ahead of the parameter requirements, and the whole thing is compact. The final clause restates the `mode` enum description word-for-word, which is dead weight in an otherwise efficient definition.

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 a present output schema (no need to explain returns), full schema coverage, and annotations covering hints, the description supplies the remaining essentials: cost, billing policy, mode selection, and the statutory basis. The only residual gap is the internal structure of the `hours` object, which is minor for a paid, deterministic calculator.

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, and the description's mode sentence is a near-verbatim duplicate of the `mode` property description rather than added meaning. Crucially it does not explain the shape of the nested `hours` object or how regular vs. overtime hours are distinguished, which is the one place the schema ('Hours worked') is genuinely ambiguous.

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?

Names a specific computation (overtime premium pay under Labor Standards Act Art.37, plus Article-36 limit check) with the legal basis, which is an unusually concrete verb+resource statement. It even enumerates the two internal capabilities. It stops short of 5 because it never distinguishes itself from payroll-adjacent siblings such as jp_payroll_net or jp_payslip_audit, leaving the agent to infer which tool owns overtime math.

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 mode breakdown ('pay' vs 'check36') tells the agent which parameters each path needs, which is functional routing. However, that is parameter guidance rather than use-case guidance: there is no statement of when to pick this tool over a sibling, no prerequisites, and no exclusions. Usage is implied, not stated.

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?

Goes well beyond the annotations by disclosing the cost model ($0.02/call), the billing guarantee (errors and unverified rules are never billed), determinism, and the primary-source citation claim. The 'exact NTA Beppyo-5 table' note and the paid nature of the call are consistent with readOnlyHint=false and openWorldHint=true, so nothing contradicts the 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?

Front-loads the core transformation and the sibling routing, which is the right ordering. However the same phrase is substantially restated twice ('Annual gross salary to net take-home (social insurance + income tax + resident tax)' then 'annual gross salary to annual take-home after social insurance, income tax and resident tax'), so one sentence could be trimmed.

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 paid calculation tool: cost, billing exceptions, determinism, scope and sibling alternatives are all covered, and an output schema exists so return shape needn't be described. The payment handshake is only covered by the schema's x_payment field rather than the description, which is a minor gap given this is a chargeable call.

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 explains annual_gross_yen, prefecture, age, year, as_of, dependents and the x_payment flow. The description adds no parameter-level detail beyond restating 'annual gross salary' and the deduction categories, 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 transformation (annual gross salary → net take-home) and enumerates the deduction components: social insurance, income tax, resident tax. It explicitly stakes out the annual scope and names the sibling tools that cover the adjacent cases, so an agent can distinguish it from jp_bonus_net, jp_social_insurance and jp_payslip_audit immediately.

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 to choose this 'for a whole YEAR' and then routes three concrete alternative intents: one bonus → jp_bonus_net, one month's premiums only → jp_social_insurance, verify a real payslip → jp_payslip_audit. Both the when and the when-not are stated with named alternatives.

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 already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the one genuinely new behavioral fact, the flat $0.05 charge, but says nothing about how the x402 payment flow behaves or what happens when required inputs are missing. Useful addition, not rich 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?

Front-loaded with the composite scope and cost, then the routing rule. Slightly wasteful: 'in one call' is repeated twice and 'Flat $0.05' could be merged into the selection sentence, but the whole thing is short and every part is functional.

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 explanation, and the annotations cover idempotency and safety. What remains thin is the payment path: the x_payment parameter's charge-avoidance behavior is only in the schema, not reinforced against the advertised $0.05. Adequate for a 7-parameter composite calculator.

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 only restates that the calculation derives from 'one annual figure' and 'the bonus, if given'; it adds no meaning about prefecture, age, dependents or previous_month_after_si_yen beyond what the schema documents.

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 composite resource: net salary, social insurance and income walls computed from one annual gross figure, optionally with bonus. It explicitly names the sibling it is not (jp_payroll_net) and the difference between them, so an agent can route without opening either 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?

Explicit when-to-use ('when you want take-home pay, social insurance and the income walls... in one call') and when-not ('if you only need the take-home amount, jp_payroll_net is cheaper'), with a cost-based selection criterion. 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?

Goes well past the annotations by disclosing cost ($0.02/call), billing exclusions (errors and unverified rules never billed), determinism, and source citation behavior. The x_payment parameter note completes the payment flow: omitting it returns accepts[]/docs without a charge, which resolves the main operational risk for a paid 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?

Front-loaded with the action and result, then pricing, then the routing rule; no sentence is filler. It is dense – three distinct concerns packed into one block – but each earns its place for a paid, deterministic audit tool.

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?

With an output schema present, return values need not be explained, and the description still summarizes the verdict taxonomy. Payment mechanics, billing guarantees, determinism, and sibling routing are all covered, so an agent has everything needed to decide and 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%, so the baseline is 3; the description earns a 4 by tying parameters to behavior: 'as_of' selects the rules version and 'age' gates care-insurance and age-dependent rules, which is genuinely useful model context. It does not, however, explain the nested 'payslip' payload beyond pointing to '/catalog input spec', leaving the required payload shape off-tool.

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 ('Audit a Japanese payslip') plus the method: recompute statutory premiums and withholding tax from official tables and diff against actual amounts. The output artifact (per-item match/explainable/mismatch verdicts) is named, so an agent knows exactly what it gets back, and the tool is distinguishable from the calculation siblings without opening a 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?

Explicit selection rule: 'Choose this when you HAVE an actual payslip'. It also names the contrasting condition and the specific alternatives ('to compute expected amounts from a salary alone use jp_payroll_net or jp_social_insurance'), so the boundary against the two closest siblings is 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?

Annotations already declare idempotent=true, destructive=false and openWorld=true, so safety is partly covered. The description still adds real behavioral value beyond the schema: per-call pricing ($0.02), determinism, primary-source citation, and a no-charge-on-error policy, plus the x_payment parameter documents a dry-run payment-requirements flow.

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 tight, front-loaded fragments with no filler; the core computation leads and pricing/behavioral caveats follow. Every sentence earns its place, though the terse fragment style slightly reduces readability.

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?

With a 100%-covered schema and an output schema present, return values need no explanation and the description wisely omits them. It covers rules and billing behavior adequately; the only notable gap is routing guidance relative to sibling tax tools.

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 explains all five parameters including the payment header, disability and officer flags. The description references years-of-service deduction logic but adds no syntax, format, or edge-case detail beyond that, 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 the resource precisely (retirement income tax) and the specific computation enclosed (deduction by years of service, half-taxation rules, withholding rounding), so an agent knows exactly what output to expect. It does not, however, differentiate itself from the dense cluster of jp_* payroll/tax siblings (e.g. jp_payroll_net, jp_consumption_tax), leaving the agent to infer the boundary.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative among the many sibling tools that also compute Japanese income taxes. The agent must guess whether this is the right tool versus jp_payroll_net or jp_payslip_audit.

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?

Goes well beyond the annotations by disclosing per-call pricing ($0.01/call), the billing guarantee (errors and unverified rules are never billed), determinism, and primary-source citation behavior. This also contextualizes the readOnlyHint=false annotation, which would otherwise look surprising for a pure calculation 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?

Front-loaded with the what and the data source, then pricing, then the sibling routing rule — no wasted sentences. Slightly dense with parentheticals, but every clause carries 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 deterministic, output-schema-backed calculation tool, the description covers source, scope, cost model, and alternative routing; return values need not be explained given the output schema. Nothing needed to invoke 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?

Schema description coverage is 100%, so all five parameters (including the x_payment payment flow and age-gated rules) are already documented in the schema. The description adds only the framing that remuneration is a grade-table lookup, which the schema already says; 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 resource (monthly social insurance premiums) with a specific source (official Kyokai-Kenpo grade table, FY2026), and explicitly bounds the scope to premiums only, excluding tax. An agent can distinguish it from jp_payroll_net without opening either 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?

Explicit 'Choose this when you only need...' condition plus a named alternative and its selection rule ('for take-home pay use jp_payroll_net'). Both the when and the when-not are stated.

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 cover the safety profile, and the description adds genuinely useful behavior the annotations cannot convey: every call is a 3-run consensus with disclosed spread and item agreement, the calibrated range contained truth in 26/30 weighed meals, and the cost is $0.05/image. Missing is any statement of what happens on failure/retry beyond the pack_code note in 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?

Front-loaded with the core purpose in the first clause, followed by output contents, calibration evidence, consensus behavior and price. Three of the five sentences earn their place; the dense feature list ('PFC balance ratios and alcohol-aware 4/4/9 cross-checks') drifts toward marketing padding.

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 shape need not be re-explained, and the description still covers cost, consensus methodology and calibration honesty. The main gap is routing guidance relative to the many sibling extraction/OCR tools, which is not addressed at all.

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 five parameters (hints, image_url, image_base64, x_payment, pack_code) are already fully documented in the schema. The description adds almost no parameter-level meaning beyond echoing that nutrition output is produced, 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 ('Analyze a meal photo to itemized nutrition JSON') plus an enumerated scope of outputs (dishes, portions, kcal, macros, confidence). That is clearly distinguishable from siblings like ocr_image, portrait_analysis and document_pipeline 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?

Usage is only implied through the output description and the hints note ('measurably improves accuracy on regional home-style meals'). It never says when to pick this over ocr_image or structured_extract, and gives no exclusions or prerequisites beyond the payment mechanics that live in the schema.

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 declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds real operational context beyond that: dual-engine consensus, calibrated confidence, per-segment corroboration, and a flat $0.05/image cost, which matters because this call is billed. It does not mention the x402 payment handshake, though the schema covers it.

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, zero filler, front-loaded with the capability and cost, then the routing rule. Every 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?

An output schema exists, so return-value explanation is unnecessary, and the schema documents the one-of input and payment header. The routing rule and cost complete the picture; only the payment-requirement flow is left entirely to the schema.

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 lang, image_url, image_base64 and x_payment are already documented in the schema. 'Japanese-strong' hints at the lang default but adds no syntax or format detail 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?

Specific verb (OCR) plus resource (one image) plus the differentiating capabilities (dual-engine consensus, calibrated confidence, per-segment corroboration) and the language specialty. It explicitly names the sibling it is not: parse_document.

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?

States the selection condition directly: 'Choose this when the input is an IMAGE (photo, screenshot, receipt); for PDFs use parse_document.' Both the when and the when-not are given, with the alternative named.

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 already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context beyond those: the data is free, spans a 12-week window, and includes weekly series, trend, volatility, and badge, which helps the agent understand the payload without contradicting 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?

Two sentences, front-loaded with the core resource and data content, followed immediately by the usage condition. 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 simple read-only lookup with an output schema and complete annotations, the description supplies what is needed: what the tool returns, what the 12-week window means, and when to invoke it. Parameter requirements are fully documented in the schema, so no critical gap remains.

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 tool has one parameter with 100% schema description coverage, including an example domain. The description adds no syntax or format details beyond the schema, so the baseline of 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 resource — 12-week measured score history for an x402 operator from the Market402 index — with the key returned dimensions (weekly series, trend, volatility, badge). It does not explicitly differentiate from sibling tools such as search_x402_services, so it falls short of a 5.

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 a clear use condition: 'Check a seller's record before your agent pays an unfamiliar endpoint.' It gives context but does not name alternatives or when-not-to-use cases, so it is strong but not exhaustive.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description adds the substantive behavioral detail those annotations omit: the 402 response quotes an exact price, omitting x_payment returns payment requirements without being charged, and quote_id locks the price. This is real value beyond structured fields, though limits such as document size or failure handling are unstated.

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 dense sentences, all load-bearing, with the core capability front-loaded before routing and payment mechanics. The stacked parentheticals in sentence one are slightly packed, but nothing is padding or repetition of the name/title.

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-format explanation is unnecessary. For a 3-parameter paid tool with no required fields, the description covers capability, output form, parameter choice, prerequisites (pdf_info), alternatives (document_pipeline), and the payment lifecycle an agent must navigate to invoke it successfully.

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 baseline is 3. The description goes further by explaining the semantic relationship declared only structurally in x-required-one-of: 'One of the two is required', plus the tradeoff that url is the one-step form while quote_id carries a pre-fixed price. That interpretation is not derivable 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?

Names a specific verb and resource with the exact output form: 'Parse a PDF to structured Markdown'. The parentheticals add distinguishing traits (hallucination-guarded OCR, Japanese-strong) that separate it from the many other PDF siblings. An agent can identify this tool without opening the 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?

Explicit routing: choose this when the input is a PDF and full text as Markdown is wanted; call pdf_info first if scanning status is unknown; use document_pipeline for invoices needing verification. It also states how to choose between url and quote_id (one-step vs. fixed price). Both when-to-use and alternatives are covered.

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 cover the safety profile (destructive=false, idempotent=true, openWorld=true), and the description adds the cost dimension ('$0.001', 'cheapest real call') plus the cheap-probe-before-parsing workflow, which is genuine context not in the structured fields. It does not contradict readOnlyHint=false (the paid call is a real side effect), though it never explicitly frames itself as a metered x402 call — that detail lives only in the x_payment schema 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?

Two dense sentences with zero filler; the value proposition and cost come first, then the routing instruction. Every 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?

An output schema exists, so return values need not be explained, and the description still previews the payload (pages, metadata, text volume, scan estimate). Purpose, cost, and downstream routing are all covered for a 2-param read 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 description coverage is 100%, so both url and x_payment are already documented in the schema, including the omit-to-get-payment-requirements behavior. The description adds no parameter-level syntax or format detail beyond that, 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 ('PDF facts') and enumerates the exact outputs: pages, metadata, per-page text volume, scanned-or-not estimate. It explicitly positions itself against siblings parse_document, pdf_pages and document_pipeline, so an agent can distinguish it 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?

'Choose this first for any unknown PDF (cheapest real call); then parse_document, pdf_pages or document_pipeline' gives an explicit ordering rule and names the alternatives that follow. When-to-use and which-sibling-next are both spelled out rather than implied.

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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds two facts those annotations do not: the operation is deterministic and it costs $0.003, which is genuinely useful for a paid tool. It still says nothing about failure behavior or turnaround, hence not a 5.

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?

Two short fragments, front-loaded with the operation and its cardinality limit, and each clause carries information: ordering, bound, determinism, price. There is 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?

With an output schema present, return values need not be explained, and the payment mechanics are documented in the x_payment parameter. The description signals that the call is paid ($0.003), covering the main non-schema concern; only error/latency expectations are absent.

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 two parameters are fully documented there, including the ordering constraint and the x_payment flow, so the baseline of 3 applies. "In order" echoes the schema's own wording rather than adding syntax or format detail.

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 names a specific verb and resource ("Merge 2-10 PDFs into one, in order"), which is unambiguous and inherently distinguishes it from the read-oriented siblings pdf_info and pdf_pages. It stops short of explicitly contrasting itself with any sibling, so it lands at clear-but-undifferentiated.

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?

Usage is implied by the constraint (combine 2-10 PDFs) plus the cost note, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as pdf_pages or document_pipeline. The price signal gives a decision-relevant cue but no routing 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?

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds genuinely new behavioral context: a fixed $0.002 cost and the fact that output goes 'into a new PDF' (input is not mutated). It does not disclose error behavior for invalid ranges or payment-flow details beyond what the x_payment schema param already says.

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?

Two tight sentences, front-loaded with the action and scope, followed by the differentiators (deterministic, cost). No filler or 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?

An output schema exists so return values need no explanation, and the description covers purpose, cost, and non-destructive output. It is slightly incomplete on error handling for malformed ranges and on how it relates to sibling PDF tools, but adequate for a simple, well-annotated extraction 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 description coverage is 100%, so the schema already documents url, pages, and x_payment. The description's '1-based ranges (e.g. 1-3,7)' merely restates the pages schema description, adding no syntax or edge-case meaning beyond 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?

States a specific verb (Extract), resource (pages from a PDF), input format (1-based ranges), and output (a new PDF), which lets an agent separate it from siblings like pdf_merge or pdf_info by function. It stops short of naming those siblings explicitly, so there is no direct differentiation.

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 purpose implies when the tool applies (you have a PDF and want a subset of pages), but there is no explicit when-to-use vs alternatives guidance and no mention of when to prefer pdf_merge or pdf_info. Usage is left to inference from the description.

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?

Goes well beyond the annotations by disclosing cost ($0.05/call), the x402 payment handshake (omitting x_payment returns payment requirements without being charged), retry-credit behavior via pack_code, and privacy guarantees ('no identification; images not stored'). It also flags cross-photo lighting consistency as part of processing, which an agent needs in order to submit valid inputs. Nothing here contradicts the readOnlyHint/openWorldHint/idempotentHint 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 method, cost, and privacy caveats are front-loaded before the routing sentence, and every sentence carries information. It is dense — the first sentence packs method, pipeline, and output into one clause — but 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?

An output schema exists, so return shape needn't be restated, and the description still names the verdict and palette contents. Combined with the payment mechanics, privacy statement, input-count guidance, and sibling routing, an agent has everything needed to call this 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 documents every parameter, and the description only echoes the '1-3 portraits' shape and the purpose of multi-image input. It adds marginal semantics (why multiple photos help) but no format or validation detail 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 ('personal color analysis from 1-3 portraits') and explains the mechanism (CIELAB/ITA colorimetry cross-checked with vision-model attributes, deterministic rule table). It also explicitly names the sibling tools it is not, so an agent can distinguish it from style_profile and style_report 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?

Gives an explicit selection rule: 'Choose this when you need only the seasonal color verdict and palette as JSON,' then routes the two alternative needs to style_profile (fuller styling verdict) and style_report (PDF for a human client). When-to-use, when-not-to-use, and alternatives are all present.

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?

Goes beyond annotations by disclosing that the check is deterministic and uses no LLM, and by stating a concrete rate limit of 10/hour/IP. Annotations already cover safety traits like read-only and idempotent, and the description adds useful operational 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?

Front-loads the free pre-check purpose, then tightly lists the checks, deterministic nature, and rate limit. Every clause earns its place with no 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?

For a simple two-parameter pre-check tool with full schema coverage and an output schema, the description covers purpose, usage routing, determinism, and rate limit. Nothing essential 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?

Schema description coverage is 100% and both parameters are fully documented there, so the description is not required to add parameter meaning. It does not add syntax or format details beyond the schema, which is the baseline-3 case.

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: a free analyzability check on a portrait photo, including what it verifies (face detection, quality issues like clipping/color cast). It explicitly positions itself as distinct from portrait_analysis by being the pre-check before paying.

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?

Names the alternative tool portrait_analysis and states the condition for using this one: before paying for the full analysis. This gives an agent a clear routing rule without needing to inspect either schema.

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 already cover readOnly, idempotent, and non-destructive, so the safety profile is done. The description adds genuinely new context the annotations don't carry: the operation is free, no payment occurs, and the returned quote_id is the credential for the follow-up parse_document call.

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?

Two sentences, no filler, and the value proposition ('free', 'exact final price', 'before any payment') is front-loaded where the agent needs it.

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-value documentation isn't required, and the description still previews the key return fields and the quote_id handoff. The only gap is any precondition on the input URL, which is minor for this simple one-param 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?

One parameter with 100% schema description coverage ('PDF URL'), so the schema handles the semantics. The description adds nothing about URL constraints (public accessibility, size limits), 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 (quote a PDF parse) plus what the quote contains: page count, route, and exact price. It clearly distinguishes itself from parse_document by framing itself as the free pre-payment step.

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 positions the tool as coming 'before any payment' and tells the agent to use the returned quote_id with parse_document. It doesn't spell out when to skip this tool (e.g., if a quote is already held), so it stops short of a full when/when-not statement.

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 annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so they already establish the safety profile. The description adds behavioral substance beyond them: the exact price, the fact that 10 single-use codes are returned, that the codes do not expire, that the codes should be treated like cash, and that each code must be passed to style_report as pack_code. It does not explain whether retrying after a charge could charge again, which is a minor gap against idempotentHint=true.

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 pricing and what-you-get information comes first, followed by the anti-confusion clarification and then the when-to-use guidance. The pricing parentheses are dense but carry real decision value; no sentence is 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?

An output schema exists, so the description need not explain the return shape. It covers pricing, what is delivered, code lifetime, and the handoff to style_report. It omits only the payment-requirements probe, which the schema's x_payment description already documents.

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?

There is only one parameter, and schema coverage is 100%; the schema already explains the optional x_payment header and the flow for receiving payment requirements without being charged. The description adds no detail about x_payment itself, so the baseline 3 applies. The downstream integration note ('pass each code as pack_code to style_report') is helpful but describes the output codes, not this tool's input parameter.

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?

It states clearly that this is a volume-pricing purchase: one $19.90 payment yields 10 single-use style_report credit codes. It also explicitly distinguishes itself from its siblings, saying 'Not an analysis: it buys prepaid style_report credits' and pointing to style_report as the consumer of the codes.

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 a concrete condition for choosing this tool: 'Choose this only when you expect to produce several style_report PDFs.' It also implies the alternative by citing the $2.99 single-unit price. The condition that selects this tool is stated, not 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: results are real probed resources, each carries a measured 402 Score, and the call is free — none of which the annotations convey.

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-loaded with the action and index identity, then the differentiator (verified/probed, scored) and the cost note. 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?

With an output schema present, return structure needn't be explained, and the description covers scope, result trust, and cost. It could say slightly more about query semantics (multi-word, matching behavior) but is essentially complete for a two-parameter read 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 description coverage is 100%, so both parameters (q, limit) are already documented in the schema, including defaults and example keywords. The description's mention of 'by capability' and examples largely duplicates the schema rather than adding syntax or validation detail, so 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 (Search) and resource (the Market402 verified index of x402 services) with the query dimension (by capability) called out. An agent immediately knows this is a capability-keyword search over a curated service catalog, distinct from every sibling tool listed.

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 phrase 'Search ... by capability' implies when to use it, and the examples ('ocr', 'market-data') guide query construction, but there is no explicit when-to-use/when-not statement and no named alternative among the many unrelated siblings. Usage is implied rather than specified.

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 already declare openWorldHint=true and idempotentHint=true, and the description adds genuinely useful context the schema doesn't: the $0.03/call cost and the hybrid LLM+deterministic execution model. It doesn't explain the unexpected readOnlyHint=false or any rate/latency behavior, but the pricing disclosure is meaningful value beyond 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?

Two tight sentences, with the core purpose and cost front-loaded before the routing guidance. No wasted 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?

An output schema exists, so return values need not be described, and the payment path is covered in the x_payment schema. Cost and sibling routing are provided, though the description could say more about input limits (page/PDF size, schema complexity) for a service with a per-call fee.

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 url, schema, x_payment, and instructions fully. The description reinforces 'your own schema' and 'any URL/PDF' but adds no syntax or format detail beyond the schema. 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+resource ('Fill YOUR JSON schema from any URL') and adds the mechanism ('hybrid LLM + deterministic canonicalization'). It also names the sibling tools it is not (enrich_company, jp_company_profile), so an agent can distinguish it without inspecting 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 states when to choose it ('when you have your OWN JSON schema to fill from any page') and names the alternatives for the company-profile case. The routing condition is 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?

Annotations already declare openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is partly covered. The description adds genuinely new behavior: a flat $0.05/call charge (non-read-only compute), input cardinality (1-3 face photos), and the exact analytical equivalence to style_report. It does not discuss failure modes for poor photos or image retention, leaving a small gap.

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 value proposition and component list are front-loaded, and the routing guidance comes last where it is needed. It is dense with domain jargon (colorimetry consensus, geometry rules) but no sentence is filler; a slightly tighter break into sentences would improve scanability.

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?

With an output schema present, return values need not be explained, and cost, inputs, and sibling relationships are all covered. The questionnaire and body_image_base64 params defer to '/catalog input spec', an external reference the agent may not have loaded, which is the only notable gap.

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 explains every parameter, including the x_payment flow and image formats. The description only adds the '1-3 face photos, optional full-body + questionnaire' constraint, which is marginal over the schema's 'Up to 3 objects' note; 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?

The description names a specific verb+resource ('Integrated styling verdict') and enumerates its components (seasonal color, face-impression zone, body frame, integration rules). It explicitly distinguishes itself from both style_report (PDF) and portrait_analysis (color only), so an agent can route correctly without opening 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?

'Choose this when you want the integrated styling analysis as JSON to use or render yourself' gives an explicit selection condition, and 'For color only use portrait_analysis' names the alternative and the case that selects it. The style_report relationship is also clarified as output-format-only, not analytical difference.

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?

Adds substantial context the annotations cannot carry: flat $2.99/call pricing, $1.99 with a prepaid report_pack credit, and the x_payment behavior where omitting the header returns payment requirements without being charged. It does not address whether a retried/duplicate call re-charges or how idempotency interacts with billing, which matters for a paid tool even though idempotentHint is set — that omission keeps it below a 5.

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-loads the deliverable in the first clause, then the audience, then pricing, then the sibling comparison — a sensible priority order with no filler sentences. It is dense but slightly over-packed, with the report-contents parenthetical competing for attention in the opening sentence.

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 the description needn't enumerate return values (though it names report_pdf_base64 and profile JSON), and the payment and pack-credit story is fully explained. The gap is the 11-parameter input surface: the description never mentions that at least one of image_url/image_base64/images is required, leaving that constraint entirely to the schema for a complex, nested-object call.

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 reinforces two parameters (language en/ja, pack_code as prepaid credit replacing payment) but adds no syntax or format meaning beyond what the schema already documents, and says nothing about the at-least-one-image requirement encoded as x-required-one-of.

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 artifact: renders a style-profile analysis as a finished PDF report in English or Japanese, returned as report_pdf_base64 plus profile JSON. It enumerates the report contents (palette with color names, outfit formulas, draping boards, confidence) and explicitly names the sibling style_profile as the JSON-only alternative, so the agent can distinguish the two without opening either 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?

Gives an explicit decision rule: 'Choose this when the result goes to a HUMAN end-client as a finished document; if you will present the result yourself, style_profile returns the same analysis as JSON for less.' It also names the audience condition ('for agents serving human end-clients') and the cheaper path via pack_code, so when-to-use and when-not-to-use are both covered.

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 cover the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true for the NTA lookup), so the description's added value is the per-call price ($0.015/call) and the specific external check performed. It does not explain how the x_payment charge/accepts flow interacts with a failed verification, which keeps it short of a 5.

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 what gets checked, then price, then routing guidance in a single compact block. Dense but each clause carries information; the only mild redundancy is restating 'invoice' across the check list.

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?

Output schema exists so return values need not be re-explained, and the mention of 'accounting-ready JSON' plus the precise check list, cost, and sibling routing covers everything an agent needs to call this 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 the schema itself documents fields, x_payment, and line_items, so baseline is 3. The description only lightly reinforces this by naming 'line-item totals' and the per-call fee; it adds no format, enum, or validation detail 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?

States a specific verb (verify) plus resource (extracted invoice fields) and enumerates the actual checks performed: arithmetic consistency, line-item totals, JP registration check-digit, and NTA registry lookup. It also explicitly separates itself from document_pipeline, so an agent can pick it without opening either 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?

Gives an explicit when-to-use ('when you already HAVE invoice fields from your own extraction') and an explicit when-not with the named alternative ('to start from a PDF use document_pipeline'). Routing is unambiguous.

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