Science Feeds

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

Discloses return format (score, confidence, signals, raw_response per model + combined view), cost implications (BYO key for Anthropic), and non-destructive nature, adding value beyond readOnlyHint and idempotentHint annotations.

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

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

Two concise, front-loaded sentences covering purpose, model details, and use cases with no extraneous information.

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

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

Despite no output schema, the description fully explains return structure and scoring range, making the tool's outcome clear for its complexity.

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

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

With 100% schema coverage, the description adds practical context: default model, API key requirement, and context disambiguation, exceeding baseline of 3.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, distinguishing it from sibling tools like ask_pipeworx or deep_research.

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

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

Provides context for when to use (AI-marketing audits, pre-launch checks) and model selection guidance (default Workers AI, Anthropic requires API key), but no explicit exclusion of alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it routes to 4,552 tools, fills arguments, and returns structured answers with citation URIs, providing useful context beyond annotations. 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?

Description is long but well-organized with upfront emphasis, examples, and clear differentiation. Every sentence serves a purpose, though slightly verbose. Could be trimmed slightly without losing value.

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

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

Given the tool's complexity (many sibling tools, vast source coverage), the description thoroughly covers purpose, usage, and behavior. It mentions the return format (structured answer with citation URIs) and provides extensive examples, making it 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% with aliases documented. Description adds that the parameter is a natural language question and lists aliases, but does not add significant meaning beyond the schema. 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 answers factual questions using authoritative structured data from many sources. It lists specific categories (SEC filings, FDA drug data, etc.) and provides examples, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises to prefer this over web search, provides when to use (e.g., factual questions) and when to step up to alternatives (broad questions -> deep_research, need hallucination-resistant -> ask_pipeworx_grounded). Includes example phrasings that trigger its use.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the internal routing, data fetching, and extraction process, plus explicit refusal scenarios. 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 paragraphs packed with crucial information, front-loaded with key behavior. Every sentence is necessary and adds value with no redundancy.

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

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

Despite no output schema, the description explicitly defines the return format (answer, evidence, confidence, source, etc.) and all refusal reasons, fully equipping the agent to handle responses. Also covers cost trade-off.

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 mentions the question is natural language but adds no new meaning beyond what the schema's aliases already convey.

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

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

The description clearly states it's a hallucination-resistant answer mode for high-stakes reads, explicitly differentiating from ask_pipeworx and detailing the answer extraction process. It provides a specific verb and resource, making the tool's purpose unmistakable.

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

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

The description gives explicit guidance on when to use the tool (answers to be quoted/cited/acted on, high-stakes domains) and when to prefer the sibling ask_pipeworx (casual lookups), including a cost trade-off explanation.

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

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

The description goes far beyond annotations (readOnlyHint, idempotent, etc.) by detailing fan-out logic, response shapes, resolver contract with match confidence, parent event extraction, news fallback fields, safety mechanisms, and resolution-rule risk. It discloses failure modes and what agents should inspect. No contradiction with annotations.

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

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

The description is long but well-structured with clear headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds unique value. While dense, it is justified by the tool's complexity; however, it could be slightly more concise without losing critical information.

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

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

Despite no output schema and high complexity, the description covers input, classification, fan-out, response structure, resolver contract, parent events, news fields, safety, liquidity, and resolution-rule risk. It is remarkably comprehensive for a tool of this sophistication.

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

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

Schema coverage is 100% with descriptions for market, depth, and include_raw. The description adds context: examples for market input, default behavior for depth, and explanation of include_raw's payload sizes and use cases. This enriches the schema's meaning.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and the overall process (resolve market, classify bet, fan-out, return evidence + comparison). This strongly distinguishes it from sibling tools like ask_pipeworx 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?

Explicit usage examples are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also includes safety notes about low-confidence resolutions, closed markets, and wide spreads, guiding the agent on when to trust or inspect results. It implicitly contrasts with siblings by focusing on bet-specific research.

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

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

