Oregon Open Data

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context: default model, free vs. paid model (BYO key), and return format (per-model and combined view). This 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 four sentences, each serving a distinct purpose: definition, model/cost details, return format, and use cases. No redundancy or fluff. Front-loaded with the core action.

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

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

For a tool with 4 parameters and no output schema, the description adequately covers inputs and outputs. It mentions per-model and combined results but does not specify how the combined score is derived (e.g., average, max). Overall, sufficiently complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior for 'models', the pass-through nature of '_apiKey', and the disambiguation purpose of 'context'. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It specifies the resource (LLMs) and action (probe and score). It does not explicitly differentiate from siblings like 'scan_competitor_ai_presence', but the unique output format and cost structure provide implicit distinction.

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 lists use cases (AI-marketing audits, pre-launch brand checks) but does not provide explicit guidance on when to use this tool versus alternatives like 'ask_pipeworx' or 'deep_research'. It mentions default free model and optional Anthropic key, implying cost considerations.

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, read-only behavior. The description adds valuable context: it routes questions to one of many tools, returns structured answers with citation URIs, and works on all tiers with a single fast call. No contradictions.

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

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

The description is well-structured, front-loading the key preference statement. Every sentence adds distinct value—usage guidance, examples, alternatives, and behavioral details—without redundancy or waste.

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 (routing to thousands of sources), the description is remarkably complete: it covers purpose, when to use, how it works, examples, fallback options, and what makes it the default entry point. No output schema needed; the description clarifies 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% with detailed descriptions. The description adds examples and clarifies that input is natural language. While the schema already documents aliases, the examples and usage context raise the value beyond 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 articulates the tool's purpose: answering factual questions by routing to specialized tools across many domains. It explicitly contrasts with web search and names alternatives, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance on when to use this tool (default for most factual questions) and when to step up to other tools (for hallucination-resistant answers or broad multi-part queries). Includes concrete examples and a preference statement.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it details the routing process (picking from 4,482 tools across 1,129 sources), the extraction step using only tool results, and the explicit refusal reasons. 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 and front-loaded with the key purpose and usage. Every sentence adds value, but it is slightly lengthy. However, it remains efficient for the complexity explained.

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 (routing, extraction, refusal modes) and lack of output schema, the description covers main aspects: behavior vs ask_pipeworx, return format, refusal reasons, and use cases. Missing minor details like timeout limits, but overall sufficient.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions), so baseline is 3. The description does not add additional meaning about the parameters beyond what the schema already provides (e.g., it mentions 'question' is accepted with alias names, but the schema already details that). Thus, no extra value.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies that it uses the same routing as ask_pipeworx but extracts answers only from tool results, with evidence and refusal reasons. This distinctively separates it from its sibling.

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 advises when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides when-not guidance: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This clearly differentiates usage from ask_pipeworx.

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 extensively details behavioral traits: resolution mechanism (low_confidence_match, market_closed_or_inactive), short-circuiting, tradeability warnings, cancellation rule parsing, and response structure. Annotations already indicate readOnly and idempotent, but the description adds critical runtime behavior and safety checks. 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 lengthy but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded purpose. Each sentence adds necessary detail for a complex tool. While verbose, it earns each sentence by covering numerous edge cases and response shapes, making it appropriately sized.

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

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

