Spain Tenders

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

The description discloses important behavioral traits beyond the annotations: the default model (Workers AI Llama-3.3-70b), the free tier, the requirement to pass an Anthropic key for additional probes, and the direct billing arrangement with Anthropic ('you pay Anthropic directly'). It also outlines the return structure. This complements the readOnlyHint/openWorldHint annotations without contradicting them.

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 four sentences, each contributing distinct information: main purpose, default model and key handling, return value, and use cases. It is front-loaded with the most critical information and contains no fluff 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?

Since there is no output schema, the description correctly explains the return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers the model selection logic, key handling, cost implications, and target use cases. This is complete for a tool of moderate complexity, with no major gaps.

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 value by giving concrete examples for the 'entity' parameter (e.g., 'Pipeworx', 'OpenInvoice'), clarifying that 'models' is optional with a free default, and explaining the relationship between '_apiKey' and 'models' (only needed if 'anthropic' is in models). This goes beyond the schema's formal 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 begins with a specific verb ('Probe') and resource ('one or more LLMs'), and clearly states the output (visibility score 0-100 per model). It further scopes the tool to brands/products/topics and lists concrete use cases, distinguishing it from siblings like ask_pipeworx (which answers questions) by focusing on visibility scoring.

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 mentions when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not, however, name alternative sibling tools or provide exclusion criteria (e.g., 'for direct Q&A use ask_pipeworx instead'), so it falls short of a full 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?

Goes beyond annotations by disclosing that the tool routes to 5,529 tools, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. Annotations already indicate read-only/idempotent, but the description adds concrete behavioral context 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 relatively long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and each section earns its place. The examples and sibling differentiators are useful. Slight verbosity in the middle, but overall well-structured.

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 no output schema, the description adequately covers return format ('structured answer with citations') and behavior. It provides a comprehensive picture: when to use, what it does, how it differs from siblings, and example queries, making it complete for an agent to invoke correctly.

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

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

The input schema already fully documents the 'question' parameter with aliases, and baseline is 3. The description adds value by providing multiple realistic example queries and clarifying that the tool accepts natural-language questions, reinforcing the schema but not deeply technical 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 clearly states the tool's function: routing questions about real-world data to the appropriate source among thousands, returning structured answers with citations. It differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs, and explicitly says 'START HERE for most questions'.

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 guidance on when to use the tool ('PREFER OVER WEB SEARCH', 'START HERE'), triggers ('what is', 'look up', etc.), and examples. Also tells when NOT to use it and names alternatives: 'Step up only when needed' for ask_pipeworx_grounded and deep_research.

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 readOnly/openWorld/idempotent annotations, the description reveals the beta/experimental nature, the live candidate testing mechanism, the comparison against the stable router, and clarifies it is a full working router rather than a fallback stub. Also states 'same response shape' as ask_pipeworx, which is useful for expectations.

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

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

Three sentences with substantive detail, but slightly wordy due to parentheticals and the emphatic 'this IS a full working router' clarification. Still well-structured and front-loaded with the most important 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 and absence of an output schema, the description provides necessary context: it is a full router, identical to ask_pipeworx, experimental, and when to use it. The reference to 'same response shape' relies on knowledge of the sibling tool, which is acceptable in this 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 100% of parameters with descriptions such as 'Alias for question.' The description only adds 'same arguments' without elaborating on individual parameters, so it does not add significant semantic value 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 clearly states 'Beta version of ask_pipeworx: identical universal router (same 5,529 tools, same arguments, same response shape)' which defines its purpose as a routing/query tool with an experimental variant. It distinguishes itself from the stable ask_pipeworx by highlighting beta status and candidate routing improvements.

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 instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that it 'currently matches ask_pipeworx exactly' when no candidate is active. This provides clear when-to-use guidance relative to the sibling tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by detailing the return contract ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and enumerating explicit refusal_reason values, making the tool's behavior highly transparent. It also notes the extra LLM call cost, which is valuable operational context not present in 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 somewhat lengthy but dense and well-structured, with front-loaded purpose and clear use-case guidance. Every sentence contributes distinct value (routing, extraction constraint, return shape, refusal reasons, cost comparison), though a tighter structure could improve scannability slightly.

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

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

Despite having no output schema, the description fully explains the return format and refusal behavior, including all possible refusal_reason values. It also provides enough context about the internal routing and data-fetching behavior to allow agents to predict outcomes. Given the tool's moderate complexity, this is 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%: all six parameters are explicitly documented as aliases for the natural-language question, so the schema already carries parameter semantics. The description adds general context about how the question is used (picks the right tool and fills arguments) but does not provide additional parameter-level meaning beyond what the schema states, aligning with the baseline score.

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

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

