Obis

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds beyond this by detailing return structure (per-model score, confidence, signals, raw_response, combined view), default model (Workers AI, free), and cost implications (BYO API key for Anthropic). It does not contradict annotations and enriches behavioral understanding.

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 purposeful. It front-loads the core action, then details models and returns, and ends with use cases. No redundant words or filler. Perfectly concise.

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 4 parameters with 100% schema coverage, no output schema, and no nested objects, the description covers the return format explicitly ('per-model {score, confidence, signals, raw_response} + a combined view') and ties to practical use cases. With safety annotations, the agent has enough context to select and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for each parameter. However, the description adds meaning beyond the schema: it explains the default model for the 'models' parameter, the purpose of '_apiKey' (BYO key), and the disambiguation role of 'context'. This aids parameter selection meaningfully.

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

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

The description explicitly states the tool 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly identifies the verb (probe), resource (LLMs), and output (visibility score), distinguishing it from siblings like 'ask_pipeworx' which answers questions, and 'compare_entities' which compares entities.

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

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

The description provides context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use, such as for brand visibility checks, but does not explicitly exclude alternatives or mention when not to use. While helpful, it could be more precise about distinguishing from similar lookup tools.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context about routing to 4,552 tools, returning structured answers with citation URIs, which goes beyond annotations without contradicting them.

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

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

The description is front-loaded with the key recommendation and covers all important aspects. While it is somewhat lengthy, each sentence adds value, and the structure is logical. Minor reduction in length 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?

Given the complexity of the tool (6 parameters, all aliases), no output schema, and presence of annotations, the description is highly complete. It explains use cases, alternatives, scope, and provides examples. No missing information for effective use.

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 all 6 parameters being aliases for the same 'question' parameter, and the schema already describes them. The description does not add additional semantic information beyond what the schema provides, so baseline score 3 is appropriate.

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

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

The description clearly states that the tool routes questions to a large set of authoritative sources and returns structured data with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

The description provides explicit guidance on when to use this tool (factual questions, structured data), when to prefer it over web search, and when to use alternatives like ask_pipeworx_grounded or deep_research. It also includes concrete examples and a 'START HERE' recommendation.

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

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

Adds significant behavioral context beyond annotations: extra LLM call cost, explicit refusal reasons, and extraction-only-from-source policy, which complements readOnlyHint=true and idempotentHint=true.

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

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

Well-structured with front-loaded purpose, but somewhat verbose with detailed return format and examples; could tighten while retaining 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 covers purpose, usage, behavior, return structure, and refusal reasons, despite no output schema; annotations provide safety 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 already covers all parameter aliases with 100% description coverage; description only reinforces that question is natural language, adding minimal extra meaning.

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's a 'Hallucination-resistant answer mode for high-stakes reads' and contrasts its grounded extraction method with the sibling ask_pipeworx, providing a specific verb and resource.

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 (quotable, critical answers) and when not to use (casual lookups, prefer ask_pipeworx), with concrete examples like financial verdicts and medical lookups.

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 (readOnlyHint, idempotentHint) are already present, but the description adds extensive behavioral context: fan-out logic, response structure, resolver contract, parent event extractor, news field fallbacks, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule parsing. No contradiction with annotations; all disclosed behaviors are read-only.

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

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

The description is long but well-structured with clear headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). It front-loads the purpose and usage. Every sentence serves the explanation; no filler. Could be slightly more concise, but the detail is justified by 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?

Despite no output schema and only 3 parameters, the description comprehensively explains the return shape, edge cases (low-confidence, closed markets, wide spreads, cancellation rules), and error handling. It covers everything an agent needs to correctly invoke and interpret 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 description coverage is 100%, so baseline is 3. The description adds context beyond the schema (e.g., examples of market_input as slug, URL, or question; depth options quick vs thorough; include_raw effect). These reinforce but do not drastically expand on 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 explicitly states the tool 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the verb (research) and resource (Polymarket bet) and distinguishes from siblings like polymarket_edges or validate_claim by focusing on an all-in-one data pull. Use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'.

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 for...' and details when the tool short-circuits (low-confidence, closed markets). However, it does not directly compare to sibling tools (e.g., when to use polymarket_edges instead). Still, the context is clear enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: it uses SEC EDGAR/XBRL for company data, handles off-calendar fiscal years, returns results sorted by primary metric, and provides citation URIs. 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 informative but somewhat verbose with multiple example queries. Although these examples are helpful, it could be slightly more concise. However, it is well-structured and front-loaded with key 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?