Annotations indicate readOnly=true, openWorld=true, idempotent=true. Beyond that, the description adds: results are sorted by primary metric for 'largest' queries, off-calendar fiscal years are handled correctly, and returns pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is longer than ideal but every sentence adds value: example queries, preferred usage, data sources, sorting behavior, and return format. It is front-loaded with key phrases. Minor conciseness improvement possible, but still effective.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and no output schema, the description covers all essential aspects: what data is returned, how it is sorted, and that citation URIs are included. It is complete for agent use.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'type', it specifies financial metrics (revenue, net income, cash, debt) for companies and adverse-event counts, FDA approvals, trials for drugs. For 'values', it gives example inputs (tickers, drug names) and confirms min/max (2-5). This goes beyond schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example user queries like 'Compare X and Y' and 'rank these companies', and explains the data sources (SEC EDGAR for companies, FAERS for drugs). This distinguishes it from siblings like 'entity_profile' for single entities.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear when-to-use directive. Example queries illustrate user intent, and the 2-5 count implies not to use for single entities. No explicit when-not-to, but context is sufficient.

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

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

Description adds substantial behavioral context beyond annotations: account requirement, expected duration (15-60s), decomposition into facets, return format (findings packet with gaps[], citations), and the fact it is not open-web search. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destruction; description aligns and enriches.

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 thorough but each sentence adds value—account warning, alternative, mechanism, return structure, use cases, timing. Slightly long but well-structured with clear sections; 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 complexity (1160 sources, 4552 tools, parallel decomposition) and no output schema, the description fully covers how the tool works, what it returns (evidence, confidence, source, fetched_at, citations, gaps), expected latency, and precise usage context. No gaps left for the agent.

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

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

Schema coverage is 100%, and description adds meaningful detail: it explains the depth enum values (quick=3, standard=5, thorough=8) and clarifies that the question should be broad and multi-part. This goes beyond the schema's basic descriptions.

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

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

The description clearly states this tool performs 'grounded multi-source research across Pipeworx's 1160 structured data sources' in a single call, with decomposition and parallelization. It distinguishes itself from siblings like ask_pipeworx by specifying it's for broad/multi-part questions over structured data, not open-web search.

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

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

Explicitly provides when-to-use (broad/multi-part over structured data) and when-not-to-use (single lookups use ask_pipeworx; breaking news prefers ask_pipeworx). Also mentions account requirements and provides an alternative (ask_pipeworx) for unsigned users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds valuable context that each result includes full input schemas with curated examples and is ready to call directly, which is 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 well-structured with front-loaded purpose, followed by domains, return format, and call-to-action. Every sentence adds value, though slightly verbose; could be tightened but still effective.

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

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

Despite no output schema, the description fully explains the return value: top-N most relevant tools with names, descriptions, and full input schemas. It also notes no second lookup needed. Given the complexity and rich annotations, this is complete.

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

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

Schema description coverage is 100%, and the description adds meaning by explaining that parameters like task, q, search, description are aliases for query and provides examples of natural language inputs. This enriches the schema information.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example data domains and explains that it returns top-N tools with schemas. It distinguishes from sibling tools like deep_research by noting this is for discovering the option set from many tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, implying alternatives for other 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by detailed behavioral info: the tool fans out across multiple APIs, notes patents API sunset May 2025 (soft-fails), and lists exact return fields with URIs for filings. No contradiction with annotations.

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

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

The description is front-loaded with examples and organized into logical sections, but it is somewhat lengthy. However, each sentence adds substantive value, so it earns a 4 rather than a 5.

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

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

