Biosamples

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds cost implications (free default, BYO key for Anthropic) and return structure (per-model fields + combined view). 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 concise (3 sentences) with front-loaded purpose. Every sentence provides essential information: what it does, default model, optional API key, return format, and use cases. No redundant or missing content.

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 explains return values sufficiently (per-model {score, confidence, signals, raw_response} + combined view). It covers all aspects for a probing tool with 4 parameters and full schema descriptions.

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 parameters are documented. The description adds value by naming the default model ('Workers AI Llama-3.3-70b'), clarifying payment for Anthropic, and explaining the optional context parameter's purpose.

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: probing LLMs for brand visibility and scoring it 0-100. It uses specific verbs ('probe', 'score') and resource ('LLMs'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring across multiple models.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the default model vs Anthropic with a BYO key. It lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already provide safety profile (read-only, idempotent). Description adds behavioral context: routes to 5,245 tools, fills arguments, returns structured answer with citation URIs. No 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?

Description is fairly long but front-loaded with key guidance. Every section adds value (examples, alternatives). Could tighten some repetition but effective overall.

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

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

No output schema, but description explains return format (structured answer with citations). Covers all necessary context: purpose, usage, alternatives, examples, and behavior. Complete for a general query 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 has 100% coverage with clear descriptions of all six parameters (mostly aliases for question). Description doesn't add new semantics beyond stating 'natural language' use, which is already in 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?

Description clearly states the tool answers factual questions using structured data with citations, and distinguishes it from sibling tools like ask_pipeworx_grounded and deep_research with specific use cases.

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 'PREFER OVER WEB SEARCH', provides when-to-use (factual questions), examples, and when to step up to alternatives. Covers exclusions and 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?

Description adds behavioral context beyond annotations: mentions live candidate switching, current identical behavior, and that it 'falls back to nothing' (a full working router). No contradiction with readOnlyHint etc.

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?

Description is slightly verbose but each sentence is informative: identity, purpose, current state, usage, fallback. Front-loads key information about being a beta version.

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 complexity (router with 5k+ tools, experimental), the description comprehensively covers purpose, similarity, current operational state, and usage guidance. Schema and annotations already handle parameter and behavioral info.

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 description adds value by stating 'same arguments as ask_pipeworx', reinforcing that parameters are identical. However, does not add new meaning per parameter beyond 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router with candidate routing improvements, distinguishing it from sibling tools by noting it is the experimental edge.

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: 'when you want the newest routing'; implies stability use ask_pipeworx. Also explains current state (no active candidate) and that it matches ask_pipeworx exactly, 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 already provide readOnlyHint, idempotentHint, destructiveHint. Description adds crucial behavioral details: hallucination-resistant, extracts answer ONLY from tool result, returns specific response shape with evidence and refusal reasons, and costs one extra LLM call. 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 front-loaded with key info and is dense but every sentence adds value. It is slightly long but well-structured, explaining mechanism, use case, and trade-offs. Could be slightly more concise but still effective.

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 complexity of routing among 5,245 tools and performing extraction, the description covers behavior, use case, trade-offs (extra LLM call), and detailed return shape (including refusal reasons). No output schema exists, so description fully compensates by explaining return values comprehensively.

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

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

Schema description coverage is 100%, with all parameters having descriptions. The description adds context that the tool picks the right tool and fills arguments, but does not elaborate on parameter meaning beyond what schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains it picks the right tool, fetches data, and extracts the answer using only the tool result. It distinguishes itself from sibling ask_pipeworx by noting it costs an extra LLM call and is for answers that will be quoted or cited.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists examples like financial verdicts, legal claims. Also says 'prefer ask_pipeworx for casual lookups,' providing an alternative and a clear 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?

The description adds extensive behavioral details beyond annotations: resolver confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, wide-spread handling, and resolution-rule risk. All align with annotations (readOnlyHint, idempotentHint, openWorldHint) 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 well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), but it is excessively long. While the detail is valuable given complexity, conciseness is compromised. The information could be more tightly written without losing meaning.

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

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

