Tech Feeds

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds valuable context: default model, cost implications (BYO key), and return format (per-model fields + combined view). This goes beyond annotations to inform agent decision-making.

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 well-structured: purpose first, then details on models and API key, then use cases. Every sentence adds essential information with no redundancy.

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

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

Given the tool's complexity (4 parameters, no output schema), the description covers purpose, usage, parameters, and return format adequately. It provides enough detail for an agent to select and invoke the tool correctly, especially with annotations filling in behavioral gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by clarifying default model behavior, when _apiKey is needed, and how 'context' helps disambiguate. It also explains return structure, though that's not parameter-specific.

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 ('probe', 'score') and clearly identifies the resource (LLMs) and output (visibility score 0-100). It distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on LLM knowledge probing, providing a unique value proposition.

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 explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key for Anthropic. However, it does not mention when not to use this tool or suggest alternatives among siblings, which would earn a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds context about the tool routing to many sources, returning structured answers with citations, and being fast with one call. No contradictions, and the additional context is helpful 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 lengthy but front-loaded with the key instruction to prefer over web search. Every sentence adds unique value, covering purpose, examples, and differentiation from siblings. Could be slightly more concise but 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 complexity (6 parameters, many siblings, no output schema), the description fully covers when to use, how it works, alternatives, and examples. It addresses common use cases and states availability (works on every tier), making it complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'question' parameter accepts multiple aliases (query, q, prompt, etc.) and provides numerous examples, going beyond the schema's description.

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

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

The description clearly states the tool routes questions to authoritative sources and returns structured answers with citations. It provides specific examples and contrasts with siblings like web search and ask_pipeworx_grounded, making the purpose unambiguous.

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

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

Explicitly instructs to prefer over web search for factual queries and provides clear when-not-to-use guidelines. Names sibling tools (ask_pipeworx_grounded, deep_research) for alternative use cases and lists example commands.

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 behavioral context like refusal reasons, extraction logic, and cost implication, which goes beyond the annotations.

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

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

The description is informative and well-structured, but is slightly long. It front-loads the key purpose and use cases efficiently.

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 explicitly details the return format including success and refusal types, making it complete for a high-stakes tool with many siblings.

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

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

Schema coverage is 100% and the description merely confirms that the question parameter accepts various aliases. It adds no new 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 it is a 'Hallucination-resistant answer mode for high-stakes reads,' specifies the routing process, and distinguishes it from ask_pipeworx by highlighting the extraction step.

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

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