The description states a specific verb and resource: it is a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-backed extraction and explicit refusal 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 explicitly says when to use this tool: when an answer will be quoted, cited, or acted on and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements). It also contrasts with ask_pipeworx, noting the extra LLM call cost and advising to 'prefer ask_pipeworx for casual lookups,' which provides clear usage boundaries.

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, idempotentHint, and destructiveHint=false, and the description substantially augments this with rich behavioral detail: resolver confidence matches, parent-event extraction, news fallback retries, low-confidence short-circuiting, market-closed status, illiquid wide-spread flags, and rare cancellation-rule risk. No contradiction exists.

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 every section earns its place, with uppercase headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) making it scannable. The opening sentence states the core purpose immediately, and the extensive detail is justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description fully carries the burden of explaining return values. It enumerates result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event fields, news fallback fields, and multiple blocking statuses. It also covers edge cases such as closed markets, wide spreads, and cancellation rules, making the tool safely invocable without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful supplementary semantics: accepted market input forms (slug, URL, question text), concrete slug/URL examples, and fan-out examples that clarify what thorough depth does per category. It does not redefine any parameter, but the contextual examples help an agent choose and format inputs correctly.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It goes on to define the supported inputs, classifiers, fan-out behavior, and response shapes, clearly distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage which are about edge scanning or arbitrage rather than single-bet research.

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 present: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed category examples and when blocking statuses occur, giving strong contextual clarity. However, it does not explicitly state when NOT to use this tool versus a sibling like polymarket_edges, so it stops short of a full 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses concrete behaviors: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, income, cash, debt; adverse-event and trial counts), fiscal-year handling, and output ordering. This is rich, non-redundant context.

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

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

The description is front-loaded with trigger phrases, then gives usage guidance, then provides type-specific details and output format. Every sentence earns its place, and the structure is easy to scan—long but purposeful.

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 no output schema, the description explains return values (paired data + citation URIs), sorting behavior, and data sourcing. It covers all essential aspects for an agent to invoke correctly, including the benefit of replacing many sequential calls. No significant gaps.

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 already explains the enum and array format. The description enhances this by providing concrete examples (AAPL, MSFT; ozempic, mounjaro) and explaining how the type parameter determines which metrics are retrieved, adding meaning beyond the raw 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?

Clear verb 'compare' with explicit resource ('companies or drugs') and scope (2-5 entities). Trigger phrases like 'X vs Y' and 'rank these companies' make intent unmistakable, and it distinguishes itself from single-entity lookups like entity_profile.

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

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

States 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing explicit when-to-use guidance and a direct alternative. Also clarifies the two entity types and gives example usage for each.

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 annotations by disclosing latency ('15-60s', up to ~90s for thorough), output structure (findings packet with gaps[], contradictions[], hop field, citation_uri), depth-dependent behavior (gap recovery, lead chasing), and semantic excerpting of large records. It also clarifies that gaps[] are never invented, adding critical trust context. This does not contradict the readOnly/openWorld/idempotent 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?

Although lengthy, every sentence carries critical information, from account requirements to output guarantees. The description is front-loaded with the most important constraint (ACCOUNT REQUIRED) and follows with purpose, usage, depth behavior, citations, and performance. It is dense but not bloated, and effectively structured for a complex tool.

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

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

Given that the tool has no output schema, the description fully covers return values: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also addresses limitations relative to open-web search and alternative tools, as well as performance expectations. For its complexity, the description is remarkably 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 baseline is 3. The description adds extra value by noting that depth:'thorough' requires a paid plan and explaining the practical impact of each depth level in execution latency and iterative hops, which is not present in the schema. While it repeats some schema details, the added context about account tier and runtime justifies a score above 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 with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts it with open-web search. It distinguishes from siblings by naming ask_pipeworx as the alternative for single lookups and breaking news, making the core purpose highly specific and non-confusable.

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 usage guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives account prerequisites and a fallback for unsigned users, making when-to-use and when-not-to-use 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=true and idempotentHint=true, which the description doesn't contradict. Beyond annotations, it discloses return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds useful context about output shape and efficiency. It doesn't discuss rate limits or auth, but annotations cover the safe-read aspect, so the extra context earns a 4.

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 compact four sentences. The first sentence states purpose, the second lists relevant domains (somewhat long but useful), the third explains return format, and the fourth gives a usage rule. Every part earns its place, but the domain list could be considered slightly verbose. Still, it is overall efficient 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?

The tool is a discovery meta-tool with no output schema. The description compensates well by explaining what is returned (tools, descriptions, schemas with examples), how the results are ready to call directly, and when to use it. It provides enough context for the agent to understand its role relative to the many sibling tools. This is 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%: every parameter (query, aliases, limit) has a description, with examples. The description text doesn't add parameter-specific meaning beyond what the schema already provides. Baseline for high coverage is 3, and the description's mention of aliases is already in the schema. Therefore a 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 purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes itself from sibling tools by explicitly framing it as a discovery/browse mechanism versus data-specific tools like es_tender_search or polymarket_edges. The scope is well-defined with an enumerated list of 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 provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use this tool and when to consider a more direct tool (implied by 'not just one answer'). It also explains the benefit of skipping a second lookup.

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, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it fans out across multiple sources in one parallel call, includes a soft-fail caveat for USPTO PatentsView, and documents the GDELT→GNews fallback. No contradictions.

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 front-loaded with illustrative user queries and an immediate usage directive. It then compactly lists sources and return fields with necessary caveats. Each sentence contributes meaningful information without redundancy.

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

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