Despite no output schema, the description comprehensively details response shapes (market, analysis, evidence, resolver contract, parent_event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It provides nearly all information an agent needs to use the tool correctly and interpret results.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value beyond the schema by explaining the market parameter's flexibility (slug, URL, question text), depth options with practical examples, and include_raw with response size implications. This enhances agent understanding of how to use parameters effectively.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant data. It specifies input formats (slug, URL, question) and distinguishes by listing numerous classifiers and fan-out examples, making its scope distinct from sibling tools like polymarket_edges.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). The description also provides examples of when specific data packs are relevant (e.g., BTC bet → coingecko, fred, gdelt+gnews). However, it does not explicitly state when not to use this tool or directly compare to alternatives for specific scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: data freshness (latest 10-K), handling of off-calendar fiscal years, sorting by primary metric, return format (paired data + citation URIs). 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 of about 7 sentences, efficiently packing examples, purpose, data sources, and usage guidance. It front-loads example queries. Could be slightly more structured (e.g., bullet points) but is effective and not 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, the description explains returns ('paired data + pipeworx:// citation URIs per entity') and the sorting behavior. It covers key aspects like entity types, data sources, and replacement value. Explicit field names (e.g., revenue, net income) are not listed, but they are implied by the data sources, leaving minor gaps.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains the type parameter differentiates company vs drug and what data each returns; specifies values as tickers/CIKs or drug names with min/max items. It also describes behavioral implications like sorting by primary metric, beyond the schema's basic constraints.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one call, with example queries like 'compare X and Y'. It specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and unique handling of off-calendar fiscal years. This distinguishes it from sibling tools like entity_profile, which is for single entities.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8–15 sequential lookups, providing clear when-to-use guidance. However, it does not explicitly mention when not to use it (e.g., for a single entity), though that is implied by the 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 declare readOnly=true, destructive=false. Description adds return fields and suggests follow-up action but doesn't disclose pagination or rate limits. Adds marginal value beyond annotations.

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

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

Two sentences with no waste. Purpose stated first, returns listed, and usage hint provided. Highly 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?

For a simple read-only search tool with complete schema and annotations, description adequately covers purpose, return values, and next steps. No output schema, but field names are given.

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

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

Schema coverage is 100%, so schema already documents each parameter. Description restates 'keyword' and return context but adds no new semantics 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 verb 'Search', resource 'Oregon Open Data catalog', and specific fields returned. Distinguishes from siblings like 'query' and 'metadata' by being dataset-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?

Explains when to use (searching datasets by keyword) and hints at next step (pass resource_id to query/metadata). Does not explicitly state when not to use or list alternatives, but context is clear.

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

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

Details decomposition into facets, parallel tool routing, output format (evidence, confidence, source, fetched_at, citation, gaps), and expected duration (15-60s). 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?

Dense but front-loaded with critical info. Every sentence adds value, though could be slightly trimmed without losing meaning.

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

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

Covers prerequisites, inputs, behavior, outputs, timing, and limitations. Despite no output schema, the description fully explains what the tool returns.

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

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

Schema coverage is 100% so baseline 3. Description adds value by explaining depth enum values (quick=3, standard=5, thorough=8) and providing example questions.

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 performs 'grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and explicitly distinguishes from open-web search and sibling ask_pipeworx. Provides concrete examples of appropriate queries.

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 (broad/multi-part structured questions) and when not (breaking news, ask_pipeworx). Also mentions account requirement and paid plan for thorough depth.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns tools with full schemas and curated examples, and that results are ready to call directly, which is useful behavioral context beyond annotations.

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

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

The description is concise yet comprehensive: a few sentences with no wasted words, front-loaded with the core purpose, examples, and return value summary.

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

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

The description fully explains what the tool returns (top-N tools with names, descriptions, schemas, examples), and given the lack of output schema, this is sufficient. It also notes that no second schema lookup is needed.

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

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

Schema description coverage is 100%, and the description adds value by explaining that the 'query' parameter accepts natural language and lists all aliases (task, q, description, search), providing examples in the schema itself.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific use cases (SEC filings, FDA drugs, etc.) and explicitly distinguishes this meta-tool from sibling tools by stating it returns full input schemas for direct calling.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to use this tool vs. other sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds details about data sources (SEC, XBRL, USPTO, news, GLEIF), return fields, and the patent soft-fail (sunset May 2025). Some behaviors like latency or pagination are not mentioned, but it's fairly comprehensive.

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 packs a lot of information into a single paragraph, but is concise given the tool's complexity. Could benefit from structured bullets for return fields, but the current format is clear and front-loaded with examples.

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

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

Despite no output schema, the description enumerates returned data components (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like URI format and sorting. It mentions the patent soft-fail, though some aspects (e.g., number of news items, LEI format) are not specified. Overall, it adequately covers a complex tool.

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

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

Schema coverage is 100% and description adds value: clarifies zero-padded CIK format, restates that names are unsupported, and reiterates the 'resolve_entity' alternative. The enum for 'type' is self-explanatory.

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 ('profile', 'brief', 'research') and clearly states the resource ('US public company') and action ('full cross-source profile in one parallel call'). It distinguishes from sibling tools like resolve_entity (for name resolution) and chained 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?

Explicit guidance: 'ALWAYS PREFER over chaining single-pack... when holistic view', and 'names not supported (use resolve_entity first)'. Also clarifies accepted inputs (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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's mention of 'Delete' is consistent. It adds context about what is deleted (memories) but does not explain behavior for missing keys, though idempotentHint covers that. No contradiction.

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

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

The description is two sentences, front-loaded with purpose, and every sentence adds value. No wasted words.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description sufficiently covers purpose, usage, and pairing with related tools.

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

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

Schema coverage is 100% and the parameter description is clear ('Memory key to delete'). The tool description does not add additional meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb+resource pair. It distinguishes the tool 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?

Provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions complementary 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it fetches the page and extracts specific elements, confirming the open world behavior (openWorldHint=true) and detailing the non-destructive, read-only process 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?

Two sentences: the first states the action and output, the second lists use cases. Every sentence is informative and no extraneous content.

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

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

For a simple tool with 2 parameters, high annotation coverage, and no output schema, the description fully explains the process, output format, and appropriate use cases. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reiterates the default and maximum for 'max_links' but does not add new 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 specific verbs ('Generate', 'Fetches', 'extracts', 'emits') and clearly identifies the resource ('llms.txt file for any URL'). It distinguishes this tool from siblings like 'scan_competitor_ai_presence' by focusing specifically on llms.txt generation.

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

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

Provides explicit use cases: indexing a client's site, drafting your own llms.txt, auditing competitors. Lacks explicit when-not-to-use or direct alternative tool names, but the context is clear enough for an agent to decide.

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: return fields listed, default behavior (active only), and optional parameter. Annotations already cover safety, so description adds value.

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: first states purpose and output, second gives usage guidance. 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 list tool with one optional param, description covers purpose, return fields, and usage. No output schema, so return field list is helpful. Minor ambiguity about 'params' field.

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

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

Schema covers 100% of parameter with description. Description implicitly references default behavior but adds no extra meaning 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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like subscribe/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?

Explicitly says when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies alternatives for adding/canceling.

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, and non-destructive. The description adds the specific return fields (columns, types, row count, etc.), which is useful but does not disclose potential limitations or error conditions. Since annotations cover the safety profile, the description's additional behavioral context is adequate 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 a single sentence that front-loads the purpose and includes specific details. However, it could be slightly more concise by removing redundant phrases like 'schema + metadata' (since both are listed) or by breaking into two sentences. Overall, it is efficient and serves its purpose.

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

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

Given the tool's simplicity (one parameter, no output schema, annotations covering most behavioral traits), the description is sufficiently complete. It explains what the tool returns and how to use it. Adding the output format (e.g., JSON) would be beneficial but is not necessary for a minimal viable description.

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

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

The input schema already describes the 'resource_id' parameter with 100% coverage, providing a description and example. The description adds value by reiterating the example 'tckn-sxa6' and linking it to the dataset context, making it more concrete for an agent. This goes beyond the schema's minimal 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 verb 'Get' and the resource 'Oregon Open Data dataset's schema + metadata', listing specific return fields (columns, types, row count, category, last-updated) and providing an example resource_id. This distinguishes it from sibling tools like 'datasets' (which likely lists datasets) and 'query' (which queries data).

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

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

The description implies usage when metadata or schema for a dataset is needed, but it lacks explicit guidance on when to use this tool versus alternatives. There are no exclusions, prerequisites, or when-not-to-use indications, so an agent would have to infer context from the description alone.

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

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

Annotations are all false, so the description carries the burden. It provides additional behavioral context: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. 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 concise with two main sentences plus a brief expansion. It is front-loaded with the core purpose and uses bullet-like structure via the breakdown of feedback types. Could be slightly more streamlined, but it's effective.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers the essential aspects: purpose, usage context, rate limits, and quota implications. It is complete enough 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 coverage is 100%, so baseline is 3. The description adds value beyond the schema by advising users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts, which clarifies proper usage.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resources, and the description distinguishes it from sibling tools like query or deep_research.

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

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

Explicitly states when to use the tool (for bugs, features, data gaps, praise) and provides guidance on what not to do (don't paste end-user prompts). Also mentions rate limits and that it's free, giving clear usage boundaries.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral details: data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and self-aggregating nature. No contradiction with annotations.

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

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

Two sentences with a bullet list of use cases. Every sentence adds value, is front-loaded with main action, and no fluff. Perfectly sized for quick comprehension.

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 param and no output schema, the description covers return values, use cases, data source, caching, and privacy. It could optionally mention output format, but it's sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with one parameter (window) having enum and description. The description enhances this by explaining the effect of shorter vs longer windows and default (24h), adding value beyond the schema.

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

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

The description explicitly states the tool returns 'top tools, top packs, and total call volume' over a recent window, with specific verb 'returns' and resource 'trending data'. It clearly distinguishes from sibling tools like ask_pipeworx (for querying) and discover_tools (for exploration).

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 lists three concrete use cases (discovering hot data, confirming canonical choice, seeing alignment), providing clear context for when to use. However, it does not explicitly mention when NOT to use or name specific alternatives, though the sibling list implies differentiation.

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 extensive behavioral details beyond the annotations, such as the internal logic (monotonicity checks, partition_sum), semantic anchor for similarity (≥0.30 Jaccard), partition filter (placeholder detection), fill check against live CLOB depth, and the output structure. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and appropriately supplemented.

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

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

The description is well-structured with clear sections (REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and contains no wasted words. However, it is quite lengthy due to the detailed technical explanations, which is justified given the tool's complexity but slightly impacts 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 tool's complexity (two modes, multiple checks, no output schema), the description is remarkably complete. It covers all necessary aspects: input requirements, internal logic, output structure (opportunities[], partition_check, fill_check), and references to sibling tools for further actions. An AI agent can fully understand how to use this 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%, and the description adds significant value by explaining the semantic difference between the two parameters, providing examples of valid inputs (slugs, URLs, seed questions), and detailing how each parameter affects the tool's behavior and internal processing.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event (single-event) and topic (cross-event) modes with explicit examples of slugs and seed questions, making the purpose highly specific and distinguishable from sibling tools.

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

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

The description explicitly states that one of `event` or `topic` is required, explains when to use each mode (event for a known specific market, topic for cross-event scanning), and provides guidance on prerequisites and limitations (e.g., Jaccard similarity, partition filter). It also references the sibling tool `polymarket_fill_risk` for custom sizing, offering clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral details: caching (1h KV level), output structure with segments and diagnostics, and how knobs affect behavior. There is no contradiction with annotations.

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

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

The description is very verbose, containing detailed model formulas and technical jargon. Although it front-loads the main purpose, the subsequent text is dense and not easily scannable. It would benefit from more concise, structured formatting.

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 covers output structure (by_segment segments, diagnostics), filtering knobs, caching, and even example parameters. For a complex tool with 9 parameters and rich output, this is highly complete.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds some overarching context (e.g., 'tradeable-edge knobs') but does not significantly enhance per-parameter understanding 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb+resource and provides context for its intended use ('what should I bet on today'). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it loses a point.

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 the tool (‘agents discover opportunities’) but provides no explicit guidance on when not to use it or mention of alternative tools. Context signals show there are related tools, but no usage exclusions are 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: history depth bounded by 60-day snapshot TTL, snapshots written on cache-miss, decay from daily closes not intraday. 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 informative and well-structured, breaking down response fields with sub-headers (tracked[], expired[], snapshot_dates[]). It could be slightly shortened without losing meaning, but it maintains 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?

With no output schema, the description thoroughly explains the return format (tracked, expired, snapshot_dates) and relevant limitations (60-day TTL, cache-miss gaps). All aspects of the tool's operation are covered, making it easy for an agent to understand.

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% (both parameters documented). The description adds value by explaining defaults (days=14, window='1wk'), clamping (days clamped 2-30), and the response structure which clarifies parameter impact. This goes beyond the 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 states a specific verb-resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes from sibling tools like polymarket_edges by focusing on temporal behavior rather than raw edge data.

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

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

The description clearly conveys when to use: to understand edge longevity and decay. It contrasts fresh edges vs old ones ('a fresh wide edge and a 3-week-old wide edge are different trades'), providing implicit usage guidance. However, it does not explicitly list alternatives or 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description details the tool's internal behavior: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict' for single-market, and for baskets it lists 'theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk.' This adds significant transparency about what to expect. No contradiction with annotations.

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

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

The description is well-structured with a summary line, mode breakdown, parameter explanation, and usage guidance. It is dense but not excessively verbose; each sentence adds value. However, it could be slightly more concise by combining some repetitive points on return values.

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, no output schema), the description is remarkably complete. It explains all return values for both modes, warns about risks (thin legs, forced directional risk), and provides usage context relative to sibling tools. Without an output schema, the description fully compensates by documenting what the tool returns.

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

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

Although schema coverage is 100%, the description enriches parameter meaning by providing operational context: it explains the two modes ('REQUIRES one of market or event'), gives side defaults and auto-detection logic for baskets, and interprets size_usd differently per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional'). It also includes default values and clamp ranges not in the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and differentiates from siblings by explicitly referencing 'polymarket_arbitrage' and 'polymarket_edges' as tools to use before acting on, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against misuse, explaining that theoretical overround on thin books is not capturable and partial basket fills convert an arb into an unhedged directional position, providing clear context for when not to rely solely on theoretical edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: response structure, safety fields, compatibility warnings (with causes), temporal alignment considerations, and counters for dropped comparisons. 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 well-structured with sections and front-loaded purpose. It is somewhat lengthy but every sentence adds value given the tool's complexity. Could be slightly condensed but remains efficient.

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

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

Given the tool's complexity (two modes, safety fields, lack of output schema), the description is comprehensive. It covers return values, edge cases, compatibility warnings, temporal alignment, and limitations. No output schema exists, so the description fully fills that 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 elaborates on each parameter: topic lists the 10 shortcuts, kalshi_event_ticker and polymarket_event_slug are explained with examples and override behavior. The description adds semantic meaning beyond schema by explaining the two modes and how parameters interact.

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, specifying the two modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 the tool (to compare prices across venues) and provides guidance on when not to rely on it (compatibility warnings indicate non-equivalent bet shapes or unrelated events). It implicitly advises caution but does not explicitly name alternative tools for different use cases.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover safety. The description adds behavioral details: it returns matching rows as JSON and implies pagination via limit/offset parameters, adding value beyond annotations.

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

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

The description is a single, well-structured sentence with no wasted words. It front-loads the core purpose, provides an example, and enumerates key parameters efficiently, earning every character.

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 (7 parameters, SoQL syntax) and the fact that no output schema exists, the description is remarkably complete. It clarifies the SoQL clause syntax, mentions return format (JSON), and hints at default limit, covering all essential aspects for correct 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?

With 100% schema coverage, baseline is 3. The description adds significant meaning by explaining that SoQL clauses should be provided without the leading '$' and gives concrete examples for where, select, and order, enhancing understanding beyond the schema's parameter 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 action ('Run a Socrata SoQL query') and the resource ('Oregon Open Data dataset by resource_id'), with a concrete example. It distinguishes from sibling tools like 'datasets' which return metadata rather than query results.

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

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

While not explicitly stating when not to use, the description provides clear context: use this tool when you need to query data from a dataset by resource_id. The parenthetical hint 'from datasets' subtly guides users to first obtain the resource_id, making usage appropriate.

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

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

Annotations already cover readOnly and idempotent hints; description adds scoping detail (identifier-based) and behavior of omitting key, but no new safety-related 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?

Concise single paragraph with front-loaded action, no redundant words, efficient structure.

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 with 1 param, no output schema, and rich annotations, description covers purpose, usage, scoping, and relationships completely.

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

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

Schema covers parameter fully; description adds concrete examples of what keys represent (ticker, address, notes), providing extra meaning 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?

Clearly states verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools remember and forget.

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

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

Provides explicit use cases (e.g., 'the user's target ticker, an address') and pairs with remember/forget, but does not explicitly state when not to use.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context by explaining that setting mark_read:true flags returned events as read, affecting subsequent calls. 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 concise with only 4 sentences, each serving a purpose: overall action, return details, parameter usage, and polling/alternative access. No redundancy.

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

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

Given 5 optional parameters and no output schema, the description adequately explains what is returned (source, citation_uri, raw payload), the effect of mark_read, and provides an alternative access method. It is complete for its 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 parameter descriptions. The description adds value by providing an example for 'type' (e.g., 'sec_8k') and clarifying the effect of 'mark_read'. This surpasses the baseline of 3.

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

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

The description clearly states the tool pulls fired events from a subscription feed and specifies the return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools by focusing on recent alerts with specific filtering capabilities.

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

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

The description implies usage for retrieving recent alerts and mentions polling works fine. It also notes an alternative access method via GET endpoint. However, it does not explicitly state when to use this tool over siblings or 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 indicate read-only, idempotent, non-destructive. The description adds crucial context: parallel fan-out to multiple sources, fallback logic, API sunset note for patents, date format options, and return structure (grouped by source + citation URIs), significantly enhancing transparency.

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

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

The description is a dense single paragraph packing a lot of information without being overly verbose. However, it could be slightly more structured (e.g., bullet points for sources) to improve scanability. Still, every sentence is valuable and front-loaded.

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

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

Given the tool's complexity (multiple sources, fallbacks, date parsing), the description is complete. It covers prerequisites, behavior, return structure (changes grouped by source, total_changes count, citation URIs), and when to use alternatives, all without 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?

Schema covers 100% parameters with descriptions, but the description adds meaningful detail: explains 'since' formats (ISO/relative with examples like '30d'), clarifies 'value' accepts ticker or CIK, and notes 'type' is currently only 'company'. This goes beyond schema.

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

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

The description clearly states the tool provides a change feed for a company, listing specific data sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from the sibling tool 'entity_profile' which provides static profiles.

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

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

Includes example queries, explicit guidance on when to use the sibling tool instead, and explains fallback behavior (GDELT preferred, GNews on rate limit/5xx), giving clear context for correct invocation.

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

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

Discloses key behavioral traits: key-value pair storage scoped by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). These add value beyond annotations. No contradictions with annotations found.

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 with 4 sentences, front-loading the main action, then usage, technical details, and complementary tools. No extraneous information.

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

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

For a simple key-value write tool, the description covers purpose, usage, persistence, and pairing with recall/forget. It does not mention error cases or size limits, but overall is sufficiently complete.

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

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

Schema has 100% coverage with examples. The description adds context that key is a label and value is the finding, and explains the memory system. This provides moderate additional meaning beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses a specific verb ('Save') and resource ('data for reuse'), and distinguishes itself from siblings like 'recall' and 'forget' by explicitly pairing with 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?

Provides clear guidance on when to use: 'when you discover something worth carrying forward'. Also explains persistence differences for authenticated vs anonymous users. Though it doesn't explicitly state when not to use, the context implies temporary data doesn't need this 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavior: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also explains exactly what fields are returned for each type, exceeding the annotation coverage.

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

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

The description is front-loaded with example queries and core purpose. Every sentence adds value, covering usage, return format, and internal behavior without redundancy. It is well-structured and concise given the detail provided.

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 covers return values for both types and mentions the internal cascade. Minor gap: it doesn't address disambiguation or error handling for ambiguous inputs. But overall, it provides sufficient context for an AI agent to use the tool effectively.

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

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

Schema coverage is 100%, but the description significantly enhances meaning with examples (e.g., ticker, CIK, company name for company; brand/generic names for drug) and explains return values per type, which the schema does not fully capture.

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: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries and specifies the supported types (company, drug) with detailed return values, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear context. It also details what each type returns. However, it does not explicitly state when not to use it or mention alternative tools for comparison, though the primacy hint is strong.

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 idempotent, read-only, non-destructive behavior. The description adds behavioral detail: it iteratively probes each entity via ai_visibility_check, ranks results, and surfaces relative standing. No contradictions exist. It provides useful process-level transparency beyond the annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, methodology, use case, return format. No 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 that there is no output schema, the description compensates by summarizing the return format (ranked list with score, confidence, signal density). Parameters are well-covered by the schema. The tool's complexity is moderate, and the description provides sufficient context for an agent to use it correctly. Minor omission: the entity count constraint (2-8) is in the schema but not in the description, which is acceptable.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context: the first entity in the array is treated as the 'subject' for narrative purposes, and the context parameter is described as disambiguating common names. This goes beyond the schema's field-level 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It includes a concrete use case ('does Claude know about us as well as our competitors?'), which precisely defines the resource and action, distinguishing it from siblings like the single-entity ai_visibility_check.

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 frames the tool as useful for competitive AI-marketing audits, implying when it should be used (multi-entity comparison). While it does not explicitly mention when not to use it or list alternatives, the context of sibling tools makes the use case clear. A slight gap remains in not contrasting with single-entity probes.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds important behavioral details: partial failures degrade gracefully, bundlephobia may take 5-30s on first measurement, and sources_failed field indicates timeouts. 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 a single paragraph that front-loads the main purpose. It is concise but contains multiple sentences; slight restructuring could improve readability.

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 adequately lists the return fields (summary block, advisories, links, alternatives) and explains behavior on partial failure, covering the necessary context for an agent to use the tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add new meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states it's a composite check for deciding whether to add an npm package, specifying the services queried and the ecosystem. It is distinct from sibling tools like scan_competitor_ai_presence.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also notes that the tool is NPM-only and suggests alternatives for other ecosystems.

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, idempotent, non-destructive. Description adds embedding details, 200K char cap, truncation and flagging, and return format (offsets, similarity scores) — far beyond annotations.

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

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

Description is well-structured: core purpose, usage guidance, pairing, technical details. Efficient but a bit dense; could be slightly more concise. Still strong.

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 specifies return type (top-N passages with offsets and scores) and truncation behavior. Complete for a 3-param tool with clear purpose.

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 good descriptions. Description adds minimal extra meaning beyond schema (e.g., natural-language examples for query). 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?

Description clearly states verb 'semantic search' and resource 'inside a fetched record'. It distinguishes from sibling tools by naming ask_pipeworx_grounded, and gives concrete examples (SEC 10-K, article).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded', providing when-to-use and an alternative.

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?

Disclosures go beyond annotations: requires OAuth account, sms 10/day cap, phone verification, webhook auto-disable after 10 failures, and webhook signing secret returned once. Annotations indicate idempotentHint true, but description adds behavioral specifics. No contradiction.

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

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

Dense but efficient; every sentence adds value. Front-loaded with core action. Slightly lengthy but justified by complexity. Could be slightly trimmed without loss, but overall well-structured.

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

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

Returns subscription id, prerequisites, type-specific examples, delivery details, and important caveats (webhook secret once, auto-disable). No output schema but description covers return value adequately. Complete for a complex subscription tool.

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

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

Schema coverage is 100%, and description adds significant meaning: for 'sec_8k' explains items codes like '5.02' = officer change; for delivery details provides constraints and examples. Enhances schema with practical usage context.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Specific verb+resource, and distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by detailing subscription creation with types and delivery channels.

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

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

Provides explicit context: requires Pipeworx OAuth account, anonymous/BYO cannot persist. Mentions supported types and delivery options. Implicitly contrasts with 'recent_alerts' for pulling feed, but does not explicitly state when not to use or list alternatives. Clear guidance overall.

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, etc. The description adds value by detailing the output structure (categorized examples with tool+argument shape) and the effect of omitting or specifying the topic. No contradiction with annotations.

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

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

The description is front-loaded with key purpose and usage guidance. It is thorough but slightly lengthy; a minor trimming would optimize 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?

Given no output schema, the description fully explains what is returned (category-bucketed examples with exact tool calls). It covers the optional parameter, the scope of the catalog, and the tool's role as an onboarding resource.

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 has 100% coverage for a single parameter. The description enriches it by listing concrete topic values (finance, pharma, etc.) and explaining that omitting it gives a full spread. This exceeds what the schema alone 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 explicitly states the tool is 'the onboarding entry point for an agent that just connected' and lists triggers like 'what can I ask Pipeworx?' It clearly distinguishes from siblings by positioning it as a first-use discovery tool.

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

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

The description advises using it 'FIRST' when uncertain about capabilities and to learn meta-tool calls. It also explains the optional topic parameter. However, it does not explicitly state when NOT to use it, which would make it a 5.

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

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

Describes that rows are deactivated (not deleted), adding value beyond annotations. No contradiction with annotations.

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

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

Two sentences, front-loaded with action, 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?

Complete for a simple tool with one parameter and no output schema; covers behavior, ownership, and retention of history.

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

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

Schema covers 100% of parameters, and description adds context that id comes from subscribe, enhancing 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?

Clearly states the action ('Cancel a subscription by id') and enforces ownership, distinguishing from sibling tools like subscribe 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?

Ownership enforcement implies when not to use, but lacks explicit alternatives or scenarios. Still clear context for 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, idempotentHint, and non-destructive nature. The description adds substantial behavioral context: it uses SEC EDGAR + XBRL, returns a verdict with structured form, actual value with pipeworx:// citation, and percent delta, and explains it replaces multiple sequential calls. No contradictions.

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

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

The description is front-loaded with examples and purpose, then provides usage guidance, scope, and return details. It is somewhat lengthy but well-structured and each sentence adds value. 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 a single parameter and no output schema, the description covers the tool's behavior thoroughly: domain (company-financial claims), data source (SEC EDGAR+XBRL), return values (verdict, structured form, citation, delta), and efficiency benefit (replaces multiple calls). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, with a clear description for the 'claim' parameter. The description reinforces this with additional examples ('Apple's FY2024 revenue was $400 billion'), adding extra semantics beyond the schema baseline, but schema already does a good job.

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. It provides specific example phrases like 'Is it true that...' and 'fact check', and distinguishes itself from siblings by noting it replaces 4-6 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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also narrows the scope to company-financial claims for public US companies, but does not provide explicit when-not-to-use scenarios or alternatives.

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