Explicitly states when to use ('when an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including cost trade-off.

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 safe read-only behavior but description adds deep behavioral details: fan-out mechanism, response shapes, short-circuit paths, cancellation rule parsing, fallback handling for news, and tradeability warnings. 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?

Well-structured with clear section headings, but could be slightly more concise. Some redundancy in explaining low-confidence paths and closed markets. However, given complexity, the length is mostly justified.

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

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

Covers all aspects: input options, classification, fan-out examples, response shapes, edge cases (low confidence, closed, illiquid, resolution risk), and parameter details. No output schema but description compensates fully. Complete for a complex research 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?

All three parameters have schema descriptions, but the tool description adds substantial context: market input formats (slug, URL, text), depth levels with fan-out examples, and include_raw usage with size implications. Goes well beyond schema documentation.

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 Polymarket bets by pulling Pipeworx data, with specific verb 'research' and resource 'Polymarket bet'. It distinguishes from siblings like 'ask_pipeworx' by being focused on betting decisions.

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 given ('should I bet on X', etc.) plus extensive guidance on inspecting match confidence, handling low-confidence matches, closed markets, and resolution-rule risks. Provides when-not-to-trust results and parameter usage advice.

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. Description adds rich behavioral details: sources (SEC EDGAR/XBRL, FAERS), data points (revenue, net income, etc.), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction.

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

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

Description is a single paragraph but front-loaded with example queries. Every sentence is informative, though slightly dense. Could be slightly more structured, but efficient overall.

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

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

Despite no output schema, description covers return values (paired data, citation URIs), sorting methodology, and data sources for both entity types. Completely addresses the complexity of 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%. Description adds meaning beyond schema: for type, it specifies tickers/CIKs for company vs names for drug; provides examples. Enhances understanding without redundancy.

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

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

Description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one call, with explicit example queries and entity-specific behavior. Distinguishes from sibling tools like 'entity_profile' by aggregating multiple entities.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, noting it replaces 8–15 sequential lookups. Provides clear context for when to use.

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

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

The description adds substantial behavioral context beyond the annotations. It discloses account requirements, paid plan needed for 'thorough' depth, the decomposition and parallel routing process, the structure of the findings packet (evidence, confidence, source, citation, gaps), the 15-60s expected runtime, and the limitation that it returns empty gaps for topics absent from the structured catalog. This transparency is comprehensive and consistent with the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is relatively long but each sentence serves a purpose: prerequisites, core functionality, process, use cases, limitations, and performance. Information is front-loaded (account requirement first). Minor redundancy (e.g., 'in ONE call' and 'decomposes your question into focused facets') could be trimmed, but overall it is well-structured and efficient for the complexity of the tool.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It describes the return format in detail: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers prerequisites, typical use cases, and performance expectations. No significant gaps remain 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 the schema already documents both parameters. The description adds value by explaining the depth enum in context of paid plans ('depth: 'thorough' needs a paid plan') and reaffirms that question decomposition is the point. While the description does not add new parameter details beyond the schema, it provides operational context that aids correct 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 specifies the tool's action: 'Grounded multi-source research across Pipeworx's 1122 STRUCTURED data sources... in ONE call'. It distinguishes from siblings by stating it is not open-web search and provides explicit comparisons to ask_pipeworx. The verb 'research' and the resource 'structured data sources' are specific, and the description differentiates from similar 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 when to use this tool vs alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... topics, prefer ask_pipeworx'. It also notes that deep_research returns empty gaps for topics not in its catalog, providing clear guidance on when it is 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context. No contradictions, and it enriches understanding 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 and front-loaded, starting with purpose then usage and details. Every sentence serves a purpose without redundancy, making it efficient and easy to parse.

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

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

Given the tool's complexity and no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and full schemas with curated examples. It covers all necessary context for a discovery tool.

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

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

The input schema has 100% coverage with descriptions for all parameters, including aliases. The description adds value by providing examples of natural language queries and stating default/max limits for 'limit.' This goes beyond 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 clearly states the tool's purpose: to find tools by describing the data or task. It lists specific domains (SEC filings, financials, etc.) and explains that it returns top-N relevant tools with schemas, making it distinct from sibling tools like search_within or list_feeds.

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 when you need to browse, search, look up, or discover what tools exist for' and provides examples. It also advises 'Call this FIRST when you have many tools available and want to see the option set,' giving clear guidance on when to use this tool versus 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?

Despite comprehensive annotations (readOnly, idempotent, openWorld), the description adds significant behavioral detail: parallel fan-out across sources, specific data returned, patent source sunset and soft-fail behavior, and fallback mechanisms (GDELT→GNews). No contradictions with annotations.

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

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

The description is informative but slightly lengthy; it front-loads example queries and key guidance, then details output. Each sentence adds value, but could be streamlined by grouping related details. Still effective for agent understanding.

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

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

No output schema, so description must cover return values; it lists exact fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and explains data sources. However, it omits specific substructure of recent_filings or fundamentals, which may require agent inference. Adequate but not exhaustive.

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 includes descriptions, but the description adds value by specifying exact input formats (ticker, zero-padded CIK) and clarifying that type is restricted to 'company'. This aids correct parameter selection beyond schema alone.

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

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

The description clearly states the tool provides a holistic profile of US public companies, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields. It distinguishes from siblings by recommending it over chaining lookups and contrasting with resolve_entity for name resolution.

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 to use when user wants a holistic view and to avoid chaining single-pack queries. It also states when not to use (names not supported) and directs to resolve_entity as an alternative. Provides clear guidance on input format (ticker or CIK).

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds significant behavioral details: 'CF-robust' with direct fetch and proxy fallback if blocked, and normalization of output. No contradictions with annotations.

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

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

Two sentences: first states purpose, second adds robustness and guidance. No unnecessary words, front-loaded with 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?

Given full schema coverage and annotations, description adds the fallback and normalization details. It suggests using list_feeds first, which is helpful context. No need to describe return values since no output schema exists.

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 each parameter is described in the schema. Description does not add additional meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool fetches and normalizes RSS/Atom/RDF feeds by URL. It mentions specific feed types and normalization. However, it does not explicitly distinguish from sibling 'read_feed', which could be a similar operation on subscribed feeds.

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

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

Explicitly advises 'Use list_feeds first for curated sources', providing context for when to use this tool versus listing feeds. Does not mention other alternatives like read_feed, but guidance is helpful.

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

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

Description aligns with annotations (destructive, idempotent) and adds context about clearing sensitive data. No contradictions, but could mention if confirmation is needed.

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

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

Two concise sentences, front-loaded with action and resource, then usage guidelines. Every sentence adds value, 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?

For a simple tool with one parameter and no output schema, the description covers all needed context: purpose, usage, and behavioral hints.

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?

Single parameter 'key' is well described in schema (100% coverage). Description adds no additional semantics beyond schema, meeting baseline.

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

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

The description clearly states the action (delete) and resource (previously stored memory by key), effectively distinguishing from siblings like '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?

Explicitly states when to use (stale context, task done, clear sensitive data) and suggests pairing with siblings, providing excellent guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by explaining the process of fetching the page, extracting title/description/key links, and emitting standard llms.txt format. It does not contradict annotations.

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

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

The description is concise with no unnecessary words. It is structured with a clear first sentence stating purpose, followed by process, output, and use cases. Every sentence adds value, making it easy for an agent to quickly understand the tool.

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

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

Given the tool's simplicity, the description is complete. It covers what it does, how it works, output format, and use cases. The schema and annotations cover the remaining details, so no additional information is needed for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents both parameters (url and max_links) with their descriptions. The tool description does not add new information about parameter behavior beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the target users (AI crawlers) and the output format. While it doesn't explicitly differentiate from siblings, its function is distinct and well-defined.

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 lists use cases: getting a client's site indexed, drafting your own project, or auditing competitors. It provides clear context for when to use the tool, though it does not mention when not to use or explicitly name alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behaviors. The description adds context about the output (id, title, category, source) and filtering options. No hidden behaviors or contradictions are present.

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, directly stating the tool's purpose and optional filters, and pointing to a sibling tool. Every sentence is necessary and well-placed, with no redundant 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 list tool with optional filters and no output schema, the description covers all needed aspects: what is listed (feeds with fields), how to filter, and how to proceed to read a feed. It is fully adequate given 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% for both parameters, so the description does not add new information beyond what the schema provides. The description repeats the filtering concept, but offers no additional semantic detail about parameters.

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

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

The description clearly states it lists curated technology feeds with specific fields (id, title, category, source), and distinguishes from read_feed by saying 'Pass an id to read_feed.' The verb 'list' combined with the resource 'curated technology feeds' is specific and unambiguous.

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

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

The description mentions optional filtering by category or keyword, and explicitly points to the sibling tool read_feed for reading a specific feed. However, it does not provide guidance on when to use list_feeds vs other listing tools like list_subscriptions, which are listed as siblings.

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

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

Annotations already indicate readOnly and non-destructive. Description adds value by specifying return fields and the effect of the include_inactive parameter. No contradictions.

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

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

Two sentences: first states function, second provides usage context. No redundant information.

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

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

Given the tool's simplicity (one optional boolean parameter, no output schema) and rich annotations, the description fully addresses purpose, usage, and behavior.

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

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

Schema coverage is 100% with full parameter description. Description mentions the parameter only implicitly ('active'), adding 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?

The description explicitly states the tool lists the caller's active subscriptions and enumerates returned fields. It clearly distinguishes from sibling tools 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?

Provides explicit guidance on when to use: to review monitoring before adding more or to find an id to cancel. Lacks explicit exclusion of when not to use, 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?

The description reveals rate limits (5 per identifier per day), that it's free and doesn't count against quota, and how feedback affects roadmap. Annotations are all false, so the description adds substantial behavioral context beyond what annotations provide.

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

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

The description is a single paragraph but covers all necessary aspects efficiently. It is front-loaded with the main action and logically flows to usage guidelines and behavioral notes. While clear, it could be slightly more structured (e.g., bullet points) without losing 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?

The description is complete for a feedback tool with no output schema. It explains input constraints, rate limits, and purpose, leaving no gaps in understanding how 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?

With 100% schema coverage, the description still adds value by explaining the 'type' enum values in detail and giving examples for 'context' fields (pack slug, tool name, vertical). It also instructs to describe issues in terms of tools/packs, adding layer of usage semantics.

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

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

The description clearly states the tool's purpose: to provide feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes the tool from siblings by its unique function of submitting feedback, not querying or manipulating 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 explicitly tells when to use the tool for each feedback type (bug, feature, data_gap, praise) and what not to do (e.g., 'don't paste the end-user's prompt'). This provides clear guidance for appropriate 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 data source (CF analytics-engine), no PII, caching behavior (5min-1h), and idempotent/non-destructive nature 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?

Five sentences with clear front-loading: first sentence states purpose, then use cases, then technical details. Every sentence adds value without redundancy.

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

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

Completely describes a simple read tool: what it returns, how it works, when to use, and data handling. No output schema needed given the simplicity; annotations cover safety.

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?

Adds meaning to the 'window' parameter by explaining trade-offs between short and long windows. Schema description coverage is 100%, but tool description enriches 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 it returns top tools, packs, and call volume over recent windows. Distinguishes itself from sibling tools by focusing on trending usage data derived from analytics.

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

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

Lists three specific use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent needs. Provides clear context for when to use 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 mark the tool as readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond by detailing internal algorithms (monotonicity, partition check, Jaccard similarity filter, placeholder filter, fill check) and explaining when a trade is not realizable. This adds significant behavioral context beyond the structured 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?

While the description is long, it is well-organized into clear sections (REQUIRES, event mode, topic mode, SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK). Every sentence adds necessary information, and the structure aids readability. It is appropriately sized for a complex tool.

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

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

Given there is no output schema, the description fully explains the response structure (opportunities array with fields, partition_check object) and covers edge cases (realizable_edge_pp ≤ 0, placeholder fraction >20%). With only 2 parameters (both fully described) and no nested objects, the description leaves no gaps.

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

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

Schema description coverage is 100%; both parameters already have descriptions. The description adds additional value by clarifying the difference between event and topic modes, recommending event for specific markets, and explaining acceptable input formats (slugs, URLs, seed questions). This enriches the meaning beyond the raw schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with two distinct modes (event and topic) that are clearly explained. While sibling tool names like polymarket_edges and polymarket_fill_risk exist, the description's specificity about its unique analysis method sufficiently differentiates it.

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

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

Explicit guidance is provided: 'REQUIRES one of event or topic — call with no args fails'. It recommends event mode for specific markets and topic mode for cross-event scanning, and even hints to use polymarket_fill_risk for custom sizing. This is exemplary usage direction.

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 is extremely detailed about behavioral traits: it explains the three model families, how edge is computed net of slippage, Kelly sizing, liquidity and spread filters, 24h move warning, caching at KV level for 1h, and even diagnostics for empty segments. This goes far beyond the annotations (readOnly, openWorld, idempotent) which are already clear.

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

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

The description is long but well-structured with numbered segments and clear sections. It front-loads the purpose and then dives into details. Some technical details (e.g., exact alpha values per sport) could be trimmed, but overall it earns its length by providing actionable information for the agent.

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

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

Given the complexity (9 params, no output schema), the description comprehensively covers what the tool returns: by_segment with three sub-segments, fed_candidates, and _diagnostics. It explains how each segment is computed and what fields each opportunity carries. The lack of an output schema is compensated by this detailed narrative, though a structured summary could help.

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

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

Schema coverage is 100% with all 9 parameters documented. The description adds value by explaining how parameters like min_liquidity and max_spread_pp act as 'tradeable-edge' filters and how min_partition_leg_kelly applies to per-leg Kelly. While the schema already has good descriptions, the description enhances understanding of their interaction.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings by explicitly being built for 'what should I bet on today' and mentions three segments, which are unique to this 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 explains when to use (for discovering opportunities without paging) and provides context for tradeable-edge knobs and Fed bets. However, it does not explicitly say when not to use it versus siblings like polymarket_arbitrage or polymarket_edge_tracker, though the detailed breakdown implies its specific use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it reads from daily snapshots, computes trends and decay, handles expired entries, and mentions limits (60-day TTL, daily closes). No contradiction with annotations; description enhances 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 well-structured with sections: purpose, response fields, limits. It is somewhat lengthy but all information is relevant. Could be slightly more concise, but each sentence adds value.

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

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

For a tool with no output schema, the description fully explains the return value (tracked, expired, snapshot_dates) and their significance. It covers limitations and data sources, making the tool understandable and usable without additional documentation.

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

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

Schema description coverage is 100% with clear defaults. The description adds meaning by explaining 'days' as lookback and 'window' as snapshot family, and details the response structure which relates to parameters. This provides value beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It specifies the resource (polymarket_edges snapshots) and verb (analyze persistence/decay), distinguishing it from siblings like polymarket_edges which provide raw snapshots.

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

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

The description provides clear context for use: analyzing edge persistence over time, contrasting fresh vs. aged edges. It implicitly suggests using polymarket_edges for raw snapshots but does not explicitly list alternatives or state when not to use this tool. The usage context is well defined, but lacks explicit when-not-to-use guidance.

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

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

Annotations clearly indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details: 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, etc.), and explains the verdict. 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 verbose but well-structured with clear sections (SINGLE-MARKET, BASKET, usage note). It front-loads the core purpose. Some redundancy could be trimmed, but the organization aids 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?