Despite lacking an output schema, the description comprehensively explains the return structure (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and covers input limitations, making it fully sufficient for agent use.

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

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

With 100% schema coverage, the description still adds value by clarifying accepted value formats (ticker or CIK, no names), mentioning future type expansions (person/place coming soon), and reinforcing input constraints.

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

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

The description clearly states the tool's purpose: producing a 'full cross-source profile of a US public company in ONE parallel call.' It provides concrete example queries ('Tell me about X', 'research Acme') and enumerates the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), distinguishing it from sibling tools like resolve_entity.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It states when not to use—'names not supported (use resolve_entity first if you only have a name)'—and specifies acceptable input formats (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 indicate read-only, idempotent, open-world, and non-destructive. The description adds behavioral detail: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway', which is useful 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 two concise sentences with no wasted words, front-loading the core purpose and then adding a usage hint. Every sentence adds value.

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

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

With no output schema, the description could mention the normalized output format, but the key behaviors (fetch, normalize, fallback) are covered. The param schema is complete. Adequate for a simple read 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% (all three parameters described in schema). The description adds no additional meaning for parameters beyond the schema; it merely repeats the URL purpose in a different phrasing.

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 'Fetch and normalize any RSS / Atom / RDF feed by URL', specifying the verb (fetch/normalize) and resource (feed), and distinguishes from sibling 'list_feeds' which is for curated sources.

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

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

The description advises 'Use list_feeds first for curated sources', giving context on when to prefer another tool. However, it doesn't explicitly state when not to use this tool or mention other alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which convey key behavioral traits. The description confirms 'Delete' and adds context about when to use it, but does not disclose additional behaviors such as error handling or side effects beyond what annotations provide. It adds value but not extensive 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 consists of three efficient sentences: the first states the action, the second provides usage scenarios, and the third references sibling tools. There is no redundant or repetitive information, and the structure is well-organized for quick comprehension.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers its purpose, usage, and related tools. It lacks explicit mention of behavior when the key does not exist (e.g., error or success) or return value, but annotations provide idempotency and destructiveness. Overall, it is nearly complete for a delete operation.

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 input schema already describes the 'key' parameter as 'Memory key to delete'. The description only says 'by key', which adds no new meaning. The description does not elaborate on parameter format, constraints, or examples, so it performs adequately but does not exceed the schema.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies the verb (delete) and resource (memory by key), and explicitly distinguishes from siblings by mentioning 'Pair with remember and recall.' This leaves no ambiguity about the tool's function.

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

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

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions related tools 'remember and recall', indicating alternatives for storage and retrieval. However, it does not explicitly state when not to use this tool, but the given guidance is sufficient.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: it fetches the page, extracts title/description/key links, and outputs standard markdown. 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 core action and format, second lists use cases. Front-loaded, no filler, every sentence earns its place.

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

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

The tool is simple with 2 parameters (100% schema coverage) and no output schema. Description fully covers purpose, output format, and use cases. 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% (both parameters documented). The description adds context about the output format ('standard llms.txt markdown') and purpose, but doesn't elaborate on parameter constraints beyond defaults. The 'single text blob' clarifies return format, slightly above baseline.

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

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

The description uses specific verbs ('Generate', 'Fetches', 'extracts', 'emits') and clearly identifies the resource ('production-ready llms.txt file for any URL'). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't provide when-not-to-use or alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds scope (curated science & space) and filter behavior, consistent with annotations.

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

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

Single concise sentence front-loads purpose, uses no superfluous words, and efficiently communicates functionality.

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 2 optional parameters and no output schema, the description covers all necessary aspects: purpose, fields returned, filters, and linkage to related tool.

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

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

Schema description coverage is 100% and the tool description largely mirrors the schema's parameter descriptions. No additional semantic meaning beyond what 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?

Clearly states 'List the curated science & space feeds' with specific fields, and distinguishes from sibling 'read_feed' by instructing to pass an id to that 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?

Provides when to use with optional filters and differentiation to read_feed. Does not explicitly list alternatives for other sibling tools, but sufficient for a simple list tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's safety profile is covered. The description adds that it lists 'active' subscriptions by default, which is useful but not extensive.

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

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

Two sentences efficiently convey purpose, return values, and usage guidance without unnecessary words.

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

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

Given one optional parameter, comprehensive annotations, and listing of return fields, the description is fully sufficient for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the description does not need to add extra semantics. It does not provide additional meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly advises using this tool to review current subscriptions before adding more or to find an id to cancel, providing clear guidance on when to use it 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?

Description discloses rate limiting (5 per identifier per day), that it is free and doesn't count against tool-call quota, and that feedback is read daily and influences roadmap. Annotations (readOnlyHint false) align with the writing nature. 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?

Description is concise (~4 sentences) with front-loaded purpose and clear step-by-step guidance. 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?

Given no output schema and simple structure, the description fully covers purpose, usage, parameter guidance, constraints, and behavioral notes. Nothing missing.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds value by advising on how to formulate feedback (in terms of tools/packs) and what to avoid, going beyond schema. Slightly redundant with schema enums but still useful.

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's purpose: sending feedback to Pipeworx about bugs, missing features, data gaps, or praise. It clearly distinguishes from sibling tools, which are primarily data retrieval or actions, by framing it as a communication channel.

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 specific when-to-use scenarios (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). It also mentions rate limits and quota, giving clear operational 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 provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. No contradictions.

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

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

The description is well-structured, starting with a clear hook, then the return value, then use cases, then technical details. Every sentence adds value, and it is appropriately concise for the complexity.

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

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

Given the tool has one optional parameter and no output schema, the description is complete. It explains the data source, privacy, caching, and use cases, ensuring the agent can use it correctly without additional info.

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

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

Schema coverage is 100% with an enum and description for 'window'. The description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, aiding selection.

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 what other AI agents are calling on Pipeworx, including top tools, packs, and call volume over a window. This specific verb+resource combination distinguishes it from siblings like discover_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 lists three concrete use cases (discovering hot data, confirming canonical tools, aligning use cases) that guide when to use the tool. It does not explicitly state when not to use it or name alternatives, but the use cases provide clear context.

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

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

Annotations already declare safe read-only behavior. The description adds rich behavioral details: scans top ~200 markets, walks child markets, checks monotonicity, computes partition sums, filters placeholders, and performs fill check. No contradiction with annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with the core purpose. Could be slightly more structured (e.g., bullet points for modes), but overall efficient for the complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array, partition_check object, fill_check logic). It covers semantic anchor, partition filter, and references a sibling tool, making it complete for a complex arbitrage detection 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 descriptions cover both parameters (100% coverage). The tool description adds valuable context: event parameter accepts full URLs, topic expects a seed question, and explains the mode behavior. Adds significant meaning beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending, event, topic), each with a specific behavior, making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode and warns when not to trade (realizable_edge ≤ 0). It also directs to polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond the annotations (which only indicate readOnly, openWorld, idempotent, non-destructive). It reveals extensive behavioral details: the three model families with specific formulas (e.g., lognormal barrier from FRED log-returns, GDELT article-volume ratio, partition_overround with per-sport alpha, placeholder-slug filters). It explains how edges are computed net of slippage, how Kelly fractions are capped, and includes a 24h-move warning. It also details caching policy and diagnostics for empty segments. No contradictions with annotations.

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

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