With no output schema, the description effectively documents return contents: CIK, recent filings with URIs, fundamentals selection, patents status, news fallback chain, and LEI. It also covers input limitations and prerequisites, making the tool's behavior sufficiently predictable.

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?

Input schema has 100% description coverage with examples and constraints for both parameters. The description mostly repeats the same information (ticker or zero-padded CIK, names not supported), adding no major semantic value 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 opens with concrete user phrasings and immediately states the tool's function: a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chaining single-pack lookups and sibling tools like resolve_entity and deep_research.

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 to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It also gives an explicit exclusion: names are not supported, and instructs to use resolve_entity first if only a name is available.

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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by disclosing the data source (PLACSP, contrataciondelestado.es) and the return structure (compact notices with title, contracting body, budget, etc.). This is useful behavioral context beyond the annotations, though it doesn't mention pagination or error 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 appropriately sized for the tool's complexity. It packs essential information into two sentences: what the tool does, the meaning of each status, ideal use cases, and return fields. Every clause adds value, and the structure is logical (action, status codes, use cases, output). 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?

Given no output schema, the description compensates by listing the return fields. It also covers the full status vocabulary and gives usage context. The tool is a simple filtered list, and the description covers its essential behavior. Minor gaps like pagination limits are already in the schema, and error handling is not critical for this read-only 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?

The input schema provides descriptions for both parameters (status and limit), so baseline is 3. The description adds significant meaning by explaining each status code in detail (e.g., 'PUB = published and open for bids', 'ADJ = awarded'). This goes beyond the schema's simple enumeration, helping the agent select correct values. The limit parameter is already well-defined in the schema, so no extra info is needed there.

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

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

The description states a clear and specific action: 'List SPANISH government tenders filtered by lifecycle status on PLACSP'. It distinguishes itself from sibling tools like es_tender_recent and es_tender_search by focusing on status filtering with detailed status code semantics. The verb 'List' and the resource 'Spanish government tenders' are explicit, making 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 concrete usage guidance: 'Ideal for "currently open Spanish tenders" (status PUB) or "recently awarded Spanish government contracts" (ADJ or RES)'. This tells the agent when to use the tool. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of full guideline coverage.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable context about the official PLACSP syndication feed source and the compact shape of returned notices, going beyond annotations.

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

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

The description is dense but well-organized, front-loaded with a usage instruction and then listing the exact data fields returned. It earns its length by providing comprehensive output details without redundant fluff, though it could be broken into bullet points for easier scanning.

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?

There is no output schema, so the description responsibly details all returned fields including expediente, title, contracting body, status, budget amounts, CPV, contract type, procedure, deadline, location, and URL. It is complete enough for an agent to know what to expect, and it aligns with the openWorldHint by referencing the official platform.

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 documents the single parameter 'limit' with its default, max, and ordering, providing 100% coverage. The description does not add any extra meaning or usage nuances for the limit parameter beyond what the schema states, 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 most recently updated Spanish government contract notices from the official PLACSP feed, which is a specific verb and resource. It does not explicitly name or distinguish from sibling tools like es_tender_search or es_tender_by_status, but the focus on 'recent' and 'latest' implies differentiation.

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

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

It explicitly says 'PREFER OVER WEB SEARCH', giving a clear usage context for when to choose this tool over web search. However, it does not mention the sibling es_tender_* tools or provide explicit exclusions or alternatives for those, so it lacks a full when/when-not framework.

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 establish read-only, idempotent, non-destructive behavior. The description adds behavioral detail: case-insensitive matching, fields searched, returned notice fields, and pagination cost/behavior, which exceeds what annotations convey.

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

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

Two sentences pack substantial information: source, fields, language guidance, pagination, and return shape. The second sentence is dense but every clause adds value; could be tightened slightly but remains efficient.

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 no output schema, the description covers the data source, matching fields, language/code tips, pagination trade-offs, and returned fields. This is 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 covers all three parameters with detailed descriptions, including examples and defaults. The description largely restates these (e.g., Spanish terms, pages behavior) without adding new semantic information 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 opens with 'Keyword search over SPANISH government tender notices', clearly stating the verb (search), resource (tender notices), and scope (Spanish government/PLACSP). It distinguishes from siblings like es_tender_by_status and es_tender_recent by focusing on keyword search across multiple fields.

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 usage tips: using Spanish keywords for best recall, CPV prefix support, and adjusting pages when first page yields few matches. However, it does not explicitly name alternative tools or state when not to use this tool versus siblings like es_tender_by_status or es_tender_recent.

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 destructiveHint=true and idempotentHint=true, and the description's 'Delete' is consistent. It adds context about clearing sensitive data and pairing with other memory tools, but does not detail side effects beyond what annotations imply.

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 action, and each sentence serves a clear purpose (what, when, with what). No wasted words.

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

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