Given the tool's complexity (two modes, multiple outputs, risk warnings), the description covers all necessary aspects: explains inputs, outputs for each mode, risk of partial fills, and provides practical usage context. Without an output schema, the description fully informs the agent.

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

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

Schema description coverage is 100% with all parameters described. The description adds extra meaning beyond schema, e.g., explaining size_usd interpretation in single-market vs basket modes and side default logic ('auto if not provided'). Provides context and constraints (clamp range).

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 single-market and basket modes with specific actions and outputs, and is clearly differentiated from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains the rationale (theoretical overround not capturable, partial basket fills create unhedged directional risk) and provides context for alternatives.

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

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

Beyond annotations (readOnlyHint, etc.), the description extensively covers behavioral traits: compatibility_warning conditions, temporal alignment, skipped_cross counters, and the rarity of real spreads. It adds substantial context.

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

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

The description is front-loaded with the main purpose and contains detailed but valuable information. It is slightly long but every sentence earns its place; no 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?

Despite no output schema, the description fully explains the response structure, safety fields, and edge cases. It is comprehensive given 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%, so baseline is 3. The description adds meaning by explaining the two modes (topic vs explicit), providing examples, and detailing response fields like compatibility_warning and temporal_alignment.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly defining the tool's specific verb+resource. 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 two modes (topic shortcuts and explicit tickers) and details when compatibility warnings arise, guiding appropriate use. However, it does not explicitly contrast with similar siblings like polymarket_arbitrage.

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 the tool is read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations, such as the return format (title, link, published, summary) and optional filtering capability. However, it does not disclose edge cases like invalid feed ids or rate limits.

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 wasted words. The first sentence states the main purpose and source of the id, the second adds optional filtering. Information is front-loaded and efficiently 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?