The description is well-structured: it opens with the core purpose, then details model families in segments, followed by tradeable-edge knobs and response top-level structure. It is verbose but every sentence adds new information. The use of bullet-like formatting with numbers and parentheses helps readability. Some redundancy exists (e.g., repeating parameter details that are in the schema), but overall it is organized and front-loaded.

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

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

Given the complexity of the tool (9 parameters, no output schema, three model families with intricate logic), the description is remarkably complete. It explains the response structure under by_segment, the diagnostics fields, and every relevant edge metric (edge_pp_net, kelly_fraction, market.liquidity, etc.). It covers special cases like Fed bets and caching. Without an output schema, the agent can fully understand what to expect. The description leaves no critical gaps.

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

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

The input schema already has 100% coverage with good descriptions for all 9 parameters. The tool's description adds significant value by explaining how parameters like min_partition_leg_kelly interact with partition overround opportunities (e.g., 'min_kelly never filters them — this knob applies to the per-leg Kelly inside top_legs instead'). It also provides context for tradeable-edge filters (max_spread_pp, min_liquidity) on how they affect opportunities. The description complements the schema well.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes itself by being built for 'what should I bet on today' — discovering opportunities without paging through hundreds of markets. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 usage context: it is designed for agents to discover bet opportunities daily. It explains the three model families and the tradeable-edge knobs (min_liquidity, max_spread_pp, etc.). While it doesn't explicitly state when not to use it or list alternatives, the detailed parameter descriptions and response structure give strong implicit guidance. The mention that 'Fed bets surface here, excluded from ranking' adds specific context about a special 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, openWorldHint, and idempotentHint. The description adds valuable behavioral context: the structure of returned data (tracked, expired, snapshot_dates), limitations (60-day TTL, decay from daily closes), and snapshot creation conditions. No contradictions with annotations.

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

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