Given the tool's complexity, no output schema, and three parameters, the description is remarkably complete. It covers all relevant aspects: parameter usage, response structure, edge cases (low-confidence, closed markets, wide spreads), safety mechanisms, and resolution rules. An agent has sufficient information to use the tool correctly in diverse scenarios.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds value by explaining the effect of 'depth' (quick vs thorough) and providing practical guidance for 'include_raw' (when to use true). This surpasses the baseline of 3 for high 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific resource (Polymarket bet) and action (research), and distinguishes itself from sibling tools by focusing on comprehensive bet research with multiple classifiers and data sources.

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

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

Usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. However, it does not explicitly state when not to use it or mention alternative sibling tools, which would strengthen this dimension.

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. The description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), fiscal year handling, sorting by primary metric, and output including citation URIs.

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 common trigger phrases and well-organized. It is slightly verbose but each sentence adds unique value, covering purpose, usage, data details, and output format.

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 adequately describes return values (paired data + citation URIs). It covers inputs, data sources, sorting, and the efficiency advantage, making the tool fully understandable.

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%. Description adds meaning by explaining what data each type pulls (e.g., revenue, net income for companies), reinforces value format (tickers/CIKs vs drug names), and mentions the 2–5 constraint.

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 specifies the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It lists example queries and distinguishes from siblings like entity_profile which handles single 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Details input constraints such as 2–5 entities and format for tickers or drug names.

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 provides extensive behavioral context beyond annotations: expected latency (15-90s), return format (findings with evidence, confidence, gaps, contradictions), no invention, semantic excerpts, and hop fields. No contradiction with annotations.

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

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

The description is long but well-organized with clear sections and no wasted words. Slightly verbose due to depth of detail, but appropriately so given tool 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?

No output schema exists, but the description fully details the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop field) and explains behavior differences across depth levels. Covers limitations (structured data only, not breaking news).

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 description adds detailed semantics for the depth parameter (exact facet counts and behaviors for quick/standard/thorough) and the question parameter (natural language, broad/multi-part fine). Adds meaning 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 does grounded multi-source research across 1369 structured data sources, and distinguishes it from sibling tools like ask_pipeworx for single lookups or breaking news. The verb-resource combination is explicit: 'research across structured data'.

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 on when to use deep_research (broad/multi-part questions over structured data) vs ask_pipeworx (single lookup, breaking news). Also notes account requirements and fallback for unsigned-in users.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond annotations by explaining that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly', which informs 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 front-loaded with purpose and uses two main sentences plus a list of domains. It is efficient but could be slightly more concise by trimming domain list 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?

Given no output schema, the description fully explains what is returned (tool names, descriptions, schemas). It covers the input parameters and provides usage examples. For a tool with moderate complexity (6 params, aliases), 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 coverage is 100%, so baseline is 3. The description adds context by stating that the query accepts natural language, lists example queries, and mentions aliases (though schema already documents them). This provides meaningful extra guidance.

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 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like search_samples or deep_research by emphasizing that it returns tool definitions ready to call.

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 'Call this FIRST when you have many tools available and want to see the option set', providing strong usage context. However, it does not explicitly state when not to use this tool or name specific alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it fans out across multiple sources in parallel, soft-fails for patents (May 2025 sunset), and provides specific return fields. 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 somewhat verbose but well-structured, with front-loaded example queries and a clear list of return fields. Every sentence adds value, though it could be slightly tighter. Still, it is efficient given the complexity.

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

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

Given the tool's complexity (multi-source, no output schema), the description is very complete. It covers return fields, source details, limitations (patents sunset, name handling), and example inputs. The agent has sufficient context to invoke the tool correctly.

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

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