The description covers the core functionality, required parameter, and return fields. However, it does not mention pagination behavior, ordering, or error handling for invalid ids, which would make it more 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 marginal value by specifying the feed parameter's source (list_feeds) and clarifying the query parameter's scope (title/summary), but the schema already provides adequate 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: reading a curated technology feed by its id, returning normalized items with specific fields, and optional keyword filtering. It also links to list_feeds for obtaining the id, distinguishing it from sibling tools like fetch_feed or list_feeds.

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

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

The description provides context on how to use the tool (requires a feed id from list_feeds) and mentions optional filtering, but does not explicitly state when not to use it or compare it to alternatives like fetch_feed.

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 all relevant behaviors: retrieval, listing all keys when no key is provided, scoping to user identifier, and pairing with remember/forget. It adds value beyond annotations which already indicate read-only and idempotent behavior.

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

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

The description is three concise sentences, each adding unique value. It front-loads the main action and provides necessary details without redundancy.

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

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

For a simple tool with a single parameter and good annotations, the description covers purpose, usage, behavior, parameter semantics, and scoping. It provides complete guidance 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?

The description clarifies the key parameter is optional and explains the behavior when omitted (list all keys), adding meaning beyond the schema's description. Schema coverage is 100%, but the description enhances understanding.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted. It uses specific verbs and resources, and distinguishes itself from siblings by mentioning pairing with 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?

