Fillin

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

Even though annotations already provide readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial beyond-annotation behavioral context: exact cost range ($0.01–$0.05 USDC), auth mechanisms (x402, Bearer, X-Payer-Address/Nonce/Signature), rate limits (1 free taste/IP/day, free 20-query trial), the auditable `selection` manifest contract, billing parity across substrates, and a safe-default behavior for unknown readers. 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?

The purpose is front-loaded in sentence one, which is good. However, the description is long and dense: payment fallback flows and credential details consume several sentences, some phrasing is cryptic ('Glyph as a language anyone can speak', 'flat-tile billers'), and the trial/signup details overlap with the 1-free-taste note. Every sentence has some content, but the structure is inflated and 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?

For a tool with a payment/auth state machine, the description is unusually thorough: it prescribes exact fallback tool sequences (fillin_probe, fillin_signup, fillin_payment_challenge), exact headers, billing semantics, and the selection manifest. Since an output schema exists, return-value documentation isn't the description's job. Minor gaps remain — 'glyph' is never precisely defined and the 'Requires payment... On payment_required' interplay is slightly ambiguous — but for this complexity level it's near complete.

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

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

Schema description coverage is 100% and the schema itself is unusually rich (reader billing categories 'flat-tile/pixel billers', verbatim auto-detection of fenced code, max length). The description reinforces the text parameter's purpose and clarifies billing implications ('text and glyph cost the same here'), but adds little beyond the schema's already-detailed parameter explanations — so the high-coverage 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?