Schema coverage is 100%, and the description enriches parameter meaning significantly. It clarifies that 'value' accepts ticker or zero-padded CIK but not names, and that 'type' only supports 'company' for now. This adds practical guidance 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 provides a full cross-source profile of US public companies in one parallel call, listing specific sources and return fields. It distinguishes from siblings by explicitly recommending this tool over chaining single-pack lookups and referencing related tools like compare_entities and resolve_entity.

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 example queries for when to use the tool and advises to prefer it over chaining separate lookups. It also specifies limitations: names not supported, use resolve_entity first, and notes the patents API sunset. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data, enhancing transparency beyond annotations. No 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?

Two sentences, front-loaded with action ('Delete a previously stored memory by key'), no unnecessary words. Efficient and 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?

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description covers all necessary context effectively.

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 schema fully documents the 'key' parameter. Description does not add further semantics beyond what is in the schema, meeting baseline but not exceeding.

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 deletes a memory by key, using verb 'delete' and resource 'memory'. It distinguishes from siblings 'remember' and 'recall' which store and retrieve respectively.

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 lists when to use: stale context, task completion, clearing sensitive data. Also suggests pairing with 'remember' and 'recall', providing guidance on alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds detail on fetching the page, extracting content, and output format, which complements annotations 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 a single, front-loaded paragraph without wasted words. It efficiently conveys purpose, process, and use cases. Minor improvement could be bullet points for clarity.

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 purpose, process, output, and use cases. No output schema exists, but annotations compensate. Complete enough for an AI 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?

Both parameters have schema descriptions (100% coverage). The description does not add further meaning beyond what the schema provides, so baseline score 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 generates a production-ready llms.txt file, specifies the process (fetch, extract, emit), and includes distinct use cases. It differentiates from siblings by its unique function.

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 use cases (client indexing, own project, competitor audit) but does not mention when not to use or alternatives. Given no direct siblings, this is sufficient.

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 read-only and idempotent. The description adds that the tool returns specific fields (name, dates, taxId, organism, characteristics) and notes it is 'keyless', which is useful context 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?

Two sentences with no fluff. First sentence states purpose, second lists return fields. Perfectly concise and front-loaded.

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

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

For a simple fetch-by-accession tool with no output schema, the description covers the purpose, input format, and output fields. No missing context given the low 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?

The schema already fully describes the accession parameter with examples. The description's mention of accession format repeats the schema's description, adding no new semantic value. Baseline 3 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 clearly states the tool fetches a single EBI BioSamples record by accession, specifying the source, action, and identifier. It also lists return fields, distinguishing it from the sibling 'search_samples' tool.

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

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

While not explicitly stating when to use vs alternatives, the purpose is clear: use this tool when you have a specific accession and need full record details. The sibling 'search_samples' implies a search function, so context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds return field details but does not contradict annotations.

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

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

Two sentences, directly stating purpose and usage. No unnecessary 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?

With one optional parameter, no output schema, and rich annotations, the description is sufficient. It lists return field names, providing helpful 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 coverage is 100%, and the schema describes the only parameter (include_inactive) with a clear description. The description adds no additional parameter info, so baseline 3.

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

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