The description is well-organized, front-loading the purpose, then explaining response structure, parameters, and limitations. It is somewhat lengthy but every sentence adds value. Could be slightly more concise without losing clarity.

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

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

Given the absence of an output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields, along with limitations and assumptions. This provides complete context for an agent to understand and use the tool effectively.

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

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

Schema description coverage is 100% for both parameters. The description reiterates the defaults and clamps but does not add new meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' using snapshots, answering a specific question about edge longevity. It differentiates itself from sibling tools like polymarket_edges by focusing on historical trends rather than current values.

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

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

The description explains the use case ('how long has this edge existed and is it shrinking?') and provides context for when to use it, but it does not explicitly state when not to use it or mention alternative tools like polymarket_edges for real-time data. The context is clear but lacks explicit exclusions.

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. The description adds behavioral detail: what the check returns (top_of_book, vwap_fill_price, slippage, verdicts), and the risk of partial basket fills converting arbitrage into unhedged directional positions—a key behavioral trait not captured by annotations.

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

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

The description is informative but verbose (approx. 300 words). It front-loads the core purpose and required parameters, but the dense text could benefit from structured formatting (e.g., bullet points for return fields). Each sentence adds value, but overall length reduces quick scanability.

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

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

The tool is complex with two modes, multiple return fields, and risk warnings. With no output schema, the description covers key return values, defaults, and edge cases (thin_legs, forced_directional_risk). It provides enough context for an agent to understand what to expect, though a complete output schema would further enhance completeness.

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%. The description adds meaning beyond the schema by clarifying the side parameter's default in basket mode ('auto — sell if partition sum > 1, buy if < 1'), and explaining size_usd interpretation in both modes (spend vs target proceeds; settlement notional for basket). This helps agents use parameters correctly.

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

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

The description starts with a specific verb ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before those.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns against partial basket fills leading to unhedged directional positions, providing clear when-to-use and when-not-to-use context.

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

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

Beyond annotations (readOnly, idempotent), the description details response structure (leg prices, spread), safety fields (compatibility_warning, temporal_alignment), and conditions for warnings. 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 detailed but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose, though slightly verbose given the complexity.

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

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

Comprehensive coverage: explains output format, safety warnings, temporal alignment, and conditions for meaningless spreads. No output schema, so the description fully compensates by detailing return values.

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

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

Schema coverage is 100% with descriptions, but the description adds interpretive context: explains the macro shortcuts for the topic parameter and the override behavior for explicit tickers. This adds value beyond 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's function: comparing prices between Kalshi and Polymarket for the same event. It specifies two modes (topic shortcuts and explicit tickers) and contrasts with sibling tools like polymarket_arbitrage.

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

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

Provides explicit guidance on when to use (to find cross-venue spreads) and warns that most pre-mapped topics return compatibility warnings, indicating non-tradeable spreads. It explains safety fields that indicate when to avoid using the spread.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return format (normalized items with fields) and optional filtering, providing useful behavioral context beyond annotations.

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

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