The description provides explicit context for when to use the tool (look up previously stored context) and implies it should not be used for deriving new information. It mentions scoping and pairing but does not explicitly list alternative tools for similar tasks.

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

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

Adds significant context beyond annotations: discloses mark_read state mutation, notes polling safety, and describes returned payload. Aligns with readOnlyHint and idempotentHint, and clarifies openWorldHint with external URL.

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

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

Four well-structured sentences, front-loaded with purpose, no unnecessary words. Each sentence adds unique value.

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

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

Covers return format, filtering, mark_read, and polling; no output schema so description compensates. Missing pagination details, but limit parameter is in 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% of parameters; description adds valuable examples (type='sec_8k', since ISO timestamp) and explains mark_read/unread_only semantics beyond schema descriptions.

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

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

Description clearly states verb 'Pull' and resource 'fired events from your subscription feed', specifies returned fields (source, citation_uri, payload), and highlights filter options. Distinguished from siblings by focusing on recent alerts with mark_read and polling support.

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 usage hints like filtering by type/since and setting mark_read, but does not explicitly differentiate from sibling tools such as fetch_feed or read_feed. Lacks when-not-to-use advice.

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; description adds rich behavioral context: fans out in one parallel call, fallback mechanism, USPTO soft-fail, relative date acceptance, return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