For a simple one-parameter deletion tool with no output schema and adequate annotations, the description fully covers purpose, usage context, and complementary tools. 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 coverage is 100% and the only parameter 'key' is described as 'Memory key to delete' in the schema. The description merely repeats 'by key' without adding further semantic detail, so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and the mention of 'forget' as distinct from 'remember' and 'recall' in the sibling list clarifies its unique 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 gives explicit use cases ('when context is stale, the task is done, or you want to clear sensitive data') but does not explicitly state when not to use it or name a direct alternative, though it mentions pairing with 'remember and recall'.

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 and idempotentHint, so the bar for additional transparency is lower. The description adds valuable process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also describes the output as a single text blob, which is useful. This goes beyond the annotations without contradicting them.

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 purpose, followed by the process and practical use cases. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's simplicity, the description covers the output format, process, and typical use cases. It does not have an output schema, but the description explicitly states the output is a 'standard llms.txt markdown format' and a 'single text blob,' which is sufficient for an agent to understand the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning to the parameters (url and max_links) beyond what the schema already provides. It mentions 'any URL' as a generic qualifier but doesn't elaborate on parameter behavior or constraints.

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

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

The description starts with a specific verb-resource pair ('Generate a production-ready llms.txt file') and clearly differentiates this tool from siblings by stating the target output format and use cases. It distinguishes itself from related tools like ai_visibility_check or scan_competitor_ai_presence by focusing on the llms.txt artifact.

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 use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), which implies appropriate contexts. However, it does not explicitly mention when not to use this tool or compare it to potential alternatives, 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 indicate a safe read operation (readOnlyHint, destructiveHint=false). The description adds behavioral details beyond annotations by listing the exact fields returned and clarifying the default scope ('active subscriptions'), which is useful context for the agent.

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, first stating purpose and return fields, second giving usage guidance. Every word earns its place; no fluff or redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the return fields, default behavior, and practical use cases. It provides sufficient context for an agent to invoke it correctly without additional information.

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

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