Two sentences, no redundant information. First sentence covers purpose and output, second introduces optional filter. Front-loaded and efficient.

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

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

Covers purpose, parameters, output fields, filtering. Lacks error handling details (e.g., feed not found), but sufficient for a simple read tool with rich 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 descriptions for all parameters. Description restates keyword filtering but adds minimal extra meaning beyond schema, warranting baseline score.

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

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

Explicitly states verb 'Read', resource 'curated science & space feed', and mechanism 'by its id (from list_feeds)'. Distinguishes from siblings like list_feeds and fetch_feed by specifying normalized output and optional keyword filtering.

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

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

Provides context that feed id must come from list_feeds, implying prerequisite. Does not explicitly state when not to use or compare to alternatives, but clear enough for typical use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds scoping details (anonymous IP, BYO key hash, etc.) and that omitting key lists all keys. 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?

Three concise sentences, each adding value. Front-loaded with core functionality, followed by use case and scoping. No unnecessary words.

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

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

The description covers usage and scoping well but lacks details about the return format (e.g., string or structure of values or list of keys). Since no output schema exists, this is a gap.

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

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

Schema coverage is 100% and the schema description already explains the key parameter. The description repeats this information without adding new semantics beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when omitting the key argument. It distinguishes from sibling tools remember and forget.

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

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

The description explains when to use the tool (look up stored context) and implicitly contrasts with remember and forget. It could be more explicit about when not to use it, but guidance is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavior: explains mark_read functionality, return fields, and alternative access via URL. 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?

Four sentences, each with clear purpose: purpose, return fields, filter examples, and additional behavior. No fluff, front-loaded, every sentence adds value.

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

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

No output schema, but description details return fields. All parameters are optional and explained. Polling and alternative access are mentioned. No gaps for this 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 concrete examples for type and since, and explains mark_read's effect beyond schema, earning an extra point.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', with specific return fields. However, it does not explicitly distinguish this tool from similar siblings like fetch_feed or read_feed, though it provides enough context for typical use.

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

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

The description implies usage for retrieving recent alerts and mentions polling works fine, but lacks explicit guidance on when not to use this tool or how it compares to alternatives like fetch_feed. No when-not or alternative tool names are given.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds operational details: fans out to multiple sources, fallback behavior, soft-fail for USPTO, and response structure with grouped changes and URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads purpose and gives concrete examples. Every sentence adds value, no redundancy, and it is appropriately sized for a tool with 3 parameters.

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

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

Given no output schema, the description adequately describes return structure (changes[], total_changes, URIs). All 3 parameters are fully described. Differentiation from the sibling tool 'entity_profile' is explicit, making the tool's place in the set clear.

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 significant value: explains `since` accepts ISO date or relative shorthand with examples, suggests '30d' for typical monitoring, explains `value` accepts ticker or CIK, and notes `type` only supports 'company'.

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

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

The description clearly states the tool returns a change feed for a company (SEC filings, news, patents) within a time window. It uses specific verbs like 'fans out' and 'returns', and distinguishes from sibling tool 'entity_profile' which returns a static profile.

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

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