Description is fairly long but front-loaded with query examples and each sentence adds value. Could be slightly more concise, but no wasted words. Structure follows logical flow: usage, behavior, parameters, return, alternatives.

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

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

Given no output schema, description adequately explains return format (changes[] grouped by source, total_changes, citation URIs). Covers all key aspects: purpose, multiple sources, parameter details, fallback, alternatives. Complete for an agent to use correctly.

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

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

Schema covers all parameters (100% coverage). Description adds practical usage examples for 'since' (ISO and relative) and recommends typical monitoring window. Also clarifies value can be ticker or CIK with examples. Adds value beyond schema.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It uses specific verbs and examples like 'What's new with X', distinguishing it from sibling tool entity_profile.

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

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

Explicit guidance on when to use this tool vs. entity_profile: 'Use entity_profile instead when you want the static profile...'. Also specifies preference order (GDELT before GNews) and provides typical relative shorthand suggestions ('30d', '1m').

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

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

Description discloses key behavioral traits beyond annotations: key-value pair storage scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour retention for anonymous), and pairing with recall/forget. Annotations already provide idempotentHint=true, destructiveHint=false, and description adds useful context about session behavior. No contradiction.

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

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

Description is a well-structured paragraph that front-loads the primary purpose, then explains when to use, how storage works, and pairing with siblings. Every sentence is meaningful with 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 the simplicity of the tool (2 params, no output schema, no nested objects), the description covers all necessary aspects: purpose, usage context, behavioral details, and parameters. Annotations further support the behavioral profile.

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

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