The description clearly states the tool lists the caller's active subscriptions and lists the return fields. It distinguishes from siblings like 'subscribe' 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?

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations are all false, so the description bears full responsibility. It discloses rate limits (5 per identifier per day), that it's free and doesn't count against quota, and how feedback is processed (daily digests affecting roadmap). 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 concise, well-structured, and front-loaded with the main purpose. Every sentence adds value, with no redundancy or unnecessary information.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description is complete. It covers purpose, usage, behavioral traits, and parameter guidance, leaving no 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%, but the description adds significant value beyond the schema by explaining the enum types with context (e.g., 'bug = something broke'), and clarifying how to use the context and message parameters effectively.

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: to send feedback to the Pipeworx team about bugs, missing features, or praise. It uses specific verbs and resources, and it is distinct from sibling tools which are query or research 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 explicitly explains when to use the tool (for bugs, feature requests, data gaps, praise) and what not to do (don't paste end-user prompts). It also mentions rate limits and quota implications, providing comprehensive usage guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds key behavioral context: data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This goes 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 concise, front-loaded with the main output, and structured with numbered use cases. Every sentence adds value with 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 tool with one optional parameter and no output schema, the description is complete. It covers purpose, use cases, data source, caching, and privacy (no PII). The nature of the output (top tools, top packs, volume) is clearly described.

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 single parameter 'window' has full schema coverage and the description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the right window.

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 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb and resource, and distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on trending data.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents. This gives clear when-to-use guidance and implicitly suggests when not to use (e.g., for specific queries).

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. Description adds extensive context: partition checks, semantic anchor for cross-event, placeholders filter, fill check against live order book depth. 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?

Description is detailed but well-structured with distinct sections for each mode and important notes. Could slightly trim redundancy, but it remains readable and front-loaded with key 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 (three modes, multiple checks), the description is exceptionally thorough, covering response structure, semantic constraints, and edge cases like placeholder filtering. No output schema, but response fields are enumerated.

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%, providing clear descriptions for both parameters. Description adds extra meaning: event accepts full URLs, topic is a seed question, and explains the mode behavior in depth.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific verbs and resources.

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 when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Also advises when not to trade (realizable_edge_pp <= 0) and provides alternatives like polymarket_fill_risk for custom sizing.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds extensive behavioral detail beyond annotations: explains the three model families, caching behavior (1h KV cache), diagnostics structure, and tradeable-edge knobs. 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?

The description is very long and dense, covering multiple paragraphs of technical details. It front-loads the purpose but could be more structured (e.g., bullet points or sections). The length is justified by complexity, but conciseness could be improved.

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

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

Given the tool has 9 parameters, no output schema, and a complex return structure, the description is exceptionally thorough. It explains the response top-level structure (by_segment, fed_candidates, diagnostics), every model family in detail, and all knobs. It even explains why segments might be empty via funnel counters. Perfectly complete 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 coverage is 100%, so baseline is 3. The description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly works on per-leg Kelly) and providing context (e.g., slippage_pp explains Polymarket fee structure). The description compensates for the schema's basic 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 uses a specific verb 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', clearly stating the resource and distinguishing purpose. It also explicitly mentions the intended use case 'what should I bet on today' and outlines three distinct model families, differentiating it from sibling tools like polymarket_arbitrage.

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 explains when to use this tool (discovering opportunities without paging) and provides detailed guidance on how to interpret results and adjust knobs. However, it does not explicitly exclude alternatives or state when not to use, relying on context from sibling names.

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 mark readOnlyHint, idempotentHint, and nondestructive. Description adds details: snapshots have 60-day TTL, decay from daily closes (not intraday), and gaps from cache misses. No contradictions with annotations. Extends transparency beyond defaults.

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?

Description is detailed but not verbose; each section (purpose, response format, limits) earns its place. Front-loaded with core question, though could trim some repetition (e.g., snapshot dates explanation). Still well-structured and 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?

No output schema, but description comprehensively explains response fields (tracked[], expired[], snapshot_dates[]) with attributes like trend, decay rate, lifespan. Also covers data gaps and TTL limits. Complete for a read-only telemetry 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 covers both parameters with descriptions. Description adds additional context: default values, clamp for days, and why window family matters. Adds modest value beyond schema, consistent with baseline for high 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?

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling polymarket_edges by focusing on time-series and decay rather than current edge values.

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 (to assess edge age and decay), contrasting fresh vs old edges for trade decisions. Does not explicitly list alternatives or when not to use, but sibling tools imply polymarket_edges for current edges, so guidance is adequate.

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

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