The description provides explicit usage scenarios (e.g., 'What's new with X', 'latest on Y') and explicitly states when to use 'entity_profile' instead. It also explains the fallback from GDELT to GNews and the soft-fail for USPTO.

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

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

Annotations indicate idempotent write. Description adds critical context: key-value pair scoped to identifier, persistence differences between authenticated (persistent) and anonymous (24 hours). Also states pairing with recall/forget. 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?

Four sentences, each serving a distinct purpose: purpose, usage guidance, storage details, pairing with other tools. Front-loaded and no superfluous content.

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

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

Tool has only 2 required params, no output schema, no nested objects. Description covers purpose, when to use, storage behavior, and related tools. Complete for the simplicity 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 covers both parameters fully with descriptions and examples. Description adds context on usage examples and storage semantics, but schema already provides clear meaning. Slight added value beyond schema.

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

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

Description clearly states verb 'save' and resource 'data' for reuse across conversations/sessions. It distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning them as partners. Examples of data types (resolved ticker, address, preference) make purpose concrete.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides examples. Mentions pairing with recall/forget. Does not explicitly state when not to use, but context is sufficient for an AI agent.

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 valuable behavioral context: 'Each call cascades through several lookup endpoints internally,' and details the exact return structure for each entity type (e.g., ticker, CIK, company_name, citation URI for companies).

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 at 4-5 sentences, front-loaded with examples and use cases. Every sentence adds value—no repetition or fluff. The structure is clear: use case, supported types with details, and efficiency note.

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

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

No output schema exists, so the description must explain return values, which it does thoroughly: for company returns ticker, 10-digit CIK, company_name, and citation URI; for drug returns RxCUI, ingredient, brand, and citation URI. Given the tool's simplicity (2 parameters), the description is complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining the semantics of the 'type' enum and the 'value' parameter beyond the schema: for type 'company', value can be ticker, CIK, or name; for 'drug', brand or generic name. It also mentions auto-disambiguation for company input.

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's purpose: resolving a user-spoken name to a canonical/official identifier. It provides specific examples like 'What's the ticker for…' and lists supported types (company, drug) with return details, clearly distinguishing it from sibling tools like entity_profile.

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

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

The description gives direct usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, indicating when it's most efficient. The supported types and input formats are clearly specified.

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, destructiveHint. Description adds that it probes multiple entities and returns a ranked list with specific fields (score, confidence, signal density). Consistent and adds value beyond annotations.

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

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

Three sentences cover action, mechanism, and use case. Front-loaded with core purpose, no unnecessary words. Every sentence earns its place.

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

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

Given comprehensive annotations and complete schema, the description covers purpose, mechanism, output structure, and relationship to sibling tool. No gaps remain for agent to effectively select and invoke the tool.

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

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

Schema coverage is 100% (all parameters described). Description adds context: first entity treated as subject for narrative, entities limited to 2-8, and explains the role of context parameter for disambiguation. This goes beyond the schema descriptions.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side' and explains the process (probes with ai_visibility_check, ranks, surfaces most/least recognized). It distinguishes from sibling tool ai_visibility_check by aggregating multiple probes.

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 ('competitive AI-marketing audits') and an example use case. Does not explicitly state when not to use or name alternatives, but the description and sibling list imply it's for batch comparison vs single check.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by noting that bundlephobia's first measurement may take 5-30s and that partial failures degrade gracefully (sources_failed listed). 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?

Description front-loads the main purpose and is well-structured with usage, limitations, and failure behavior. However, it is somewhat lengthy; could be more concise without losing 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 complexity (multiple external APIs, no output schema), the description fully covers what the tool checks, what it returns (summary, advisories, links, alternatives), limitations (NPM only, timing issues), and error handling. Adequate for agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond schema: it explains allowed package name formats (scoped packages) and default version behavior, but these are already in schema descriptions.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, covering license, advisories, size, etc. It uses a specific verb ('check') and resource ('npm package'), and distinguishes it from siblings by focusing on package evaluation.

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 agent asks about safety/popularity/size or cost of adding a package. Also provides exclusion: NPM only in v1, with fallback for other ecosystems. See 'Use whenever...' and ecosystem note.

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 detail beyond the annotations (readOnlyHint, idempotentHint): truncation at 200K chars with flag, embedding model (BGE-base-en), window size (500-char overlapping), similarity measure (cosine), and that passages carry character offsets for verification. 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 three sentences with no wasted words. It front-loads the purpose and packs technical details (embeddings, offsets, cap) efficiently. Every sentence earns its place.

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

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

Given no output schema, the description sufficiently explains the return format (passages with offsets and similarity scores), input limits, behavior on overflow, and algorithmic choices. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful extra context: 'max ~200K chars' for text, '1-20, default 5' for limit, and example queries for the query parameter. This goes beyond the schema's basic descriptions.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and outputs (passages with offsets and similarity scores). It effectively distinguishes the tool's purpose from siblings by mentioning pairing with 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?

The description explicitly says to use when the record is too large for the prompt and pairs with ask_pipeworx_grounded, providing clear context. However, it does not explicitly state when not to use this tool, only implying alternatives through the pairing note.

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 annotations: OAuth requirement, subscription types, delivery channels with rate limits and verification, webhook signing, and auto-disable. No contradiction with annotations.

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

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

The description is well-structured with clear sections for purpose, requirements, types, and delivery, though slightly dense. Every sentence adds value with minimal fluff.

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

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

Despite lacking an output schema, the description explains the return value and covers all parameters with behavioral details, making it fully complete for a complex tool.

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

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

The description enriches the schema by providing concrete examples for each type and explaining delivery channel requirements in detail, adding significant meaning beyond the schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription id. It is well-differentiated from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides clear context on when to use (building a subscription), prerequisites (Pipeworx OAuth account), and detailed type and delivery options, but does not explicitly exclude 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?

While annotations already declare readOnly, idempotent, and non-destructive, the description adds valuable context: it returns categorized examples with tool shapes and is the onboarding entry point. No contradictions, but could mention that no side effects occur.

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 detailed yet every sentence adds value. It front-loads trigger phrases and structures information logically. While long, it is appropriate 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 lack of an output schema, the description fully explains what is returned (category-bucketed examples with tool+argument shapes). No missing context needed for proper use.

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

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

Schema coverage is 100% with one parameter, but the description adds essential usage context: calling with no arguments gives full spread, while passing a topic focuses results. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point, returning categorized example questions with tool calls. It uses specific trigger phrases and distinguishes itself from sibling tools like ask_pipeworx and discover_tools.

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

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

Explicitly advises using this tool first when the user doesn't know what Pipeworx can do, and explains how to use the topic parameter to focus. Provides clear when-to-use guidance without ambiguity.

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

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

The description adds context beyond annotations: ownership enforcement and deactivation behavior. Annotations already indicate non-destructive and idempotent, but description clarifies real effect.

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

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

Two sentences, front-loaded with the action, no wasted words.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers purpose, usage constraints, and behavioral outcome completely.

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

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

Schema coverage is 100% and schema already describes the id parameter. Description adds no additional detail about the parameter beyond referencing it.

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 'Cancel' and the resource 'subscription by id'. It distinguishes from sibling tools like subscribe (opposite) 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?

The description mentions ownership enforcement and that the row is deactivated, not deleted, which informs when to use. However, it does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it describes the return verdict types (confirmed, approximately_correct, refuted, etc.), mentions the extracted structured form, actual value with citation, and percent delta. It also explains that the tool replaces multiple sequential calls, providing insight into its efficiency. 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 somewhat long but well-structured: it starts with natural-language examples ('Is it true that…'), then states the purpose, scope, and output details. Every sentence adds value, and the information is front-loaded. Minor redundancy could be trimmed, but overall effective.

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

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

Despite no output schema, the description fully compensates by listing all return elements (verdict, structured form, actual value, citation, delta). It also explains the supported domain (company-financial claims via SEC EDGAR + XBRL) and replacement of multiple calls. For a complex tool with one parameter, this is complete.

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

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

The input schema has 100% coverage with a clear description for the single 'claim' parameter. The description adds extra meaning by specifying the types of claims supported (company-financial) and providing example formats ('Apple's FY2024 revenue was $400 billion'). This exceeds the baseline of 3 for full schema coverage.

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

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

The description uses multiple specific verbs ('verify', 'fact check', 'confirm or refute') and explicitly states the resource ('natural-language claim verification against authoritative sources'). It clearly differentiates from sibling tools by noting that it replaces 4–6 sequential calls, indicating a unique unified function.

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

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

The description provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also scopes the tool to 'company-financial claims' and gives examples. While it doesn't explicitly list when not to use, the scope is clear enough for an agent to decide.

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