Schema coverage is 100% for the single optional parameter `include_inactive`, so the schema fully describes it. The description reinforces the concept of active vs. inactive by mentioning 'active subscriptions', but adds no new parameter-specific information, so a baseline score 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 action ('List'), the resource ('subscriptions'), and the scope ('the caller's active'). It distinguishes itself from siblings by specifying 'active' and 'caller's', and lists the return fields, making it 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?

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This directly references the alternative actions (adding subscriptions or cancelling), providing clear usage 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?

Annotations are all false, offering no safety or side-effect hints, so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the token flow ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'). It also reveals team reading cadence and roadmap impact, which goes beyond the schema.

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

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

The description is long but every sentence adds value: purpose, use cases, exclusions, disambiguation, token flow, rate limits, and cost. It is front-loaded with the primary purpose. The only minor redundancy is repeating the 'only Pipeworx tools' exclusion in two sentences, but this emphasis is justified to prevent misuse. Overall, it is dense and structured.

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 feedback tool with 4 parameters, nested context object, no output schema, and unhelpful annotations, the description is exceptionally complete. It covers use cases, exclusions, token-based status lookup, rate limits, quota impact, and roadmap influence. An agent can fully decide when to use it and how to invoke it correctly without additional information.

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 beyond the schema, especially for claim_token: it explains how to obtain it and how to use it as a standalone call ('pass the pwfb_… token that filing returned, with no other arguments'). It also clarifies the intended use of type and context, reinforcing but not merely repeating 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the target (Pipeworx team) and the specific actions (bug, feature, data_gap, praise). This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which are for asking questions or exploring capabilities.

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 tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also offers an explicit exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context by stating 'no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window,' which informs the agent about data provenance and freshness.

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 lead sentence, output specification, bulleted use cases, and a technical note on caching. Every sentence earns its place, and the entire description is compact yet comprehensive.

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?

Although there is no output schema, the description names the returned items (top tools, top packs, total call volume) and adds context on data provenance and caching. This is sufficient for a simple one-parameter read-only tool, though the exact response shape is not specified.

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 the single parameter with an enum and a detailed description, so the baseline is 3. The tool description only lists the windows without adding new semantic details; the schema already explains the trade-off between short and long windows.

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 question, 'What other AI agents are calling on Pipeworx right now', and then specifies the exact outputs: 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This verb+resource+scope structure clearly distinguishes it from related siblings like discover_tools and ask_pipeworx.

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 includes a 'Useful for' list with three explicit scenarios: discovering hot data sources, confirming a canonical tool choice, and seeing alignment with agent needs. This provides strong context for when to use the tool, though it does not explicitly name alternative tools 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?

Beyond the readOnlyHint/idempotentHint annotations, the description adds rich behavioral context: the >3pp threshold, Jaccard ≥0.30 similarity filter, placeholder slug dropping, the >20% placeholder null-arb rule, and the fill-check logic that prices against live CLOB depth (realizable_edge_pp ≤ 0 means don't trade). 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 logically structured with labeled sections (modes, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence earns its place, covering necessary operational details without filler. The core purpose is front-loaded, and the length is justified by 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?

With no output schema, the description fully defines the return structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It covers edge cases (null arb signal, thin_legs) and references a sibling for sizing, making it complete for a complex 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 coverage is 100%, but the description adds substantial meaning beyond the schema: 'event' takes a slug or full URL and walks child markets, 'topic' searches related events and flattens markets, and the no-arg mode is explained. It also clarifies optional parameter semantics and provides concrete examples.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges by the unique approach and response structure, and includes mode-specific purposes (trending_scan, event, topic).

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

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

Explicit when-to-use guidance is provided: 'Call with NO args for a trending_scan...', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan'. It also notes that cross-event mode catches patterns single-event misses and points to polymarket_fill_risk for custom sizing, giving clear 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 far beyond the annotations (which only indicate read-only, idempotent, non-destructive). It discloses response segmentation, field details (edge_pp_net, kelly_fraction, liquidity, spread_pp), the 24h-move warning, Fed exclusion rationale, knob effects, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostics for understanding empty segments. This is rich behavioral context that helps the agent anticipate results and debug calls.

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 dense with relevant information, and it is organized thematically (segments, knobs, response structure, diagnostics, caching). There is minor redundancy with schema parameter descriptions, but the prose adds conceptual clarity. The first sentence is a strong summary, and the overall structure makes the content navigable despite the length.

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 no output schema, the description fully specifies the response structure including top-level keys (by_segment, fed_candidates/fed_note, _diagnostics) and the per-opportunity fields. It also covers optional behavior like the Fed exclusion and diagnostics for empty segments, making it self-sufficient for an agent to understand what the tool returns and why. The parameter side is also thoroughly explained via schema plus prose.

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

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

All 9 parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds meaningful context by explaining the tradeable-edge knobs ('min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), clarifying how min_kelly relates to half-Kelly and why min_partition_leg_kelly exists for partition arbs, and describing slippage assumptions. This goes beyond merely restating parameter names.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the tool's purpose as opportunity discovery and distinguishes it from siblings like polymarket_arbitrage by emphasizing the 'what should I bet on today' use case and the segmentation of model families.

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 states when the tool is meant to be used ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and provides context about when not to rely on certain signals (Fed bets excluded due to unreliable data). However, it does not explicitly name alternative sibling tools or provide explicit 'use this instead' exclusions, so it earns a 4 rather than 5.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: snapshots are written on cache-miss, gaps mean no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes (not intraday). It also discloses edge sign conventions and response structure, far exceeding 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 dense but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds necessary information for a tool with no output schema, and it avoids fluff. The front-loaded purpose sentence immediately orients the agent.

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 no output schema and two parameters, the description fully covers invocation, return fields (tracked, expired, snapshot_dates), edge sign convention, trend classifications, and data availability caveats. It is complete enough for an agent to select, call, and interpret the results 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 value by explaining that 'window' refers to a snapshot family (24hr/1wk/1mo) and clarifying default/max values for 'days'. While it largely echoes the schema, the 'snapshot family' framing helps understand parameter semantics in the tool's context.

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

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

The description clearly states the tool's function: providing edge persistence and decay telemetry from daily snapshots, and answers a specific question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edges.

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 context for when to use it—when assessing whether an edge is fresh or decaying—and explains that a 3-week-old wide edge is fundamentally different from a fresh one. It does not explicitly name alternatives or say 'don't use this for current snapshot', but the use case is clearly framed.

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 give readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds substantial behavioral detail: it walks the ladder, computes top-of-book vs VWAP, identifies thin legs, returns a verdict, and explicitly calls out the risk of partial fills converting arb into unhedged directional positions. It does not contradict any annotation.

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 and dense, but every sentence carries technical substance relevant to a high-stakes financial tool. It is front-loaded with the core purpose and then expands into modes and usage guidance. Some structuring (e.g., bullets) could improve scannability, but the length is justified given the complexity; it earns a 4 rather than a 5 for being slightly unwieldy.

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?

This is a complex dual-mode tool with 4 parameters, no output schema, and no nested objects, so the description must account for return values and edge cases. It lists all relevant outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs[], etc.) and explains the semantic meaning of each mode. Given no output schema exists, this level of detail is necessary and sufficient.

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?

Although schema description coverage is 100% and the schema already describes each parameter, the description significantly enriches semantics: it clarifies that either `market` or `event` is required (schema leaves all optional), defines mode-dependent roles for `side` and `size_usd` (e.g., 'max spend on buys, target proceeds on sells' vs 'settlement notional S'), and describes the behavior of defaults and clamps. This goes well 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', which specifies the verb (check) and resource (live CLOB order-book depth) precisely. It then distinguishes two modes (single-market and basket), listing distinct inputs and outputs, and names the exact sibling tools it pairs with (polymarket_arbitrage, polymarket_edges), setting it apart from them.

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

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

Explicit guidance is present: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to rely on theoretical overround for thin books and warns about partial basket fills, effectively providing clear when-to-use vs when-not-to-use 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 far beyond the annotations (readOnly, openWorld, idempotent) by disclosing detailed behavioral semantics: compatibility_warning firing conditions, temporal_alignment implications, skipped_cross_type/subtype counters, and what matched_pairs:0 means. This is rich, non-obvious behavioral context.

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

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

The description is long but every sentence earns its place. It is well-structured with clear sections (MODE, RESPONSE, SAFETY FIELDS) and uses formatting to highlight key distinctions. No filler or redundancy.

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

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

For a complex cross-venue comparison tool with no output schema, the description is remarkably complete. It explains return fields (leg-by-leg prices, spread, compatibility warnings), edge cases (non-equivalent bet shapes, temporal misalignment), and the limitations of pre-mapped topics, giving an agent everything needed to use it correctly.

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

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

Input schema already provides 100% coverage with descriptions for all three parameters. The description adds value by listing the exact macro shortcuts, giving example values for ticker/slug, and explaining the override relationship between topic and explicit 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 leads with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from siblings like polymarket_arbitrage by emphasizing cross-venue comparison and same-question pairing.

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 two modes (topic shortcuts vs explicit ticker/slug) and when to use each. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped ≠ tradeable, providing exclusion guidance and setting accurate expectations.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: listing all keys when omitted, scoping to a user identifier, and the relationship to remember/forget. It does not describe the return format or behavior on missing keys, but given the simplicity and annotation coverage, this is sufficient.

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 remarkably concise: two sentences front-load the core behavior, then add usage examples and scoping. Every sentence contributes meaningful information, 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?

For a simple tool with one optional parameter and no output schema, the description is nearly complete. It explains the retrieval and listing modes, provides usage context, and notes scoping. The only minor gap is the lack of explicit return value details, but the description's 'Retrieve a value' and the schema's listing hint make the expected output clear enough.

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% (key is described as 'Memory key to retrieve (omit to list all keys)'). The description enriches semantics with concrete examples of stored values (target ticker, address, research notes) and clarifies the omission behavior, going slightly beyond the bare schema description.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It also distinguishes from sibling tools by explicitly pairing with 'remember to save, forget to delete.' This provides a specific verb+resource and differentiates from nearby memory tools.

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 usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives (remember, forget) and mentions scoping to an identifier. This fully covers when and how to use the tool relative to its siblings.

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?

Annotation Contradiction: readOnlyHint=true declares a read-only operation, but the description explicitly states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' which is a persistent state change. This is a direct contradiction with the readOnlyHint annotation. No other behavioral detail can compensate for this inconsistency.

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 dense, information-packed paragraph that front-loads the core purpose. Each sentence adds value: return content, filter options, mark_read semantics, and the alternative endpoint. It is slightly long but every clause is purposeful, making it appropriate for 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?

With no output schema, the description explains the return shape (source, citation_uri, raw event payload) and covers the side-effect of mark_read. It explains filtering, the external mirror, and pollability. It could add an example output or mention default limit more explicitly, but it is adequately complete for a read-focused tool with well-described schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds enrichments beyond the schema: it provides a concrete example for type ('sec_8k'), clarifies that since takes an ISO timestamp, and explains the semantic effect of mark_read (affects subsequent calls). These details give the agent a better mental model than the raw schema alone.

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

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

The description clearly identifies the tool's function: 'Pull fired events from your subscription feed.' It names the specific resource (subscription feed), the verb (pull/return), and the delivered content (source, citation_uri, raw payload). This distinguishes it from siblings like list_subscriptions (which lists subscriptions) and subscribe/unsubscribe (which manage them).

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

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

The description implies its usage via filtering and polling guidance: 'Polls work fine' and the alternative HTTP endpoint for scripts/dashboards. It does not explicitly name sibling tools as alternatives, but the boundary is reasonably clear—this is for reading alerts, not managing subscriptions. Light exclusion guidance is present via the external URL.

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 significant behavioral traits beyond the annotations: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), describes fallback logic, and notes USPTO soft-fails until PatentsView API is reactivated. This transparency about external dependencies and failure modes adds substantial value beyond the readOnly/idempotent hints.

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 highly relevant, front-loading user-facing query examples before the technical details. Every sentence earns its place, covering purpose, sources, fallback, parameter details, return shape, and alternative guidance without redundancy or fluff.

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

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

Despite the absence of an output schema, the description explicitly states the return structure (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers limitations, external dependencies, and the identity parameter restriction. This is comprehensive for a multi-source feed 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?

The input schema already provides 100% coverage with descriptions for all three parameters, including the since format and examples. The description repeats the since format but does not introduce new semantic meaning for the parameters beyond what the schema already states. 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's purpose: a change feed for a company over a time window. It uses specific verbs like 'change feed' and provides multiple natural-language query examples ('What's new with X', 'updates on Acme'). It also distinguishes from the sibling tool entity_profile, explicitly stating which tool to use for static profiles.

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 versus alternatives: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also lists example queries and explains the fallback behavior (GDELT preferred, GNews on rate-limit/5xx), making the usage context clear.

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

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

Goes beyond annotations by disclosing scoping ('scoped by your identifier') and retention differences (authenticated users persistent, anonymous sessions 24 hours). Annotations only indicate idempotent and non-destructive write; the description adds meaningful behavioral context without contradicting them.

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

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

Four sentences, all information-dense and front-loaded with the core action. Every sentence adds value: purpose, usage trigger, storage format, retention policy, and companion tools. No fluff or redundancy.

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

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

For a simple key-value store, the description covers purpose, usage, retention, and lifecycle (recall/forget). A minor gap is the lack of explicit mention of overwrite behavior for existing keys, but idempotent annotation implies it. Overall 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 coverage is 100% with clear descriptions for both 'key' and 'value'. The description reinforces the key-value pair concept but does not add new parameter semantics beyond what the schema already provides. 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's function: 'Save data the agent will need to reuse later.' It uses a specific verb ('Save') and resource (key-value memory data), and distinguishes itself from sibling tools by explicitly pairing with 'recall' (retrieve) and 'forget' (delete).

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: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions companion tools for retrieval and deletion, implicitly indicating when not to use this tool (i.e., not for retrieving or deleting).

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 (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: each call cascades through multiple endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable (EDGAR still returns), identifiers are source-labelled, and unresolved identifiers are explicitly stated. This substantial additional context significantly aids the agent in anticipating outcomes.

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: it starts with example queries to signal intent, then explains the core function, followed by per-type details. Most sentences add valuable context (degradation, source labeling, replacement of manual lookups), though it could be trimmed slightly for tighter delivery. It is appropriately front-loaded with the main purpose.

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 (multiple entity types, multiple internal lookups, no output schema), the description is remarkably complete. It covers return values (source-labelled identifiers, 'unresolved' field), failure modes (graceful degradation), and per-type behavior (company vs. drug). An agent can fully anticipate the tool's behavior without needing an output schema.

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

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

The input schema already describes both parameters, but the description adds deep meaning: it explains what a 'company' resolution entails (cross-source identity spine with CIK, ticker, LEI, FIGI), what a 'drug' resolution returns (RxCUI, ingredient, brand, and citation), and acceptable input formats for 'value'. This goes far beyond the simple enum and string descriptions in 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 clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It uses a specific verb ('resolve') and resource ('entity names to identifiers'), and distinguishes itself from siblings by emphasizing its role as the first step when an ID is needed, unlike entity_profile or compare_entities.

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 says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It doesn't explicitly mention alternatives or when not to use, but the context and sibling list imply this tool is the entry point for identifier lookups, so the usage context is clear enough.

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, idempotentHint, and openWorldHint, covering safety. The description adds behavioral context beyond these: it reveals the tool internally calls ai_visibility_check for each entity, ranks results by score, and treats the first entity as the 'subject'. This explains aggregation behavior and the ordering of inputs, which is valuable for an agent. It stops short of a 5 by not addressing potential rate limits or result volume, but that is acceptable given 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 and every word earns its place. It starts with a clear high-level purpose, then explains mechanism, gives an example use case, and lists output fields. No filler or irrelevant details. This is exemplary 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?

Despite lacking an output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity'), which fully compensates. It also provides a use case, default model behavior, and input semantics. Combined with strong annotations and fully described parameters, this is a complete description for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the 'entities' array semantics: the first entry is treated as the 'subject' and the rest are competitors, affecting the narrative output. This is not in the schema and directly helps an agent construct correct input. Hence, it earns a 4.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from the sibling ai_visibility_check by explicitly stating it probes each entity with that tool and aggregates results. It also states the output (ranked list, score, confidence, signal density), 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 provides a clear use case ('competitive AI-marketing audits') and a concrete example question. It implies when to use this tool versus the single-entity sibling (ai_visibility_check) by contrasting 'multiple entities side-by-side' with probing each entity individually. However, it does not explicitly name alternatives or state when not to use it, so it falls just 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses graceful degradation for partial failures, the 5-30s delay on first bundlephobia measurement, and the sources_failed field. These are valuable operational details not captured by schema or annotations.

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

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

The description is dense but efficiently worded, front-loading the core composite check and then enumerating return fields. Slightly long but each sentence contributes context, with no filler.

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

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

Despite no output schema, the description enumerates the summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases (scoped packages, partial failures). This provides a complete mental model 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?

The schema description already fully covers both parameters. The description adds meaningful clarification: package accepts scoped names, version defaults to latest when omitted, and the return includes alternative versions—helping interpret the version param's purpose 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 clearly states the tool's function: a composite npm package evaluation check across deps.dev and bundlephobia. It uses a specific verb ('scan'), identifies the resource (npm package), and differentiates from sibling research tools by focusing on dependency vetting.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion boundary: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent to an alternative 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?

Beyond the annotations (which indicate read-only, idempotent, non-destructive), the description discloses important behavioral traits: it returns character offsets and similarity scores, truncates inputs over 200K chars and flags them, and uses specific embedding/window mechanics (BGE-base-en, 500-char overlapping windows). This adds substantial context not available in the annotations or schema.

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

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

The description is structured with a purpose statement, usage guidance, sibling pairing, and technical details—each sentence adds value without fluff. It is detailed but not verbose, front-loading the core function and then providing necessary specifics.

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 moderate complexity (truncation, output format, technical behavior) and the absence of an output schema, the description is thorough. It explains the return format (passages with offsets and similarity scores), the truncation cap, and the embedding approach, making the tool's behavior predictable for an 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%, so the baseline is 3. The tool description adds marginal nuance (e.g., 'text you already pulled' clarifies the text is raw content, and query examples are provided), but most parameter meaning is already well documented in the schema. It does not significantly compensate 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 begins with 'Semantic search INSIDE a fetched record,' which clearly indicates the tool's verb, resource, and unique scope. It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on returning passages from a provided text, rather than answering or grounding over the whole document. Examples further clarify its specific niche.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also directly mentions an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' which guides the agent on how to combine tools effectively.

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?

Description discloses auth requirements, phone verification, SMS daily cap, always-on feed, and return of subscription id, adding valuable context beyond the annotations. No contradictions 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?

Front-loaded with the core purpose, the description is dense but compact given the tool's complexity. It repeats some schema content and is slightly monospaced, but every part adds useful 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?

Covers purpose, return value, prerequisites, delivery options, and constraints. It omits the webhook channel in prose, but the schema fully documents it. With no output schema, the stated return value suffices.

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?

Description adds semantic meaning to the type enum with examples and clarifications such as 'sec_8k = 8-K filings matching ticker + item codes'. Schema coverage is high, so baseline is 3, but this extra context raises the score.

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

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

Description clearly states the tool creates a proactive subscription to a live-data event stream, listing specific subscription types and return value. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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 context on when to use each subscription type and notes the OAuth account prerequisite. It mentions pulling via recent_alerts as an alternative feed mechanism but does not explicitly contrast with alternative tools or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context by noting results are 'drawn from the live catalog of thousands of tools' (consistent with openWorldHint) and describes the return structure (category-bucketed questions with tool + argument shape). It does not contradict annotations and provides useful behavioral context beyond the structured data.

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 front-loaded with example queries, then a concise explanation of purpose and output. Despite being long, every sentence contributes: the query examples, the category list, the tool/argument detail, and the usage guidance. It is well-organized and not redundant with the schema or annotations.

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 onboarding tool with no output schema, the description covers what it returns (category-bucketed example questions with tool/argument shapes), the optional topic parameter, and when to use it. It is complete for an agent to understand the tool's purpose, usage, and output without additional documentation.

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

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

Schema coverage is 100% for the single parameter, providing baseline 3. The description adds value by elaborating that omitting topic gives a 'cross-category spread' and listing example focus areas (finance, pharma, betting, etc.), which helps understand the parameter's effect on the output. This goes beyond the schema's terse description.

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 it is the onboarding entry point for an agent wanting to know what Pipeworx can do, listing example queries like 'What can I ask Pipeworx?' and describing the return of category-bucketed example questions. It distinguishes from siblings by explicitly saying to use this FIRST before other tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' It also explains how to use the optional topic parameter to focus, and that omitting it gives a full spread, covering both when and how 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 discloses that the row is deactivated rather than deleted, preserving historical events for recent_alerts. This goes beyond the annotations, which only indicate non-destructiveness. It also mentions ownership enforcement, providing behavioral detail not in 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?

Two sentences, no filler. The action is stated first, followed by key behavioral notes.

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 one-parameter cancellation tool with annotations and full schema coverage, the description adequately covers ownership, soft-delete behavior, and downstream availability in recent_alerts. No output schema exists, so return details aren't expected.

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 description already fully documents the id parameter (uuid returned by subscribe), so the description adds no new parameter semantics. Baseline 3 applies due to 100% 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 uses the specific verb 'Cancel' with a resource 'subscription by id,' clearly distinguishing it from sibling tools like subscribe and list_subscriptions. It also states the ownership enforcement, further clarifying its scope.

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 implies the tool is for cancelling an existing subscription, with ownership as a constraint. It doesn't explicitly name alternatives or exclusions, but it provides clear context that you can only cancel your own subscriptions. No sibling distinction or when-not-to-use is given, so not 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?

Even with readOnlyHint and openWorldHint annotations, the description adds significant behavior: it details the internal routing logic, the exact verdict values returned, and the critical distinction between could_not_verify (failure, with verification_error) and unsupported (no source exists). This goes far beyond annotation hints, ensuring callers understand edge cases.

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 every sentence earns its place: query phrasing, usage trigger, routing explanation, return contract, caller warnings, and performance note. It is well-structured and front-loaded with examples, though it could be trimmed slightly 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?

With no output schema, the description fully compensates by enumerating possible verdicts, mentioning the actual value and citation, and explaining error semantics. It also conveys the tool's efficiency (replaces 4–6 calls). No significant gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description adds valuable semantics for tolerance_pct: tells the caller it overrides claim wording, suggests 1–2 for hallucination detection, and reveals default behavior (implied by wording, capped at 5). Claim also gets helpful examples in the schema, though the description reinforces them. This extra semantic context justifies a 4.

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

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

The description opens with many natural-language variations of the use case ('Is it true that…', 'fact check', etc.), then explicitly states 'natural-language claim verification against authoritative sources.' It clearly identifies the tool's specific job (fact-checking with verdicts) and distinguishes it from simpler search or comparison tools by noting it replaces multiple sequential calls.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two-path routing (structured SEC EDGAR/XBRL for company financial claims vs. grounded pipeline for any other factual claim), and includes concrete advice on tolerance_pct for hallucination detection, which helps the agent configure the tool correctly.

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