For a complex tool with two entity types and different data sources, the description is complete. It explains what data is pulled, how results are sorted, and that it returns paired data with citation URIs. No output schema, but description covers return format.

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

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

Schema coverage is 100% and descriptions are clear. The tool description adds meaning beyond schema by explaining that 'values' are tickers/CIKs for companies and drug names, and that different types pull different data. It also explains sorting behavior.

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 it provides side-by-side comparison of 2–5 companies or drugs. It gives example queries like 'X vs Y' and clarifies the data source and entity types. It distinguishes from siblings by recommending this over sequential single-pack lookups.

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

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

The description clearly states when to use this tool: for comparing entities, with specific example queries. It explicitly says 'ALWAYS PREFER over sequential single-pack lookups', providing guidance on when not to use 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?

Adds significant context beyond annotations: account requirements, depth options with facet counts, output format (findings packet with gaps), expected time (15-60s), and that it's not open-web search. 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 front-loaded key information (account required) followed by clear sections on purpose, usage, and expectations. Every sentence adds value, though could be slightly more concise.

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 adequately explains the return format (findings packet with evidence, confidence, citations, gaps). It covers key behavioral traits and limitations. A full output schema would be helpful but not required.

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 both parameters. The description adds minor extra context (e.g., depth defaults and facet counts) but does not significantly augment what the schema already provides.

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

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

The description clearly states the tool does grounded multi-source research across 1160 structured data sources, decomposes questions into facets, and routes to thousands of tools in parallel. It distinguishes from siblings like ask_pipeworx for single lookups or breaking news.

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 provides when-to-use and when-not-to-use: best for broad/multi-part structured data questions, not for single lookups (use ask_pipeworx) or breaking current news (prefer ask_pipeworx). Also specifies account requirement and fallback tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: results include full input schemas with curated examples and are ready to call directly. No contradictions, though it could mention output format details.

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

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

The description is structured with a clear first sentence, followed by a list of domains, return value details, and a usage directive. While not extremely terse, every sentence adds value and the information is front-loaded. Slightly long but efficient.

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

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

Given the tool's purpose (discovery), the description adequately explains its function, when to call it, what it returns (top-N tools with schemas), and the fact that results are immediately callable. No output schema exists, but the description compensates by describing the return structure.

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% (6 parameters with descriptions). The description mentions that query accepts multiple aliases (task, q, search, description) but this is already captured in the schema. It does not add significant new semantic meaning beyond what the schema provides.

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

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

The description uses a specific verb ('Find tools') and clarifies the resource ('by describing the data or task'). It lists concrete domains (SEC filings, financials, FDA drugs, etc.) and distinguishes the tool from siblings like search_within or ask_pipeworx by focusing on tool discovery rather than data retrieval.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies not to use it when you already know the specific tool, setting it apart from 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?

Beyond annotations (readOnly, idempotent, not destructive), description reveals it fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF) in one parallel call. Notes USPTO PatentsView API sunset May 2025 and soft-fails. 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?

Fairly long but front-loaded with purpose and usage. Each sentence adds value. Could be slightly more concise, but structure is logical: intent examples, purpose, comparison to alternatives, input format, output details, limitations.

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, description comprehensively lists all return fields: cik, company_name, recent_filings (with URIs), fundamentals (specific fields), patents, news, LEI. Also covers limitations and error conditions (USPTO sunset, name rejection). Complete for a complex tool.

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

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

Schema coverage 100% and each param has description. Description adds value by clarifying 'type' currently only 'company', 'value' must be ticker or zero-padded CIK, and explicitly says names not supported. Provides examples like 'AAPL' or '0000320193'.

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?

Clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call.' Distinguishes from siblings like resolve_entity (name resolution) and compare_entities. Examples show specific user intents like 'tell me about X' or 'company profile for Microsoft.'

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies when NOT to use: 'names not supported (use resolve_entity first).' Provides guidance on input format (ticker or CIK, not 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 adds value beyond annotations by confirming the tool returns both a total match count and a sample of records, and lists the specific fields included. Annotations already declare readOnly, openWorld, idempotent, and not destructive, so the description complements rather than contradicts 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 two sentences long, front-loading the key purpose and return fields, with no extraneous information. Every sentence contributes value.

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

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

Given the tool's simplicity, the description adequately covers purpose, return content, and optional filters. It lacks details on pagination or error handling, but the overall intent and output are sufficiently clear without requiring an output schema.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning by detailing the return fields (latitude, longitude, date, depth, etc.), which are not in the parameter descriptions, thus providing context 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 explicitly states the tool finds georeferenced marine occurrence records for a scientific name from OBIS, listing specific return fields. This is a specific verb-resource pairing that clearly distinguishes it from sibling tools, which either operate on different data (e.g., get_taxon) or are unrelated.

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

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

The description implies usage when searching for occurrence records by scientific name, with optional date filtering, but does not provide explicit guidance on when this tool should be used versus alternatives like get_taxon, nor does it mention when not to use it.

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

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

Annotations already declare destructiveHint=true, and the description's 'Delete' aligns with that. However, the description adds little beyond the annotations, only providing context on when to use it rather than new behavioral traits.

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

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

Two sentences, front-loaded with the action and resource, then usage advice. 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 parameter and no output schema, the description covers purpose, usage context, and sibling relationships. It lacks details on return values or error handling, but those are not expected given the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter 'key,' with its description 'Memory key to delete.' The tool description repeats 'by key' without adding more meaning, so this is baseline.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the action and resource. It also distinguishes from siblings by mentioning pairing with remember and recall.

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 scenarios for use: when context is stale, task is done, or clearing sensitive data. It also suggests pairing with remember and recall, but does not explicitly exclude inappropriate usage.

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 behavior beyond annotations: fetches page, extracts title/description/key links, emits standard format. Annotations already indicate readOnly, idempotent, non-destructive; description adds fetch and extraction details.

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 concise: one sentence for main purpose, then bullet list of use cases. Front-loaded with key information, 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?

Given simple tool (2 params, no output schema), description covers input, behavioral steps, output format, and use cases. Complete and sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions. Description adds no significant new semantic details beyond what schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states verb (generate), resource (llms.txt file for any URL), and specific purpose (for AI crawlers to index). Distinguishes itself from siblings by unique functionality.

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 three use cases (client indexing, own project drafting, competitor auditing). No explicit when-not-to-use, but the use cases are clear and tool is 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?

The description adds value beyond annotations by detailing the specific outputs returned (total records, distinct species, etc.). Annotations already indicate read-only, idempotent behavior; the description confirms no modifications. No behavioral traits like rate limits are disclosed, but for a simple query this is acceptable.

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, 18-word sentence that is front-loaded with the main verb and resource. No redundant 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?

Given the simple tool with one parameter, full schema coverage, and annotations, the description is fairly complete. It lists expected outputs, though it could mention the return format. Still adequate for selection.

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 schema coverage at 100%, the single parameter scientificname is well-documented in the schema. The description does not add any additional meaning or constraints beyond the schema, remaining at baseline.

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

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

The description clearly states it gets aggregate OBIS statistics for a marine taxon, listing specific outputs (total occurrence records, distinct species, etc.). It distinguishes from sibling tools like find_occurrences and get_taxon by focusing on aggregate metrics.

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

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

The description implies usage when aggregate statistics are needed, but does not explicitly state when to use this tool over alternatives like find_occurrences or get_taxon. No exclusion criteria or prerequisites are mentioned.

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 the tool as read-only, idempotent, non-destructive, and open-world. The description adds value by detailing the specific returned fields (taxon ID, rank, accepted name, taxonomy, occurrence count) and noting that no API key is required ('Keyless'), which goes beyond what annotations provide.

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

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

The description is three concise sentences, front-loading the main action. It efficiently provides acronym expansion and key details without unnecessary words. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the input, return fields, data source (OBIS), and marine focus. It omits details on failure behavior or multiple matches, but given the tool's simplicity and strong annotations, it is largely 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?

With 100% schema description coverage, the parameter 'name' is well-documented in the schema. The tool description does not add additional meaning beyond the schema's examples, so it meets the baseline without further enrichment.

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 resolves a marine taxon name against OBIS to retrieve detailed taxon record fields. It uses a specific verb (resolve) and resource (taxon name), and distinguishes itself by emphasizing the marine focus and complementing GBIF.

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

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

The description implies usage for marine species lookups via OBIS and mentions complementing GBIF, but does not explicitly state when to use this tool versus alternatives like 'resolve_entity'. There are no direct exclusions or alternative tool names provided in the description.

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

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

Annotations already declare the tool as read-only (readOnlyHint=true), idempotent, and non-destructive. The description adds minimal behavioral context beyond stating that by default only active subscriptions are returned. The extra detail is useful but not extensive.

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

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

The description is two sentences: first states purpose and return fields, second gives usage guidance. Every sentence adds value, no fluff. Highly 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?

Given the tool's simplicity (one optional param, no output schema, clear annotations), the description covers the core purpose and usage. It does not mention pagination or limits, but those are likely not critical for this read-only listing. Adequate for an agent to select and invoke.

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% (one parameter with a full description). The tool description does not add any additional meaning beyond what the schema already provides. Thus, 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 verb 'List' and the resource 'the caller's active subscriptions'. It enumerates specific return fields (id, type, etc.), making the tool's purpose unambiguous. 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 use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This gives clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives beyond the implied subscription management flow.

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 rate limits (5 per identifier per day), free usage, and non-counting against quota. Annotations already present but description adds valuable behavioral context.

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

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

Three well-structured sentences: purpose, usage, constraints. Front-loaded with main point, 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?

Covers all necessary aspects: purpose, when to use, parameter guidance, rate limits, and team usage. No gaps given no output schema and moderate complexity.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. Description reinforces parameter usage (e.g., describe in terms of tools/packs) but does not repeat schema. Slightly above baseline due to added usage 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 the tool is for sending feedback to Pipeworx, listing specific categories (bug, feature, data_gap, praise). It distinguishes from sibling tools which are for queries, research, or actions.

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 guides when to use for each feedback type (e.g., bug when tool returns wrong data) and what not to do (don't paste end-user prompt). No ambiguity.

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

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

Adds context beyond annotations: no PII, derived from analytics engine, data shape (pack, tool, count), caching durations. Annotations already indicate safe read operation, but description enriches with operational details.

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?

Concise, well-structured with bullet points for use cases and technical notes. No wasted sentences; 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?

Complete given tool simplicity: explains data source, caching, privacy, and result shape. No gaps left for an agent to misinterpret.

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 enum and description. Description adds interpretation of window choices (short vs. long term trends), enhancing beyond schema-provided info.

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?

Describes exactly what the tool returns (top tools, packs, call volume) and the context (recent window). Distinguishes from siblings like 'discover_tools' 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?

Lists three concrete use cases: discovering hot data sources, confirming canonical tools, and aligning with agent needs. Implicitly guides when to use, though no explicit 'when not to use' is given.

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 readOnlyHint, openWorldHint, idempotentHint, and destructveHint=false. The description goes far beyond by detailing behavioral traits: top 200 markets scanned, walking child markets, partition checks, semantic anchor, partition filter, and fill check. 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 long but front-loaded with the core action. It proceeds logically through modes, semantics, and advanced checks. Some details like fill check could be condensed, but overall it is well-structured and every sentence adds value.

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

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

Given the complexity of the tool and absence of an output schema, the description covers all essential aspects: modes, parameters, edge cases (low similarity, partition filter), fill check, and references another tool for custom sizing. It is comprehensive and leaves no critical 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?

The input schema has 2 parameters with 100% coverage. The description adds extensive meaning beyond the schema: explains what event slug and topic seed question are, how each mode works (including scanning behavior, partition checks, and fill check integration). This greatly enriches the parameter understanding.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific contexts. The verb 'find' and resource 'arbitrage opportunities on Polymarket' are precise, and it differentiates from siblings like polymarket_edges and polymarket_fill_risk by its detection logic.

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 each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also recommends event for specific markets. However, it does not explicitly state when not to use this tool or provide alternatives from the sibling list, losing a point for completeness.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: caching (1h at KV level), no mutations, response structure with diagnostics, and details on how edges are calculated. 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 dense and front-loaded with the core purpose, then structured logically into model families and response segments. While long, every sentence adds value for agent understanding. It is appropriately detailed given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), edge calculation details, and the rationale behind each segment. This provides a complete mental model for an agent to use the tool correctly.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The tool description adds value by grouping knobs (e.g., 'tradeable-edge filters', 'segment filters') and explaining their role in the overall workflow, but does not significantly add beyond the schema's own descriptions.

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

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

The description clearly states the tool's action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific verb ('scan', 'return') and resource ('Polymarket markets'), and the purpose is distinct from siblings like polymarket_arbitrage and polymarket_kalshi_spread.

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 'Built for "what should I bet on today"' and mentions tradeable-edge knobs and category filters, providing clear context for when to use it. However, it lacks explicit guidance on when not to use it or which alternatives (e.g., bet_research, polymarket_arbitrage) to prefer.

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

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

The description goes well beyond annotations, detailing data source (daily snapshots), response structure (tracked, expired, snapshot dates), computed fields (trend, decay_pp_per_day), and limits (60-day TTL, not intraday). No contradiction with annotations.

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

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

The description is well-structured with sections for args, response, and limits, all front-loaded with purpose. While lengthy, every sentence adds value, making it informative without unnecessary fluff.

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

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

Given no output schema, the description fully explains the response format, fields, and data gaps (snapshot dates). It covers behavior, limits, and edge cases, making the tool's output predictable.

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

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

The schema already describes both parameters with 100% coverage. The description adds context like default values, max clamp, and window options, enriching understanding 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 it provides edge persistence and decay telemetry, answering a specific question about edge longevity. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical 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 implies when to use this tool (to understand edge history and decay) and contrasts with a fresh edge, but does not explicitly state when not to use it or name alternatives. Clear context but lacks explicit exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: 'walks the ladder' algorithm, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and mentions forced_directional_risk. No contradiction. The description supplements annotations well, though annotations already provide a clear safety profile.

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 well-structured: starts with overall purpose, then REQUIRES clause, then details each mode with bullet-like formatting, and ends with usage guidance. Front-loads key constraint (REQUIRES one of market or event). While somewhat verbose with detailed output field lists, every sentence adds value and no information is redundant. Minor improvement could condense output field enumeration.

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 (two modes, 4 params, no output schema), the description is exceptionally complete. It explains inputs, behavior, outputs for both modes, and risk scenarios. Warns about partial fills causing directional risk and failure modes. Without output schema, it lists return fields. Virtually all information needed for correct and safe invocation is present.

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 baseline 3. The description adds significant value: explains mode-dependent semantics (size_usd interpretation differs between single-market and basket), default values (side default auto in basket), and REQUIRES clause (one of market or event). This goes beyond the schema's static descriptions, earning an extra point.

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 does a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verb 'check' and resource 'edge' against order-book depth. It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on any polymarket_arbitrage...' indicating its advisory role.

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

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

Explicitly states when to use: before acting on arb signals or trades above ~$500. Provides clear exclusions: 'theoretical overround on thin books is not capturable' and warns that partial basket fills convert an arb into a directional position. Offers alternative context by referencing sibling tools. No ambiguity on usage.

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 (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral context: explains two failure modes for compatibility_warning, temporal alignment importance, and skipped_cross_type/subtype counters. 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 long but well-structured with clear sections (two modes, response format, safety fields). Every sentence adds value, but minor redundancy could be trimmed without losing 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?

Despite lacking an output schema, the description thoroughly explains the response format (leg-by-leg prices, matched spread, safety fields) and compensates with detailed behavioral context. The tool's complexity is fully addressed.

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 meaning by explaining the two modes and how parameters interact (topic overrides explicit). Examples of topic values and explicit ticker/slug formats are provided.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing between pre-mapped topic shortcuts and explicit parameter pairing. It differentiates from siblings by being cross-venue specific.

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 topic mode vs explicit mode, explains that most pre-mapped topics are not tradeable, and details how to interpret safety fields like compatibility_warning and temporal_alignment.

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. The description adds value by explaining scope and pairing with other tools, without contradicting annotations.

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

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

Two sentences with no waste. The first sentence states the core purpose, the second adds context and pairing. Every sentence earns its place.

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

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

For a simple read-only tool with full annotation coverage, the description covers all necessary aspects: purpose, usage, scope, and relationship to siblings.

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 describes the optional key parameter. The description adds the behavior when key is omitted (list all keys), providing extra semantic meaning.

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 specific verbs ('Retrieve', 'list') and clearly identifies the resource (saved values via 'remember'). It distinguishes from sibling tools like 'remember' and 'forget' by naming them.

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

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

It states when to use the tool ('look up context the agent stored earlier') and mentions scope (identifier-based). It does not explicitly list when not to use it, but the context makes it 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 indicate readOnly, idempotent, non-destructive. The description adds behavioral details: returns specific fields (source, citation_uri, payload), filter capabilities, and mark_read side effect (flagging events as read). 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?

Four sentences, front-loaded with main purpose, no redundant words. Every sentence earns its place by adding unique information (return structure, filters, side effects, alternative endpoint).

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, description covers return values sufficiently. With complete annotations and full schema coverage, the description fills all gaps: explains return fields, filter behavior, and usage context. Complete and self-contained.

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 enhances parameter meaning: provides example for type ('sec_8k'), clarifies since is ISO timestamp, explains mark_read effect and unread_only implicitly. Adds 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?

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It details what each alert carries (source, citation_uri, raw payload), distinguishing it from sibling tools like subscribe/unsubscribe and list_subscriptions.

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 mentions 'Polls work fine' and provides an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, guiding when to use this tool vs. direct HTTP access. Also explains filter options by type and since timestamp, and mark_read behavior.

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. Description adds rich behavioral detail: fans out to multiple sources with fallback, handles relative date shorthands, soft-fails for USPTO due to API sunset. 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?

Single paragraph but well-structured: starts with common queries, then purpose, sources, parameter details, return shape, and alternative usage. Every sentence adds value. Could be more structured with bullet points, but not overly verbose.

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

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

Given no output schema and high complexity (multiple sources, fallback, date parsing), the description covers return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), source behaviors, and edge cases (soft-fail for USPTO). Complete for agent usage.

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%. Description adds value for 'since' with examples (ISO date vs relative) and usage tip ('30d' or '1m' for typical monitoring). For 'value' it explains ticker or CIK. Provides more context than schema alone.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It provides example user queries and distinguishes from sibling tool 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?

Explicit guidance on when to use: 'What's new with X' queries, and when not to: 'Use entity_profile instead when you want the static profile...' Also describes fallback logic between GDELT and GNews.

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 idempotent and non-destructive behavior. Description adds key-value scoping by identifier, persistence details, and that data is saved for later reuse, complementing 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?

Five sentences, front-loaded with purpose, 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?

Given two required parameters and no output schema, description fully covers purpose, usage, scoping, persistence, and pairing, 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% with descriptions for key and value. Description adds usage examples and context but doesn't significantly expand beyond schema; thus above 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?

Description clearly states the tool saves data for reuse across conversations or sessions, using specific verb 'Save' and resource 'data'. It distinguishes from siblings '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?

Explicit guidance on when to use ('when you discover something worth carrying forward') and pairing with recall/forget. Also explains persistence differences between authenticated and anonymous sessions.

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, idempotent, openWorld, and non-destructive behavior. The description adds rich behavioral context: it cascades through several lookup endpoints internally, auto-disambiguates, and returns specific structures (e.g., for company: ticker, CIK, company_name, citation URI). This goes well beyond the annotations and fully informs the agent of the tool's 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 well-structured, starting with user-facing query examples, then the core purpose, usage guidance, and detailed type breakdown. Every sentence adds value, though the length is appropriate. It is front-loaded with the most important information.

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

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

Given the two-parameter schema, rich annotations, and absence of an output schema, the description provides complete context: when to use, what inputs are valid, what outputs each type produces, and internal behavior (cascading lookups). No gaps remain for the agent to use 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% with both parameters documented. The description enhances understanding by providing examples for each parameter (e.g., 'AAPL' for company ticker, 'ozempic' for drug), clarifying accepted formats, and explaining return values per type. This adds meaningful context beyond 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 clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific query examples ('What's the ticker for...', 'find the CIK for...') and explicitly positions it as the first tool to use when needing an identifier. This distinguishes it from sibling tools like entity_profile or compare_entities, which likely require an identifier as input.

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.' It also explains the supported entity types and what they return, helping the agent decide when to use this tool. However, it does not explicitly list alternative tools or when not to use it, though the context of being the first step 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?

The description discloses that it probes each entity with 'ai_visibility_check' and ranks results. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false, which the description aligns with. It adds behavioral context about ranking and output fields (score, confidence, signal density), but could be more explicit about edge cases like empty input.

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

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

Four sentences, front-loaded with the core purpose, followed by a concrete use case and return format. 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?

With no output schema, the description adequately describes the return type (ranked list with score, confidence, signal density). It covers the process and use case. However, it lacks details on error handling, constraints (e.g., max 8 entities), or how the 'subject' affects narrative.

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 that the first entity in 'entities' is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema. It also clarifies the optional nature of 'models' and '_apiKey'.

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 compares AI visibility across multiple entities, ranks by score, and surfaces the most/least recognized. It gives a concrete example ('does Claude know about us as well as our competitors?') and distinguishes from the sibling tool 'ai_visibility_check' by being a comparative, multi-entity wrapper.

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 it is useful for competitive AI-marketing audits and provides an example query. It implies when to use (comparative analysis) and when to use the simpler sibling 'ai_visibility_check' (single entity). However, it does not explicitly state exclusions or alternative tool names beyond the implicit 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 indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds crucial behavioral details: fan-out across services, partial failure handling with 'sources_failed', and potential delay for bundlephobia's first measurement (5-30s). 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 a single paragraph but well-structured, starting with the core purpose and then detailing behavior and output. Every sentence adds meaningful information. Could be slightly more concise, but length is justified by complexity.

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

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

With no output schema, the description fully explains the return value structure (summary block fields, per-advisory detail, links, alternative versions) and edge cases (partial failures, timeouts). It covers input, output, and behavior 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?

Input schema already describes both parameters with 100% coverage. The description adds context: package is npm package name (scoped accepted), version defaults to latest. It also hints at output fields, which indirectly informs parameter usage. This adds moderate value over 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 performs a composite check for adding an npm package, detailing the specific services (deps.dev, bundlephobia) and the types of information gathered. It distinguishes from potential alternatives by noting NPM ecosystem only and pointing to deps.dev:version for other ecosystems.

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 contexts: 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes ecosystem limitations and partial failures. While it doesn't explicitly state when not to use, the guidance 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds crucial behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and passage offsets. 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 (~100 words), front-loaded with the primary use case, and every sentence adds value. No redundant or vague statements.

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 an output schema, the description clearly explains return values (top-N passages with character offsets and similarity scores). It also covers edge cases (truncation, chunking method) and integration hints. Fully adequate for agent decision-making.

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 each param having a description. The tool description adds context beyond the schema: for 'text' mentions max ~200K chars, 'limit' default and range implied, and 'query' gives example queries. Adds 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded for grounded Q&A over relevant passages, making its unique 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?

Explicitly advises use when the record is too large for the prompt, saving context. Mentions pairing with ask_pipeworx_grounded but does not provide explicit when-not-to-use or full list of 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?

Adds significant behavioral context beyond annotations: requires OAuth, delivery channel details (email/SMS caps, webhook signing), and subscription types. 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?

Well-structured with clear sections, front-loaded purpose. Slightly long but justified by complexity. Could be more concise, but overall 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?

Comprehensive coverage for a complex subscription tool: explains return value (subscription ID), all types and parameters, delivery channels, and important constraints (account requirement, caps). No output schema, but description fills the gap.

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

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

Schema coverage is 100%, and the description adds extensive meaning: explains each type with examples, details delivery options, and provides format constraints (e.g., E.164 for sms).

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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like unsubscribe and list_subscriptions.

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 prerequisite (Pipeworx OAuth account) and explains when to use (proactive monitoring). Does not explicitly mention when not to use or list alternatives, but the context of sibling tools implies 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 readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: returns structured example questions with exact tool+argument shapes, drawn from a live catalog. 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?

Single well-structured paragraph. Front-loaded with common user queries, then explains purpose, then lists categories, then parameter behavior, then usage advice. No redundant sentences.

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

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

Given the tool has one optional parameter, no output schema, and many siblings, the description fully covers: what it does, what it returns, parameter behavior, and when to use it. 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% with description for 'topic' listing allowed values. Description adds value by explaining omitting returns full spread, and provides examples of topics. This goes beyond basic schema 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?

Clearly states the tool returns category-bucketed example questions about Pipeworx capabilities. It lists specific categories and emphasizes it's the onboarding entry point, distinguishing it from sibling tools like ask_pipeworx or compare_entities.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning meta-tools. Provides clear context for when to use, but does not explicitly specify when not to use.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds value by clarifying that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. It also explicitly mentions ownership enforcement, which is an important behavioral trait not captured by annotations.

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

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

The description is two sentences with no wasted words. The first sentence immediately states the primary function, and the second provides essential behavioral context. Every sentence adds unique value.

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

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

Given the tool's simplicity and the richness of annotations and schema, the description covers the core behavior and side effects. While there is no output schema and the return value is not mentioned, the description is sufficient for an agent to understand the tool's effect. Slight gap: the description could specify what the tool returns, but it's not critical.

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

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

Schema coverage is 100%, so the schema already fully documents the 'id' parameter. The description adds no additional semantic detail beyond what the schema provides (it simply restates that the id is returned by subscribe).

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 'Cancel a subscription by id.' It uses a specific verb ('Cancel') and resource ('subscription'), distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. The additional detail about ownership enforcement further clarifies the scope.

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

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

The description implicitly guides usage by stating ownership enforcement ('you can only cancel your own subscriptions'), which sets a precondition. It does not explicitly mention alternatives, but the sibling context makes the use case obvious.

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, etc. The description adds behavioral context: returns verdict types (confirmed, refuted, etc.), structured form, actual value with citation, and percent delta. It also specifies the data source (SEC EDGAR+XBRL). 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 informative and front-loaded with the core purpose. Each sentence provides value: examples, usage guidance, supported scope, output details, and efficiency benefit. It is not overly verbose but could be slightly more concise.

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

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

Given the single parameter and no output schema, the description fully covers the tool's behavior, supported claims, output format (verdict, structured form, value, citation, delta), and context. It leaves no major gaps for an agent to misunderstand.

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 a single parameter 'claim' described. The description adds value by providing natural-language examples and clarifying the supported claim domain (company-financial). This goes beyond the schema description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It gives example queries and distinguishes itself from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly says to use 'whenever the agent needs to check whether something a user said is factually correct' and provides the scope of supported claims (company-financial). It does not explicitly state when not to use, but the specificity implies limitations. This is clear but lacks exclusion criteria.

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