Fillin

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

Despite annotations already declaring readOnly, idempotent, and openWorld hints, the description adds significant behavioral context: flat billing regardless of substrate, safe default for unknown readers, verbatim handling to preserve exact text, and the auditability of the selection manifest. It also explains the token-math rationale behind substrate choices, going well 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?

The description is overly verbose and includes promotional language like 'Not a search-result rendering trick: this is Glyph as a language anyone can speak.' Multiple paragraphs could be condensed without losing meaning. The essential content is buried in fluff, reducing clarity and violating the principle that every sentence should earn 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?

The description covers critical operational details: the selection object's fields, billing equivalence, reader-dependent behavior, and verbatim mode. With an output schema present and rich annotations, the description is sufficiently complete to guide usage, though a more explicit statement of return structure would slightly improve it.

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

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

The schema already provides complete descriptions for all three parameters (text, reader, verbatim), including maxLength, default values, and behavioral notes. The description adds some explanatory color (e.g., what reader types imply for billing) but does not materially exceed the schema's coverage, 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 description clearly states that the tool encodes user-provided text into either a glyph image or plain text, selecting the substrate that is cheaper for the reader model. It uses a specific verb ('encode') and resource ('your text'), and differentiates itself from the sibling tool 'retrieve_auto' by clarifying it is not a search-result rendering trick but a standalone encoding endpoint.

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 indicates appropriate use cases such as feeding tool results, RAG chunks, or documents, and explains the `verbatim` flag for code/hashes. It explicitly contrasts with retrieve_auto's answer substrate, providing some alternative guidance, though it stops short of exhaustive when-to-use/when-not-to-use scenarios.

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 read-only, open-world, and idempotent hints, so the bar is lower. The description adds useful behavior: the synthesis pass, higher cost than fillin_query, output quality fields (corpus_match, top_score), and the case where answer is None with a reason. 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 well-structured with a bolded Returns block and clear use-case paragraphs. Every section contributes meaning, though the explicit return-field enumeration partially duplicates an existing output schema, making it slightly longer than 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 rich schema, output schema, and annotations, the description covers purpose, usage guidance, cost behavior, and salient return semantics. It is fully sufficient 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 description coverage is 100%, with each of the three parameters fully documented (types, defaults, constraints). The description reinforces that the query is a natural-language question and k grounds the answer, but it adds no new per-parameter semantics beyond the schema, 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 description clearly defines the tool as a server-side synthesis pass that returns a cited answer, and it explicitly differentiates from fillin_query by naming the alternative and contrasting the synthesis approach. The phrase 'Synthesized post-cutoff answer with inline citations' gives a specific verb+resource framing.

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 explicit when-to-use conditions (small/cheap/weaker models like Llama, Gemini Flash, Mistral, Nemotron, Qwen), gives a clear exclusion ('Premium models ... usually get better results from fillin_query'), and provides a cost trade-off. This is model guidance 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?

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?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: documents on/before cutoff are excluded, results are ranked by similarity, and the return structure includes echoed fields and gap_days. It fully discloses the tool's side-effect-free, retrieval-only nature and the exact output envelope.

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 efficiently structured: a one-sentence purpose, a use-case trigger sentence, then clearly labeled Args and Returns sections. Every line adds value, there is no fluff, and the format makes it easy for an agent to parse the key information quickly.

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

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

For a three-parameter, read-only retrieval tool, this description is complete. It covers purpose, trigger conditions, parameter semantics, and the exact return shape (including nested fields) even before the output schema is considered. The context signals (read-only, idempotent, open-world) are consistent with the described behavior.

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 schema covers 100% of parameters with descriptions, so the baseline is 3. The description largely paraphrases schema information (e.g., max length, default k, cutoff exclusion), but it does add a helpful example for query and contextualizes cutoff as 'the agent's training cutoff.' This is marginal added meaning, not enough to push beyond the coverage baseline.

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

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