The description names a specific action (encode user-supplied text) and a specific outcome (return whichever substrate — glyph image or plain text — is cheaper for the reader's token billing). It also differentiates from siblings explicitly: 'unlike retrieve_auto's answer substrate' and 'Not a search-result rendering trick' (distinguishing it from glyph_search). An agent can tell what this tool is for 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?

The description gives concrete usage context ('Give it a tool result, a RAG chunk, a document'), an exclusion ('Not a search-result rendering trick'), a named alternative (retrieve_auto), and explicit conditional flows for the payment_required case (fillin_probe → fillin_signup, or fillin_payment_challenge → retry with X-Payer-* headers). It stops short of a full 5 because it never explicitly says 'use glyph_search for search-result rendering' or states when not to use encode beyond that one exclusion.

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?

Despite annotations already providing readOnlyHint, openWorldHint, and idempotentHint, the description goes far beyond by disclosing payment requirements (USDC/x402 or Bearer), rate limits (1 free taste/IP/day), error handling (payment_required), synthesis behavior (150-250 word answers with citations), and the full return structure. This is comprehensive behavioral disclosure that the annotations do not cover.

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

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

The description is well-structured with a clear opening, payment/usage sections, and a return schema. It is fairly long but each sentence adds meaningful information (payment flows, usage scenarios, return fields). It could be slightly tightened, but the density is justified given the tool's complexity.

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

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

Given the tool's complexity (payment flows, multiple auth modes, error handling, synthesis behavior), the description is exceptionally complete. It covers prerequisites, exact retry procedures, the intended user profile, and even the return shape beyond the provided output schema. Nothing an agent needs to call this 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% and the input schema already describes each parameter (query, cutoff, k) adequately. The description does not add new parameter-specific meaning beyond what the schema provides; it focuses on tying parameters to the broader synthesis pipeline. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description explicitly states a specific verb ('synthesized post-cutoff answer with inline citations') and resource ('retrieved post-cutoff documents'), and distinguishes itself from fillin_query by mentioning it runs a server-side LLM pass. It clearly identifies the tool's unique value proposition.

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

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

The description gives explicit when-to-use ('when your model is small / cheap / weaker at tool-result synthesis') and when-not-to-use ('Premium models usually get better results from fillin_query') guidance, and even names the alternative fillin_query. It also covers payment prerequisites and fallback flows (probe → signup, payment_challenge → retry with headers), leaving no ambiguity.

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

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

The description goes beyond annotations by detailing financial side effects: debits balance, credits seller minus rake, records transaction, and returns the reasoning_graph. It also specifies the API key and balance requirement. This adds significant context not present in the annotations alone.

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

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

The description is two sentences, both information-dense. The first sentence covers the action and effects, the second covers prerequisites. No redundant or filler content, making it appropriately sized and front-loaded.

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 purchase transaction, the description explains the financial flow, the returned payload, and required credentials. With an output schema present, it doesn't need to detail return values. The combination of annotations and description gives a complete picture for the agent.

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% with each parameter already described. The tool description does not elaborate further on parameter semantics. Per the rubric, high schema coverage yields a baseline of 3, and there is no additional value in the description regarding parameters.

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

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

The description opens with a specific verb and resource: 'Buy a listed mint.' It clearly differentiates from sibling tools like fillin_market_search (search) and fillin_mint (likely listing). It also enumerates the transaction flow, leaving no ambiguity about what the tool does.

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

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

The description clearly implies usage when a user wants to purchase a listed mint, and notes prerequisites (FILLIN_API_KEY, sufficient balance). It does not explicitly name alternative tools or exclusions, but the context is unambiguous for a buy operation, so it earns a 4 rather than 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?

The description adds meaningful context beyond the annotations: it explicitly states that no authentication is needed and enumerates the returned fields (host, total docs, earliest, latest). This is consistent with the readOnlyHint and idempotentHint annotations, and it supplements the output schema with a clear summary.

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

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

The description is exceptionally concise, using a single phrase and one short sentence. Every word contributes to understanding the tool's purpose and output, with no filler or redundant information. It is well-structured and front-loaded.

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 health-check tool with no parameters and an existing output schema, the description covers the essential aspects: what it returns and the auth requirement. It is sufficiently complete for an agent to select and invoke the tool correctly, though it could optionally explain 'liveness' and 'freshness' more explicitly.

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 zero parameters, so there are no parameter semantics to clarify. The description does not need to add parameter-related information, and the baseline for 0-parameter tools is 4. The description adds no conflicting or redundant parameter details.

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

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

The description clearly conveys that the tool provides liveness and freshness metrics, listing the specific fields (host, total docs, earliest, latest). While it lacks an explicit verb like 'check' or 'get', the purpose is unambiguous and distinct from sibling tools. The 'No auth required' note further clarifies its role.

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 mentions 'No auth required', which is a useful access condition, but it does not explicitly state when to use this tool versus alternatives. The health-check purpose is implied by the name and content, but no direct comparison or exclusion of other tools 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?

Annotations already mark readOnly/idempotent/openWorld, and the description adds meaningful context: explains what a mint is, why buying is beneficial, and what each result includes (conclusion, list_price_usdc, attestation). 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?

Two tight paragraphs: first sentence states purpose, second gives economic rationale, third describes return shape. Zero wasted words; every sentence adds value.

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

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

Given an output schema exists, the description adequately covers the return shape, the value proposition, and the next step. It does not discuss pagination or empty-result behavior, but those are minor for a search 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 high (80%), so the baseline is 3. The description adds the 'fingerprint' concept linking model_family and cutoff_quarter, but does not explain limit or cluster_id beyond what the schema already provides.

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

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

The description opens with a specific verb ('Search') and identifies the resource ('Fillin marketplace') and object ('minted data + reasoning assets'). It clearly distinguishes itself from siblings like fillin_buy_mint by mentioning paying via that tool, making the search-vs-purchase relationship explicit.

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

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

Provides clear context for when to use the tool: finding mints that are often cheaper than re-running retrieval/reasoning. It also points to a follow-up action (verify attestation then use fillin_buy_mint), but does not explicitly name alternative discovery tools (e.g., fillin_query) or state when not to use it.

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

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

The description adds behavioral detail beyond the annotations: it discloses verification steps (evidence chunk_id resolution, reasoning shape validation, HMAC signing), the return value (mint_id + attestation), and the auth requirement (FILLIN_API_KEY). Since annotations already mark readOnlyHint=false, this is a write operation, and the description enriches that with specific processing behavior. It does not cover failure modes or fee impact, but the main traits are disclosed.

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

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

The description is two short paragraphs: the first states the purpose, value proposition, and key mechanics; the second states the auth requirement. Every sentence adds information. There is no redundancy or filler, and it is front-loaded with the primary action.

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

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

The description covers the tool's purpose, outcome, verification process, marketplace context, and prerequisite. An output schema exists (mentioned in context), so return structure does not need to be described in detail. It could mention failure handling or costs, but for a 7-parameter minting tool with rich schema and output definition, it is sufficiently complete.

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

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

Schema coverage is 100%, so the input schema already documents all 7 parameters with descriptions. The tool description does not add parameter-level detail beyond what the schema provides; it mentions 'typed reasoning shape' and 'evidence chunk_id' but those are already in the schema. Baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with a specific verb+resource: 'Mint a (data + reasoning) asset on the Fillin marketplace.' It clearly states the outcome (returns mint_id + attestation) and differentiates from the sibling tool fillin_buy_mint, which is for buying. This makes the tool's purpose unambiguous.

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

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

The description provides clear context for when to use this tool: to create a sellable data+reasoning asset. It explicitly references the complementary flow via fillin_buy_mint, and notes the API key requirement. It does not explicitly state exclusions or when NOT to use it, but the context is sufficiently clear for an agent to select it appropriately.

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 indicate readOnlyHint=false and idempotentHint=false, which could imply mutation; the description clarifies this is a non-destructive challenge mint requiring no bearer. It also discloses the exact response contract and the required follow-up headers, adding real behavioral context beyond 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?

Compact and information-dense: purpose, auth requirement, response shape, next-step usage, and sibling names are all packed into a few focused sentences. Every line contributes to correct invocation.

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

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

With one well-documented parameter, an output schema, and a description that spells out the full challenge→sign→query sequence, an agent has everything needed to use this tool correctly without external context.

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

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

Schema covers the single `address` parameter 100% with pattern, length, and user-facing description. The tool description adds no additional parameter-level meaning, so the 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 action and resource: 'Mint an EIP-191 signing challenge' mapped to POST /v1/payment/challenge. It clearly differs from siblings like fillin_probe, fillin_signup, and fillin_query by describing its role as the challenge-issuing step in the flow.

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 describes the intended flow: obtain the challenge, sign `message`, then retry fillin_query with the required headers. It names fillin_probe and fillin_signup as distinct alternatives, giving the agent concrete routing context.

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

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

The description goes well beyond the annotations by disclosing that no bearer/x402 auth is needed, k is forced to 1, quota is 1 request per IP per UTC day, the success response shape, and the error object on exhausted quota. These are meaningful behavioral details not available from annotations alone.

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

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

The description is compact and front-loaded with the core purposeholiday. Every sentence contributes operational detail; there is no filler, repetition, or unnecessary background.

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

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

Given the schema covers parameters and annotations indicate read-only open-world behavior, the description supplies the remaining operational context: endpoint mapping, authentication, quota, forced k, and response shapes for both success and quota exhaustion. An agent has enough to invoke it correctly and interpret the outcome.

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 documents query and cutoff fully. The description adds no extra parameter-level meaning beyond what the schema already states, making the baseline 3 appropriate.

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

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

The description clearly states this is a free-taste probing tool for the Fillin corpus and identifies it as the MCP twin of POST /v1/probe. It conveys the action and resource, though it does not explicitly contrast itself with the more capable sibling fillin_query or fillin_answer.

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 states the quota and auth-free context, so an agent knows when it is usable, but it offers no guidance on when to prefer this tool over siblings like fillin_query or fillin_market_search. It does not explain which scenarios call for the full-featured 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 declare readOnlyHint, openWorldHint, and idempotentHint, and the description goes further by disclosing the payment requirement (x402 or Bearer), the trial/signup flow, and the semantic guarantee that documents on or before cutoff are excluded. It also explains the redundancy rationale, giving agents confidence in return relevance.

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?

Long but well-structured: core purpose in the first sentence, then payment details, then Args and Returns in a clear bullet-like format. Every section contributes – the payment block is essential for correct invocation. Slight verbosity in the trial/payment redundancy, but it's not wasteful.

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?

Covers all essential operational aspects: payment prerequisites, trial options, parameter meanings, return structure, and usage triggers. Output schema exists, but the description adds the crucial 'when' and 'how-to-handle-payment' context. Nothing an agent needs to call 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 already describes all parameters (100% coverage), but the description reinforces and adds behavioral context: cutoff exclusion rule, max length implications, and default for k. The description adds marginal value beyond schema, justifying a 4 over the 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?

The description opens with a specific verb ('Retrieve') and concrete resource ('documents published after a training cutoff, ranked by similarity'), clearly distinguishing it from siblings like glyph_search or query_frontier. The purpose is unambiguous and front-loaded.

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 use ('Call this whenever the user asks about events, releases, papers, issues, or news that might post-date your training data') and provides a detailed fallback path (fillin_probe, fillin_signup, fillin_payment_challenge) for payment handling. This is above and beyond typical 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?

Beyond the annotations, the description discloses the one-time visibility of the key, quota limits per IP per UTC day, the success response shape, and the trial_exhausted error object on exhausted quota. This gives the agent a realistic model of side effects and failure modes.

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

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

The description is dense and front-loaded, with every sentence earning its place: purpose, auth context, quota behavior, success shape, and error handling. 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?

Given the single optional parameter, presence of an output schema, and annotations, the description covers everything an agent needs: when to call it, what to expect, how to use the result, and what happens on quota exhaustion.

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 optional email parameter, and its schema description already covers semantics ('Optional contact email (max 254 chars). Not required.'). The tool description adds no additional parameter-specific meaning, so the baseline for high schema coverage 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 opens with a specific action and resource: 'Mint a one-time free 20-query trial bearer' and anchors it as the MCP twin of POST /v1/signup. This clearly distinguishes the tool from siblings like fillin_buy_mint and fillin_query.

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

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

The description gives clear conditions for use: no bearer and no x402, one key per IP per UTC day, and instructs to retry paid tools with the resulting bearer key. It does not explicitly name sibling alternatives, but the usage context 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 readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds the specific stat fields, but additional behavioral context (e.g., response format, cost, or caching) is not provided, which is acceptable given the annotation coverage.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the verb and resource, then lists the specific outputs.

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, a rich set of annotations, and an output schema present, the description is fully adequate. It explains what the tool does and what stats are returned, without needing to cover parameters or return format.

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 zero parameters, and schema description coverage is trivially 100%. The baseline for 0-parameter tools is 4, and the description does not need to add parameter semantics.

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 uses a specific verb ('Get') and resource ('corpus stats'), and enumerates the exact stats returned (total docs, date range, freshness). This clearly differentiates it from sibling tools like fillin_query or fillin_market_search.

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?

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where another tool would be more appropriate.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing the billing model (flat /query rate, rendering free), the payment requirement, the need to read images with vision capability, the caveat that glyphs are for comprehension not verbatim quotes, and the instruction to open URLs for exact text. This is rich behavioral context that annotations alone do not provide.

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

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

The description is dense but well-structured: it front-loads the core purpose, then covers output format, auth/payment, and usage caveats. Every sentence carries information, though the payment flow details are somewhat lengthy and could arguably be trimmed. Still, it earns a 4 for efficiency and organization.

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

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

The description is complete for an agent to invoke the tool correctly: it explains the output format, the payment/auth prerequisites, the error-handling flow, and the limitations of the glyph output. The output schema exists, so return values are documented elsewhere. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (query, cutoff, k, tier) with descriptions. The description adds context about the output format (photo glyph images + citation index) but does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it performs the same search as fillin_query but returns results as photo glyph images with a JSON citation index. It explicitly distinguishes itself from the sibling tool fillin_query, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (when you want vision-readable glyph pages) and contrasts it with fillin_query. It also details the payment/auth requirements and the exact fallback flow (fillin_probe, fillin_signup, fillin_payment_challenge) for handling payment_required errors, which is comprehensive usage 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?

While annotations declare readOnlyHint, openWorldHint, and idempotentHint, the description adds critical behavioral details: payment requirements (USDC/x402, Bearer key), the specific HTTP error-response flow, and the guarantee that each returned row carries an 'affected' list and numeric severity_score. It also explains that a buyer can act directly on the row without an extra hop, which is non-obvious behavior.

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

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

The description is structured with clear intent: purpose, use cases, payment, error handling, and result structure. Each section is dense but not padded. It front-loads the purpose and usage immediately, making it easy for an agent to evaluate relevance without reading the full text. No redundant 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?

Given the payment authentication complexity, error recovery steps, and rich output semantics, the description covers everything an agent needs to invoke correctly. It even addresses optional parameters (min_severity) with practical guidance. The existence of an output schema means return-format details aren't strictly required, but the description still provides enough context for acting on results.

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

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

The input schema already covers all four parameters, so the baseline is 3. The description adds value by explaining the 'affected' list structure ('ecosystem, name, vulnerable_range, patched_range') and severity_score semantics (CVSS baseScore, nullable on OSV-only rows). It also gives concrete min_severity thresholds ('Use 7.0 for high+critical only, 9.0 for critical only'). This goes beyond the schema's terse descriptions.

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

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

The description explicitly states the tool queries a 'daily snapshot of CVE / supply-chain advisories from NVD, GitHub Security Advisories, and OSV' and gives specific use cases ('before merging dependency updates, when triaging an alert, or when a user asks...'). This clearly differentiates it from sibling search tools like query_markets or query_papers.

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

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

Provides explicit when-to-use guidance with concrete scenarios and also outlines the exact flow for handling payment_required errors (fillin_probe → fillin_signup or fillin_payment_challenge). This goes beyond vague context and gives an agent a decision path.

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, openWorldHint, and idempotentHint, and the description does not contradict them. It adds valuable behavioral context: required payment or auth, the payment_required fallback flow, and the free probe endpoint, which an agent needs before invoking.

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 purpose and use-case are front-loaded, followed by compact operational/payment details. The payment flow is somewhat dense but each sentence earns its place because it documents required auth and error handling.

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 annotations covering safety, the description supplies the remaining essentials: data sources, example queries, payment requirements, and the exact retry flow on payment_required. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3 because all parameters are already documented. The description adds useful query intent and lab-list context, but does not materially expand on the cutoff or k semantics beyond the schema.

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

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

The description names a specific resource: a daily snapshot of frontier AI lab announcements plus HuggingFace trending model releases, and lists concrete sources. It also includes explicit user-query triggers, making it easy to distinguish from sibling search tools like query_papers or query_cves.

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

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

It explicitly says when to use the tool ('Use when a user asks...') and gives concrete phrasing examples. It does not enumerate exclusions versus sibling tools, but the scope is clear enough that an agent can select it appropriately.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the payment requirement, the point-in-time price snapshot, and the need to follow the URL for live prices. It also warns about payment_required errors and the trial flow. This complements the read-only and idempotent hints without contradiction.

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

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

The description is concise and well-structured, front-loading the purpose and usage context, then providing details on payment and data caveats. Each sentence adds value, though the payment flow explanation could be seen as slightly lengthy. Overall, it earns a high score for clarity and focus.

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

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

Given the tool's complexity (multi-venue, payment flow, data quirks), the description covers all necessary aspects: what it does, when to use it, payment handling, and data interpretation. It also provides guidance on alternative tools for auth. The presence of an output schema further reduces the need to explain return values.

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 description does not directly explain individual parameters beyond what the schema provides, but the schema already covers them well (100% coverage). The description adds context about the output (each row carries question, venue, etc.) but doesn't elaborate on `k`, `cutoff`, or `query` semantics. Baseline of 3 is appropriate.

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

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

The description clearly states the tool queries active prediction markets across multiple venues, with specific example queries. It distinguishes itself from siblings by naming the venues and use cases, and the title reinforces the scope. The description is not a tautology and provides concrete context for when an agent would invoke it.

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

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

It explicitly states when to use the tool ('when a user asks...') and includes alternative actions when payment is required, routing to sibling tools like fillin_probe and fillin_signup. It also mentions using the `url` for live pricing, providing clear guidance on post-call behavior. The description fully covers usage scenarios and 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 readOnlyHint, openWorldHint, and idempotentHint, and the description does not contradict them. The description adds substantial behavioral context beyond annotations, including the payment requirement, the payment_required fallback flow with specific sibling calls (fillin_probe, fillin_signup, fillin_payment_challenge), and the free probe limit, which are critical for invoking the tool correctly.

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

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

The description is well-structured: a concise definition up front, a clear usage trigger, then detailed payment instructions. Each section adds necessary information and there is no filler, though the payment block is dense and could be considered dense but necessary.

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

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

Given the tool has an output schema, return-value details are not required. The description covers what the tool does, its sources, when to use it, and the full payment/auth flow, making it complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents query, cutoff, and k, including types and constraints. The description adds little parameter-specific meaning beyond the schema; for example, 'Daily snapshot' hints at the cutoff's time-window semantics but does not elaborate on parameter formats or interactions.

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

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

The description opens with a specific verb-resource statement: 'Daily snapshot of new research relevant to AI/ML/agents' and enumerates exact sources (arXiv categories, HuggingFace daily papers, bioRxiv), making it immediately clear what the tool queries. This clearly distinguishes it from sibling tools like query_cves and query_markets, which target different domains.

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

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

The description explicitly states when to use it: 'Use when a user asks about a new technique, paper, or benchmark.' It does not explicitly mention sibling alternatives or negative usage conditions, but the trigger condition is clear and sufficient for an agent to select this tool among research-oriented tools.

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 mark the tool read-only, idempotent, and open-world. The description adds substantial behavioral detail well beyond the annotations: the substrate selection logic driven by the reader's billing model, the payment/refund behavior, the structure of the selection object, and the layout of glyph output. There is 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?

The description is long but well-organized into distinct sections: purpose, payment requirements, substrate modes, output structure, and pricing. It is front-loaded with a clear one-line purpose and each paragraph carries operational weight. The length is justified by the tool's complexity, though it could be tightened.

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

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

Given the tool's complexity and the presence of an output schema and annotations, the description covers all necessary operational aspects: authentication/payment prerequisites, error-handling flows, substrate selection behavior, output shape, and pricing/refunds. An agent has enough information to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the reader and verbatim parameters by explaining how they map to substrate choices (pixel vs. flat-tile vs. weak tool-caller, and verbatim disallowing glyph). It does not restate k/query/cutoff, but the schema already covers those clearly.

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

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

The description clearly states the tool does one retrieval with an auto-picked substrate, and identifies the corresponding HTTP endpoint. It does not explicitly name or contrast with sibling tools like fillin_query, so while the purpose is specific, sibling differentiation is only implicit via the word 'auto.'

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

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

The description provides concrete guidance for payment-required errors, telling the caller to use fillin_probe/fillin_signup or fillin_payment_challenge. It also mentions a free probe alternative. However, it does not state when to use retrieve_auto versus other retrieval siblings (e.g., fillin_query, glyph_search), so overall usage guidance is implied rather than explicit.

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