Annotations declare readOnlyHint, idempotentHint, non-destructive. Description adds valuable context: walks ladder, returns detailed fill metrics (top_of_book, vwap_fill_price, slippage, verdict), per-leg details, and risk analysis (thin_legs, forced_directional_risk). No contradiction with annotations; adds behavioral specifics 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?

Long but well-structured with embedded headings (SINGLE-MARKET:, BASKET:). Front-loads purpose and usage. Every sentence adds value given the tool's complexity (two modes, multiple return fields). Could be slightly more concise, but the detail is justified.

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?

No output schema, yet description fully documents all return fields for both modes, including risk warnings (partial fills, directional exposure). Covers parameters, behavior, and consequences adequately. For a complex tool with 4 params and no output schema, this is extremely 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% (all 4 parameters described). Description adds significant meaning: clarifies size_usd interpretation differs by mode (spend vs target proceeds vs settlement notional), explains side default logic for baskets (auto from partition sum), and defines market/event requirements. Goes well beyond 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?

Description specifies verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), distinguishes between single-market and basket modes with clear semantics. No ambiguity with sibling tools like polymarket_arbitrage or polymarket_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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage... signal or any polymarket_edges trade above ~$500'. Explains when not to use (theoretical overround not capturable, partial fill risk) and provides alternative tool contexts. Also clarifies required parameters ('REQUIRES one of market or event').

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 read-only, open-world, idempotent, non-destructive behavior. The description adds extensive context: compatibility_warning triggers on shape mismatch, temporal_alignment indicates period alignment, and skipped counters explain why certain leg pairs are dropped. 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 relatively long but front-loaded with purpose and modes. Every sentence adds value, though some sentences are lengthy and could be split for clarity. Still, it is well-structured and essential information is easy to find.

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 lack of output schema, the description covers purpose, modes, response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), and limitations (pre-mapped ≠ tradeable). It is complete for an agent to decide when and how to invoke the 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%, baseline 3. The description adds meaning beyond the schema by explaining the two modes, listing topic options, and describing how explicit parameters override the topic-mapped side. This adds value for selecting and using parameters 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 clearly specifies the tool's purpose: computing cross-venue spread between Kalshi and Polymarket. It names two modes ('topic' and explicit) and distinguishes itself from other polymarket tools in the sibling list by focusing on cross-venue comparisons, not single-venue arbitrage.

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 the tool and its modes, and warns that most pre-mapped topics return compatibility warnings, implying explicit mode may be better. However, it does not mention alternatives from the sibling list when to use other tools instead.

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 provide read-only, idempotent, non-destructive hints. Description adds scoping to identifier and the ability to list all keys, providing useful context 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?

Three sentences, minimal and informative, no wasted words. Front-loaded with 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 one optional parameter, no output schema, and annotations covering safety, the description fully explains behavior, scoping, and relationship to sibling tools.

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

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

The input schema has 1 parameter with 100% coverage description. The description adds clarity about omitting key to list all keys, adding value beyond 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 it retrieves a value saved via remember, or lists all keys if omitted. It distinguishes from sibling tools remember and forget.

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 (look up context stored earlier) and mentions pairing with remember and forget. Does not explicitly state when not to use, but context is clear given sibling list.

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

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

The description goes beyond annotations by detailing that returned events include source, citation_uri, and raw payload. It also explicitly discloses the side effect of the 'mark_read' parameter (flags events as read, affecting future calls). This provides crucial behavioral context beyond the readOnlyHint and other 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 four sentences, each serving a distinct purpose: purpose, payload contents, filtering/mark_read behavior, and alternative usage. It is front-loaded with the most critical information and contains no redundant 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?