Schema already provides clear descriptions for both key and value (100% coverage). Description adds value by giving concrete examples of typical key uses (subject_property, target_ticker, user_preference) and value types (findings, addresses, etc.), which helps the agent understand naming conventions.

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 'Save' and the resource 'data the agent will need to reuse later.' It explicitly distinguishes from sibling tools like recall and forget by mentioning pairing, and provides concrete examples of when to use (resolved ticker, target address, user preference).

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 when you discover something worth carrying forward' and pairs with 'recall to retrieve later, forget to delete', providing clear context for when to use this tool versus alternatives. It also notes session behavior for anonymous vs authenticated users.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses internal cascading, auto-disambiguation, specific return fields per type, and citation URIs. This gives the agent a thorough understanding of tool behavior.

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

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

The description is well-structured with a purpose statement, example queries, and per-type details. It is front-loaded with the key usage guideline. While a bit verbose, each sentence adds value.

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

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

Given the lack of an output schema and moderate complexity (two entity types, multiple input formats), the description covers all essential aspects: accepted inputs, returned fields, citations, and internal logic. No gaps are apparent.

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 auto-disambiguation for company type and the accepted input formats for each type, slightly expanding on 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 tool resolves names to canonical identifiers, with concrete examples ('ticker', 'CIK', 'RxCUI'). It distinguishes from sibling tools by noting it should be used when an ID is needed and that other tools require these IDs.

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

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

Explicitly advises to 'Use FIRST whenever you have a name but need an ID', providing clear use context. It also explains that it replaces multiple manual lookups, guiding when to prefer it over alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. 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 plus example question. Front-loaded with main action ('Compare AI visibility...'). Every sentence contributes to understanding use, process, and output. 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 4 parameters, 1 required, and no output schema, the description adequately covers purpose, input, output format, and use case. Could mention entity count constraint (2-8) explicitly, but schema handles it. Overall sufficient for selection and basic usage.

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

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

Schema coverage is 100%, and description adds meaning not in schema: first entity is treated as 'subject' for narrative, rest as competitors. Also explains that context disambiguates common names. Models and apiKey are well-described in schema, so description adds moderate 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 compares AI visibility across multiple entities using ai_visibility_check, ranks them, and surfaces which is most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (different comparison context).

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 usage for competitive AI-marketing audits and provides an example question. It implies the tool is for multi-entity comparison versus single-entity check, but does not directly contrast with other comparison siblings like compare_entities.

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, openWorld), description details return structure, partial failure behavior (bundlephobia timeout mention), and graceful degradation. 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 purpose. Includes technical details and edge cases, but could be slightly more concise. Earns its space overall.

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

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

No output schema, but description thoroughly explains return fields (summary, advisories, alternatives) and partial failures. Complete for a 2-param tool.

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

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

Schema coverage is 100%, but description adds context like scoped packages accepted, version defaults to latest. Adds modest additional 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?

The description clearly states it is a composite check for 'should I add this npm package' covering license, advisories, bundle size, etc. It distinguishes from siblings by specifying the exact resource and action.

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 (e.g., 'is X safe / popular / small'), scope (NPM only v1), and fallback for other ecosystems. Provides clear usage context.

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

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

Annotations already cover safety (readOnly, idempotent). Description adds embedding model, window size, character cap with truncation behavior, and return format (offsets, scores). No contradiction; adds significant behavioral detail.

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

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