The description opens with a clear, specific statement: 'Retrieve documents published after a training cutoff, ranked by similarity.' It names the verb (retrieve), the resource (post-cutoff documents), and the unique ranking behavior. It further differentiates from typical search by emphasizing the post-cutoff constraint, even though sibling tools are not named explicitly.

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

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

The description gives explicit when-to-use guidance: 'Call this whenever the user asks about events, releases, papers, issues, or news that might post-date your training data.' It also explains the benefit over the model's internal knowledge. However, it does not explicitly mention when not to use the tool or name alternative sibling tools, 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 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?

Beyond the readOnlyHint, the description discloses the output structure (images + citation index), the billing model (flat /query rate, free rendering), and a behavioral caveat (vision models paraphrase), which is useful context. It does not contradict 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 three sentences, front-loaded with the core function ('Same as fillin_query, but...') and efficiently packs output format, usage tips, and billing into a compact text.

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 read-only behavior, the description adds enough operative details—how to read the images, use the citation index, and handle paraphrasing—to make the tool fully actionable.

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 provides complete descriptions for all four parameters (100% coverage), including query, cutoff, k, and tier. The description adds no parameter-level detail, so the score is at 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 clearly states that this tool performs the same search as fillin_query but returns results as photo glyph images plus a JSON citation index, distinguishing it from its sibling. It specifies the output artifacts and their purpose.

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 frames this as an alternative to fillin_query with visual output, and gives a when-not-to-use directive: glyphs are for comprehension and fact-extraction, not verbatim quotes, suggesting opening the URL for exact text. This provides clear guidance on selecting this tool over the sibling.

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. The description adds valuable behavioral context: it is a daily snapshot (freshness), rows carry structured affected list and nullable severity_score, and results are directly actionable without an external hop. This goes beyond minimal 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 efficiently structured: the first paragraph front-loads the core purpose and use cases, the second adds concise output semantics. Every sentence contributes, with no redundant wording.

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 is complete enough: it specifies data sources, intended use cases, and the actionable nature of results. It gives an agent sufficient context 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?

The input schema covers all four parameters with detailed descriptions (k, query, cutoff, min_severity). The description adds no parameter-specific information beyond what the schema provides, 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?

The description clearly states the tool returns CVE and supply-chain advisories from NVD, GitHub Security Advisories, and OSV, which is a specific verb+resource. It distinguishes itself from sibling query tools (query_markets, query_papers) by explicitly focusing on vulnerability/supply-chain domain.

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 strong when-to-use context ('before merging dependency updates, when triaging an alert, or when a user asks...'). It does not explicitly name alternative tools or state when not to use it, so it lacks the full explicit contrast expected for 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful context: it reveals the tool returns a 'daily snapshot' (indicating data recency bounds) and lists the exact sources, which goes 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?

The description is three sentences that each carry weight: purpose, sources, and usage. It is front-loaded with the main purpose, avoids fluff, and is appropriately sized.

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 presence of an output schema and strong annotations, the description covers purpose, sources, and usage. It could arguably mention how the daily snapshot affects result freshness, but that is implied by 'daily snapshot' and the openWorldHint annotation. Overall, it is sufficiently complete for the tool's complexity.

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 parameters including query and cutoff semantics. The description indirectly clarifies the query format with examples like 'what model dropped' but does not add new param details beyond that baseline.

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

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

The description clearly states the tool's function: 'Daily snapshot of frontier AI lab announcements + HuggingFace trending model releases.' It names the specific resources (frontier AI lab blogs, HF trending models) and the use case distinguishes it from sibling 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?