Given the tool has 5 optional parameters, no output schema, and read-only annotations, the description covers all necessary aspects: what is returned (source, citation_uri, raw payload), how to filter (type, since), the side effect of mark_read, and an alternative access method. This provides a complete mental model for an AI 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the effect of 'mark_read' (flagging events so next call only shows newer ones) and providing an example for 'type' ('sec_8k'). It also clarifies that 'since' expects an ISO timestamp, which reinforces the schema description. However, it doesn't add much to 'limit' or 'unread_only' 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 a clear verb-resource pair: 'Pull fired events from your subscription feed.' It immediately specifies the resource and action, distinguishing it from sibling tools like 'list_subscriptions' which lists subscriptions rather than events.

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

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

The description mentions that polling works fine and provides an alternative REST endpoint for scripts/dashboards, which gives guidance on when to use this tool versus an HTTP alternative. However, it doesn't explicitly state when not to use this tool or compare it to other sibling tools.

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

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

The description details behavioral traits beyond annotations: fans out to multiple data sources, fallback from GDELT to GNews, USPTO soft-fail until May 2025, and return structure. Annotations already indicate readOnlyHint and idempotentHint, aligning with the description.

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 well-structured: it begins with example queries, explains data sources and behavior, then describes input parameters, and concludes with an alternative. Every sentence adds value, though a few details could be slightly more compact.

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 data sources, fallback logic, parameter formats, no output schema), the description completely covers return format (structured changes grouped by source, total_changes count, citation URIs), input behavior, and provides a pointer to the alternative tool 'entity_profile'. Nothing essential 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% with descriptions for all three parameters. The description adds extra meaning by clarifying accepted formats for 'since' (ISO date or relative shorthand), explaining that 'value' can be a ticker or CIK, and noting that 'type' is limited to 'company'. This goes beyond the schema but is not exhaustive.

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 provides a change feed for companies covering SEC filings, news, and patents in a specified time window. It uses specific verbs and resources (e.g., 'change feed', 'fans out to SEC EDGAR, GDELT→GNews, USPTO') and distinguishes itself from the sibling 'entity_profile' tool.

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

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

The description explicitly explains when to use this tool (for recent updates over a window) and when not to use it (for static profiles, recommending 'entity_profile' instead). It provides example queries and alternative usage contexts.

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?

Discloses key behavioral details beyond annotations: key-value scoping by identifier, persistence differences for authenticated vs. anonymous users (24-hour retention). 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?

Efficiently structured: purpose, usage, technical details in 3-4 sentences. No redundancy, every sentence adds value.

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

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

Fully addresses the tool's function, scope, and edge cases given its simplicity (2 params, no output schema). No gaps remain.

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 descriptive examples. Description adds usage context but no additional meaning beyond schema; baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, with specific examples like 'resolved ticker' and 'user preference'. It distinguishes from sibling tools recall and forget.

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 when to use ('when you discover something worth carrying forward') and mentions paired tools (recall, forget), providing clear context for selection.

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 readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds valuable context: it performs multiple internal lookups, returns official identifiers with additional metadata (citation URIs, company name, ingredient), and explains the cascading behavior. This goes beyond annotations by detailing the internal process 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 concise and well-structured: it opens with a summary of the tool's purpose, then provides usage guidance, followed by detailed supported types. Every sentence adds meaningful information without redundancy. It is appropriately sized 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?

Given the tool's simplicity (2 required parameters, 100% schema coverage, no output schema, rich annotations), the description covers all necessary aspects: purpose, when to use, parameter examples, behavioral details, and return value expectations. It fully equips an agent to correctly invoke the 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 for the two parameters (type and value) with enums and descriptions. The description adds value by providing concrete input examples ('AAPL', '0000320193', 'ozempic') and explaining what each type returns (e.g., for company: ticker + 10-digit CIK + company_name + citation URI). This enriches the schema's information.

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 a user-spoken name to a canonical/official identifier for use by other tools. It provides specific examples (ticker, CIK, RxCUI) and explicitly says 'Use FIRST whenever you have a name but need an ID', which distinguishes it from sibling tools like compare_entities or 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?

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID' and notes that it replaces 2-3 manual lookups. It also details supported types and input formats. However, it does not explicitly state when not to use it or mention alternative tools, which would further clarify 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses that it internally calls ai_visibility_check for each entity, returns a ranked list with score/confidence/signal density, and treats the first entity as the subject. 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?