Single paragraph front-loaded with purpose, then usage, then technical details. Efficient but could be slightly more structured. 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?

Despite no output schema, description explains return format (passages, offsets, similarity scores) and truncation flag. All 3 parameters are well-documented. Sufficient for agent to use 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% but description adds value: example inputs for text and query, max char limit for text, range for limit (1-20, default 5). Exceeds schema-only meaning.

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

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

The verb 'search' and resource 'inside a fetched record' are specific. Examples like SEC 10-K and article clarify scope. Distinguishes from siblings by naming ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt.' Pairs with ask_pipeworx_grounded for follow-up. Doesn't explicitly say when not to use, 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?

The description discloses important behaviors: returns subscription id, requires OAuth, delivery channel constraints, and webhook signing secret one-time delivery. Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds context without contradiction.

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

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

The description is somewhat lengthy due to comprehensive details, but it is well-structured: purpose statement first, then account requirement, then types, then delivery channels. Every sentence adds value, though slight trimming could improve conciseness.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers account requirements, all subscription types with examples, delivery channels, and return value. It could mention error handling or idempotency but is largely complete.

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

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

With 100% schema coverage, the baseline is 3, but the description significantly enriches parameter understanding. It provides concrete examples for each type's params, explains delivery fields with constraints (email validation, sms verification, webhook HMAC signing), and clarifies required fields for clinical_trial.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb, resource, and context. The supported types are listed, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context for when to use the tool, including prerequisite of a Pipeworx OAuth account and limitations (e.g., sms 10/day cap, phone verification). It does not explicitly compare to alternatives but the guidance is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns example questions with exact tool+argument shapes, which is valuable context 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 front-loaded with the core purpose but includes some redundancy (topics listed twice). It's well-structured and informative, though could be slightly more concise.

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

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

For a tool with 1 optional parameter and no output schema, the description fully explains return format, usage context, and parameter behavior. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by listing possible topic values (e.g., 'finance', 'pharma') and explaining the effect of omitting vs. passing a topic.

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 returns category-bucketed example questions with tool+argument shapes, serving as the onboarding entry point. It distinguishes from sibling tools like ask_pipeworx by specifying its role.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass a topic vs. no arguments.

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 important behaviors beyond annotations: ownership enforcement and deactivation vs deletion (keeps historical events). Aligns with annotations (destructiveHint=false, idempotentHint=true). No contradiction.

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

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

Two concise sentences, no redundancy. Purpose front-loaded, every sentence adds value (ownership, deactivation).

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 single-parameter mutation with no output schema, the description is fully adequate. Explains effect (deactivation) and relationship to recent_alerts, supported by annotations.

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 description for id (uuid returned by subscribe). The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action (cancel) and resource (subscription by id), and adds ownership enforcement and deactivation behavior, distinguishing it 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?

Provides clear context: ownership enforcement ensures only own subscriptions can be cancelled. Implies usage when you have a subscription id and want to stop alerts. No explicit when-not or alternatives, but siblings are named.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns a verdict, structured form, actual value with pipeworx:// citation, and percent delta. It also explains that it replaces multiple sequential 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 given the complexity, starting with example queries, then usage, supported domain, and output. It could be slightly tighter but is well-structured and every sentence provides value.

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

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

Given no output schema, the description fully documents return values (verdict types, extracted form, actual value, citation, delta) and specifies the supported domain (v1: company-financial claims). It addresses the complexity of the tool adequately.

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

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

Schema coverage is 100% (one parameter with a clear description). The description adds examples of valid claims, but the schema already explains the parameter adequately. The additional context is helpful but does not significantly exceed 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 it verifies natural-language claims against authoritative sources, provides example queries like 'Is it true that...' and explicitly names the domain (company-financial claims via SEC EDGAR + XBRL). It distinguishes the tool by noting it replaces 4–6 sequential calls, making its 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It further defines the scope (company-financial claims) and documents the returned verdict types. While it doesn't explicitly state when not to use it, the guidance is clear and actionable.

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