Explicit usage guidance is provided: 'Use when a user asks "what model dropped" or "did <lab> announce X".' This is a clear trigger, but it does not mention when not to use the tool or name any alternatives directly.

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 discloses critical behavioral traits beyond the annotations: prices are point-in-time at first ingestion, and users must follow the URL for live pre-trade pricing. It also specifies what each result row contains (question, venue, close date, volume, price snapshot). This adds significant context about data freshness and limitations, well above the annotation baseline.

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 well-structured, with four sentences each adding value: scope, usage triggers, result shape, and price caveat. No filler or redundancy. It front-loads the core purpose and keeps supporting details brief, earning a top score for conciseness.

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 read-only search tool with annotations (readOnlyHint, openWorldHint, idempotentHint) and an output schema, the description covers essential operational details: what results contain, the point-in-time nature of prices, and how to get live prices. It lacks nothing critical for correct invocation or interpretation, making it contextually 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%, with each parameter already documented in the schema (query, cutoff, k). The tool description does not add additional parameter-level meaning beyond what the schema provides. It mentions related concepts (prices, URLs) but does not elaborate on parameter usage. Baseline 3 is appropriate since schema carries the parameter burden.

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 identifies the tool's purpose: searching active prediction markets across four named venues (Polymarket, Kalshi, Manifold, Metaculus). It also provides concrete usage examples ('is there a market on X', 'what odds is the market giving Y') that distinguish it from generic search tools. The resource and scope are explicit and differentiate it from siblings like 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?

The description provides explicit when-to-use guidance: 'Use when a user asks...' and 'before any agent action that should be informed by a market price.' It does not mention when-not-to-use or name alternative tools, but the context is clear and actionable. This matches the 'clear context, no exclusions' level.

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 as read-only, open-world, and idempotent. The description adds meaningful behavioral context by explaining the data sources, the 'daily snapshot' nature, and the 'upvote signal' detail from HuggingFace. There is no contradiction with 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 description is two sentences, front-loading the core purpose and sources, then giving a direct usage hint. Every sentence adds value with no redundancy or 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 a rich output schema and detailed parameter descriptions, the tool description covers purpose, usage, and data sources. It could explicitly mention how cutoff interacts with 'daily snapshot' or the k parameter, but the schema already handles those details. Overall, sufficiently complete for an agent to select and invoke it.

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

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

The input schema has 100% description coverage for all three parameters, including type, default, and constraints. The description does not add extra meaning beyond the schema, but the schema already fully documents query, cutoff, and k. 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 returns a 'Daily snapshot of new research relevant to AI/ML/agents' with specific sources (arXiv categories, HuggingFace, bioRxiv). It distinguishes itself from sibling tools like query_cves or query_markets by focusing on research papers and explicitly naming the source 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 gives an explicit usage cue: 'Use when a user asks about a new technique, paper, or benchmark.' It does not mention exclusions or name alternative tools explicitly, but the context is clear enough for an agent to select it for research-related queries.

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 provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds substantial behavioral context beyond this: the trailing selection object for auditability, the flat/answer billing rates with the refund delta, unknown readers being treated as pixel-billed safe defaults, glyph paraphrasing, and images preceding the JSON block when glyph is picked. 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 longer than average but front-loaded with the core purpose and every paragraph earns its place: substrate definitions, output structure, and pricing behavior are all relevant. The bullet list and tight phrasing keep it scannable, though the pricing paragraph could arguably be trimmed without losing critical 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?

Given the tool's complexity (5 params, 3 substrate modes, billing nuances, output schema present), the description is complete. It covers the selection algorithm, output format quirks (images preceding JSON, trailing selection object), pricing/refund behavior, and edge-case defaults for unknown readers, so the agent can reliably invoke and parse results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by mapping reader billing models to substrate choices and explaining the rationale (cheapest AND legible for token billing), plus the verbatim-glyph paraphrase interaction. This enriches understanding of reader and verbatim beyond their individual schema 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 opens with a specific verb+resource: 'One retrieval, auto-picked substrate — the MCP twin of HTTP POST /v1/retrieve with substrate="auto".' This clearly states what the tool does and differentiates it from siblings like glyph_search and fillin_query via the auto-picked substrate (text | glyph | answer) behavior.

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 context for when each substrate is chosen (pixel billers get text, flat-tile billers get glyph, weak tool-callers get answer) and notes prerequisites like needing a server LLM key for answer. The verbatim param further clarifies when glyph should be avoided. It lacks explicit exclusions naming sibling alternatives, but the substrate-selection logic provides strong usage guidance.

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