Two concise sentences: first states the core function, second gives a use case and overview of the output. Every sentence earns its place with no redundancy.

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

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

Given no output schema, the description adequately explains the return object (ranked list with score, confidence, signal density) and the process. However, the exact structure per entity could be more explicit.

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?

While schema coverage is 100%, the description adds value by explaining that the first entity in the array is treated as the subject and the rest as competitors, and that the context parameter disambiguates common names. This goes beyond the 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 verb ('Compare AI visibility') and resource ('multiple entities'), with explicit differentiation from the sibling tool 'ai_visibility_check' by noting it probes multiple entities side-by-side.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and implies that for single entities, one should use ai_visibility_check. However, it does not explicitly state when not to use this tool or name alternatives.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. Description adds valuable beyond: mentions graceful degradation, timeouts (5-30s for bundlephobia first measurement), and partial failure reporting via sources_failed.

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?

Description is a single dense paragraph. It effectively front-loads the core purpose, then details return structure and caveats. Could be more structured with bullet points, but still concise and informative.

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?

Without output schema, description fully lists return fields (summary block, per-advisory, links, alternative versions), explains ecosystem scope, failure behavior, and timing caveats. No gaps in required 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 coverage is 100%, so baseline 3. Description adds that scoped packages are accepted and version defaults to latest. However, does not elaborate on other constraints or format details beyond 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?

Description explicitly states the composite check for npm packages, including the verb 'scan' and resource 'dependency'. It distinguishes from other ecosystem tools by specifying NPM only, and contrasts with siblings like 'comparing 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?

Clearly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also specifies when not to use: other ecosystems fall under different tools (deps.dev:version).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns specific fields (accession, name, organism, release date), but does not detail additional behaviors like rate limits or pagination limits 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 two efficient sentences, front-loaded with the core purpose. Every sentence adds value with no redundancy.

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

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

With 100% schema coverage, rich annotations, and no output schema needed, the description covers the tool's functionality well. It could mention pagination behavior beyond defaults, but it's not essential.

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 parameter descriptions. The description reinforces that query is a free-text search but adds no new parameter-level details. Baseline for full coverage is 3.

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

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

The description clearly states 'Search EBI BioSamples' and specifies the type of metadata and search fields (organism, tissue, keyword). It distinguishes from siblings like 'get_sample' which retrieves a single sample.

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

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

The description mentions 'Free-text search' and 'Keyless', giving usage context. However, it does not explicitly state when not to use this tool or point to alternatives like 'get_sample' for specific sample retrieval.

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 safe, read-only, idempotent behavior. The description adds embedding model (BGE-base-en), similarity (cosine), chunking (500-char windows), character cap (200K chars with truncation flag), and offset verification. 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?

Four concise, front-loaded sentences covering purpose, usage, technical details, and pairing. 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?

Given low complexity (3 params, no output schema), the description is fully adequate: it explains what, when, how, technical specifics, and relation to sibling tool. No 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 description coverage is 100%, so baseline is 3. The description adds examples for query, explains the 200K char cap for text, and mentions default limit. This adds some value beyond schema, justifying 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 clearly states the tool performs semantic search inside a fetched record, distinguishes it from sibling tools by noting it's for large records and pairs with ask_pipeworx_grounded. It specifies returning top-N passages with offsets and similarity scores, making the purpose unambiguous.

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

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

Explicit guidance: use when the record is too big to fit in the prompt, and pairs with ask_pipeworx_grounded for grounding over passages. No explicit exclusions but clear context of 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?

The description aligns with annotations (write operation, idempotent, non-destructive) and adds behavioral context: requires OAuth, returns subscription id, explains SMS verification and rate limits, webhook signing and auto-disable. 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 well-structured and front-loaded with the main action. It is detailed but not overly verbose; however, it could be slightly more concise by merging some type and delivery details. Still, every sentence serves a 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?

The description covers the main action, return value, type-specific details, delivery options, and limitations like SMS cap and webhook auto-disable. No output schema is present, so the return value is explained. It could mention error conditions, but overall complete for a create 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%, and the description adds significant meaning beyond the schema: it explains each type's specific params with examples, details delivery constraints, and elaborates on webhook secret handling. Every parameter is well-documented.

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

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

The description uses a specific verb ('Create') and identifies the resource as 'proactive monitoring subscription to a live-data event stream', clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe. Supported types and delivery channels are enumerated.

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 prerequisites (Pipeworx OAuth account) and provides context for when to use (creating subscriptions). It does not explicitly list when not to use, but sibling tools like list_subscriptions and unsubscribe serve as clear alternatives for other operations.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: returns category-bucketed examples with tool/argument shapes, and clarifies that it is safe and idempotent (no side effects). Slight deduction for not explicitly reiterating idempotency, but annotations cover this.

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 purpose and usage. It is somewhat lengthy due to listing examples and topics, but every sentence earns its place for an onboarding tool. Could be slightly more structured, but still clear and 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?

With no output schema, the description fully explains what the tool returns (category-bucketed examples with tool/argument shapes). It covers all necessary context: the optional parameter, the use case, and the source (live catalog). Comprehensive for a simple 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% and already describes the topic parameter. The description adds value by providing examples (finance, pharma, betting) and explaining the effect of omission vs. passing a topic, which helps the agent decide how to invoke the tool.

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

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

The description explicitly states that the tool returns category-bucketed example questions with exact tool+argument shapes, and positions it as the onboarding entry point for a new agent. It distinguishes from siblings by advising to use it first when unsure what Pipeworx can do.

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?

Clear instructions: call with no arguments for full spread or pass a topic to focus. Explicitly states to use it first when onboarding, providing both when-to-use and implied alternatives (e.g., ask_pipeworx after gaining familiarity).

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 annotations (idempotent, non-destructive), the description adds key behaviors: ownership enforcement, row deactivation (not deletion), and that historical events remain available via recent_alerts. 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?

Two sentences with zero waste. Every word serves a purpose: action, constraint, behavior, and side-effect.

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 one-parameter tool with no output schema, the description covers the action, constraints, and effects completely, including mention of related tool 'recent_alerts' for historical data.

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 fully describes the single parameter 'id' (type, required, description). The description does not add additional parameter context, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), specifies the resource (subscription), and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation 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 explains ownership enforcement ('you can only cancel your own subscriptions'), which guides usage. It does not explicitly list when not to use or alternatives, but the tool's purpose is clear and distinct from 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?

Annotations indicate read-only, idempotent, open-world, non-destructive behavior. The description adds detailed behavioral context: structured SEC EDGAR + XBRL for financial claims with exact percent-delta math, grounded pipeline for other claims with verbatim evidence. 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 moderately long but well-organized: starts with example queries, defines purpose, explains dual-path handling, then lists returns. Every sentence serves a purpose, though slight tightening could improve 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?

Even without an output schema, the description fully explains return values: verdict types, actual value with citation, and reasoning. It covers both use cases and edge cases like tolerance overriding. No gaps remain.

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 value: for 'claim' it gives concrete examples; for 'tolerance_pct' it explains default derivation from claim wording and recommends values for hallucination detection. This enriches the schema definitions.

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 concrete examples like 'Is it true that…' and clearly defines the tool's role as natural-language claim verification against authoritative sources. It distinguishes between financial and other claims, specifying different pipelines. This is highly specific and differentiates from sibling 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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains when it handles financial vs. other claims and notes it replaces 4-6 sequential calls. However, it does not explicitly state when not to use it or list alternatives, missing some exclusion guidance.

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