Packagephobia

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 valuable behavioral context: probing multiple models, scoring mechanism, and the financial implication of using Anthropic (BYO key). 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 two well-structured paragraphs: first paragraph states the action and key outcome; second paragraph details parameters and use cases. Every sentence is necessary, no redundancy.

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

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

Given the tool's complexity (4 params, no output schema), the description is complete. It explains the return format (per-model {score, confidence, signals, raw_response} plus combined view), the default model, and the optional API key requirement. No gaps remain for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. However, the description significantly adds meaning: it clarifies that 'entity' can be brand, product, etc.; 'models' includes specific model names with defaults; explains that '_apiKey' is passed through to Anthropic and required only if Anthropic is probed; 'context' disambiguates common names. This goes well beyond the schema descriptions.

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

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

The description uses a specific verb 'probe' and clearly identifies the resources: LLMs for a business/brand/product/topic. It directly states the output (visibility score 0-100 per model) and distinguishes from sibling tools by focusing on AI visibility scoring rather than other functions like research or alerts.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when not to use alternatives, e.g., default model free vs. requiring BYO key for Anthropic. No explicit exclusions but the context is clearly delineated.

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?

With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds useful behavioral context: it routes to a specific number of tools, fills arguments, returns stable pipeworx:// citation URIs, and is a single fast call. It doesn't discuss error handling or ambiguous questions, but given annotation coverage, the added context is meaningful.

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 average but front-loads the most important instruction ('PREFER OVER WEB SEARCH') and then systematically covers domains, trigger phrases, examples, and escalation paths. Every sentence earns its place, though some trimming of the source-count detail could tighten it.

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 having no output schema, the description explains the return format (structured answer with pipeworx:// citation URIs) and provides extensive usage context including domains, example queries, and alternative tools. It gives enough detail for an agent to decide when to call this tool without needing additional information.

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 documents all parameters with 100% coverage, but the description enriches the 'question' parameter by providing multiple example questions and clarifying that it accepts natural-language queries about real-world entities, events, or numbers. The examples help the agent formulate appropriate input beyond the schema's generic description.

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

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

The description clearly states that ask_pipeworx routes factual questions to 5,562 tools across 1,462 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives, and lists specific domains and example queries.

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

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

The description explicitly advises 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and gives concrete conditions for when to use alternative tools: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. It also covers breaking-news routing, making the when-to-use very 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, open-world, idempotent, and non-destructive behavior. The description adds essential context: it is a full working router, not a fallback, with candidate routing improvements enabled live only during tests, and currently matching the stable version because no candidate is active. This goes beyond annotations without contradicting them.

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

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

The description is three sentences and front-loaded with the core purpose. The parenthetical enumeration 'same 5,562 tools, same arguments, same response shape' is dense but not excessive. It earns its place by confirming identity with the stable tool, though it could be slightly more streamlined.

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 role as a beta router, the description covers its current behavior, relation to the stable version, and that it is a complete working tool. It mentions the same response shape but does not elaborate on return format, which is acceptable given the stable sibling's reference and the lack of an output schema.

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

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

The input schema covers all six parameters with 100% description coverage, clearly explaining that 'question' is required and the other five are aliases. The description adds nothing about parameters, so the baseline score of 3 applies as the schema handles semantics completely.

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 is the beta version of ask_pipeworx, a universal router with the same 5,562 tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the experimental edge with candidate routing improvements, making the purpose unambiguous.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. This provides clear context on when to choose this beta over the stable alternative, even if not stating a formal exclusion.

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

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

The description goes far beyond the annotations (readOnly, idempotent, non-destructive) by disclosing the exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), the refusal mechanism with enumerated refusal reasons, and the extra LLM call cost. This is rich behavioral context that annotations alone do not 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 dense but every sentence earns its place: mode, routing behavior, extraction guarantee, return schema, refusal reasons, use cases, and cost comparison with the alternative. It is front-loaded with the most critical information and maintains structural clarity.

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

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

Given the tool has no output schema, the description fully compensates by detailing the exact response structure and failure modes. It also explains the underlying routing/fetching behavior and the cost implication, making the tool's behavior completely predictable for an agent. No gaps remain.

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

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

The input schema provides 100% coverage, describing each parameter as an alias for the 'question' field with clear natural-language semantics. The description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate given the schema already carries the full burden.

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

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

The description clearly identifies a specific mode: 'Hallucination-resistant answer mode for high-stakes reads.' It also distinguishes itself from the sibling 'ask_pipeworx' by noting the same routing but with extraction and refusal behaviors. The verb 'ask' and resource 'Pipeworx Grounded' are explicit, and the scope is unambiguous.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists example domains. It also excludes casual lookups by stating 'prefer ask_pipeworx for casual lookups' and explains the cost trade-off.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond by detailing resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, wide-spread warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is long but well-structured with clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value; minor redundancy in explaining fallbacks. 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, including fields like market_match_confidence, evidence keys, and resolution risk. Covers edge cases (closed markets, low confidence, wide spreads) and provides concrete fan-out examples for various bet types.

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 3 parameters. The description adds significant meaning: market can be slug/URL/question text, depth defaults to thorough, include_raw defaults false with a clear rationale (response size considerations). Examples further clarify.

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 precise verbs ('Research', 'pull', 'resolves', 'classifies', 'fans out', 'returns') and clearly identifies the resource (Polymarket bet, Pipeworx data). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by its comprehensive research 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 explicitly provides use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives detailed examples. It does not explicitly state when NOT to use it or name alternative tools, but the usage context is very 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?

Beyond annotations (readOnly, idempotent), the description discloses key behaviors: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This adds significant context.

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

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

The description is somewhat long but well-structured: starts with example queries, then explanation, type-specific details, and result format. Every sentence adds value; no redundancy. Could be trimmed slightly, but remains efficient.

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

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

Given no output schema and moderate complexity (two entity types, multiple metrics), the description covers data sources, sorting, and citation URIs. It also notes efficiency gains. Lacks exact output format, but the 'paired data' mention is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what each type pulls (company financials vs drug data), giving examples for values (tickers/CIKs or drug names), and clarifying constraints (2-5 items).

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

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

The description clearly states the tool compares 2-5 companies or drugs side-by-side in one parallel call, with specific examples like 'compare X and Y'. It distinguishes from sequential single-entity lookups, which are common sibling tools such as 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?

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger examples. Lacks explicit exclusion criteria (e.g., for >5 entities), but the guidance is strong and 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses account/auth requirements, paid tier for thorough depth, expected latency, that gaps[] are 'never invented', contradictions[] detection, semantic excerpting, and resolvable citations. 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 dense with essential context: account requirement, alternative tool routing, depth behavior, output structure, and latency. It is front-loaded with the most critical caveat (account + alternative). Some redundancy with the schema's depth description exists, but given the tool's complexity, the length is mostly justified.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return values (findings packet, evidence, confidence, source, fetched_at, citation, gaps[]), depth modes, error behavior (gaps not invented), and practical concerns like latency and account tiers. It is fully complete for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by giving concrete example questions ('compare X and Y's regulatory + financial exposure') and explaining depth behavior in terms of gap recovery and hops beyond the schema's already-detailed enum descriptions. It does not add entirely new parameter syntax but reinforces semantics.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, decomposes questions, and returns a findings packet. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making its unique purpose unambiguous.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also states it's 'Best for broad/multi-part questions', giving 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?

The description adds detail beyond annotations: results include full schemas with curated examples, ready to call. Annotations already indicate read-only, idempotent, non-destructive. No contradictions.

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

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

The description is well-structured and front-loaded with the purpose. It efficiently lists domains and output details without redundancy. Minor wordiness 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?

The description covers purpose, usage, and return structure well. However, it lacks details on error handling, behavior when no tools match, or result limit enforcement beyond schema's max 50. Adequate for the 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?

Parameter schema coverage is 100%, so baseline is 3. The description mentions query accepts aliases (task, q, description, search) but that is already in the schema. It adds no new semantic meaning beyond what the schema provides.

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

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

The description uses a specific verb 'find tools' and clearly states the resource as tools by describing task/data. It lists many example domains and distinguishes itself as a meta-tool for discovery, contrasting with sibling tools that are domain-specific.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context. It does not state when not to use, but the guidance is strong for a tool that is unique among siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds detailed behavioral traits: returns specific fields (CIK, filings with URIs, fundamentals, patents with note on sunset, news, LEI), uses multiple data sources, and soft-fails for patents. No contradictions with annotations.

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

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

The description is long but well-structured: starts with examples, then preferred usage, then lists sources and return data. Every sentence adds value, though it is somewhat dense. It is front-loaded with key information.

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

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

Given no output schema, the description thoroughly explains return values and data sources. It covers limitations (names not supported, patents sunset, only company type) and provides all necessary context for an agent to understand the tool's capabilities and constraints.

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, so baseline is 3. The description adds value by explaining that type is currently only 'company', and value can be ticker or CIK (not names), with examples. This helps the agent understand parameter usage beyond what the schema provides.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies, with multiple example queries. It distinguishes from siblings by explicitly preferring this tool over chaining individual lookups and mentioning resolve_entity for name-only queries.

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

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

The description provides explicit when-to-use (holistic view) and when-not-to-use (if only have a name, use resolve_entity first). It also emphasizes efficiency by performing a single parallel call instead of chaining multiple tools.

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

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

The description states 'Delete', which aligns with the destructiveHint annotation. It discloses the destructive nature effectively, though it does not elaborate on permanence or side effects beyond what annotations already provide. With annotations covering destructiveHint, the description adds sufficient clarity.

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

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

The description is two sentences, front-loaded with the action ('Delete a previously stored memory by key'), and every sentence is necessary and informative. No wasted words.

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

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

For a simple delete-by-key tool with one parameter and no output schema, the description fully covers what an agent needs to know: what it does, when to use it, and its relationship to sibling tools.

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

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

The schema coverage is 100%, and the description does not add meaning beyond the schema's parameter description. The single parameter 'key' is explained as 'Memory key to delete', which matches the description but provides no extra detail. Baseline score 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 explicitly states 'Delete a previously stored memory by key,' which is a specific verb and resource. This clearly distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

The description provides explicit guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember and recall', offering clear context against 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 and destructiveHint=false. The description adds process details (fetching, extracting) and output format ('single text blob'), providing useful behavioral context beyond annotations without 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 three sentences, front-loaded with action, process, and use cases. Every sentence is necessary 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?

The description explains the output format ('single text blob') since no output schema exists. It covers parameters (via schema), process, and use cases, leaving no critical gaps for a tool of this complexity.

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

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

Schema coverage is 100% with clear parameter descriptions (url, max_links with defaults). The tool description does not add extra meaning beyond the schema, so baseline score 3 applies.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying it fetches the page, extracts title/description/key links, and outputs standard markdown. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting own project, auditing competitor). It does not provide when-not-to-use or compare to alternatives, but the context is clear enough for the 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=true, idempotentHint=true, destructiveHint=false. Description adds that only active subscriptions are returned by default (unless include_inactive is true) and lists response fields. 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 efficient sentences: first states purpose and output, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

For a simple list tool with one optional parameter and good annotations, the description covers purpose, usage, response fields, and filtering. No output schema needed given fields listed. Comprehensive enough.

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?

Only parameter include_inactive is fully described in the schema (100% coverage). Description adds minimal extra meaning beyond implying default is active subscriptions. Baseline 3 is appropriate.

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

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

The description clearly states it 'List the caller's active subscriptions' with specific verb and resource. It distinguishes from sibling tools subscribe and unsubscribe by being a read-only listing operation.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use. Could be more explicit about when not to use, but 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?

The description discloses rate limiting, free usage, return of a claim_token, and the async read-back behavior. It also explains roadmap impact and daily digests. No annotations exist to contradict; the description adds rich behavioral context well beyond the generic annotation flags.

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 serves a purpose: usage, exclusions, token mechanics, rate limits, and quotas. It front-loads the core purpose before diving into details. While it could be tightened, the structure is logical and each clause adds value.

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

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

Given the tool's complexity (4 params, nested context object, no output schema), the description fully covers the return behavior via claim_token, how to later retrieve resolution, rate limits, and what to include. The message length max appears in the schema, so the description doesn't need to repeat it. This is a complete picture for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra semantics: the claim_token usage pattern with an example call, the flow of filing without an account, and concrete examples of pack/tool/vertical values. This goes beyond schema, though the schema already explains each parameter adequately.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by focusing on feedback for Pipeworx tools and explicitly contrasting with other MCP servers. The types (bug, feature, data_gap, praise) further clarify scope.

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

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

Explicit 'Use when' guidance covers bug, feature/data_gap, and praise scenarios. It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs to file elsewhere for other servers. This is exemplary usage differentiation.

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

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

Annotations already cover safety; description adds details on data source (CF analytics-engine), privacy (no PII), output structure ((pack, tool, count)), and caching (5min-1h).

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

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

Concise 5-sentence description that is front-loaded with return type and includes all essential info 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 a single optional parameter and no output schema, the description fully explains purpose, usage context, data provenance, and caching behavior.

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

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

Schema coverage is 100% with enum description; description adds context that shorter windows surface current hotness while longer windows show steady-state demand, enhancing parameter understanding.

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

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

Clearly states it returns top tools, packs, and call volume over a recent window, distinguishing from sibling tools focused on queries or 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?

Lists three specific use cases (discovering hot data, confirming canonical tool, alignment) but does not explicitly state when not to use or list 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?

The description provides extensive behavioral details: monotonicity checks, partition_sum logic, similarity thresholds, placeholder filtering, fill check with theoretical vs realizable edge, and response structure. Annotations (readOnlyHint: true, idempotent, non-destructive) are consistent and the description far exceeds annotation coverage, adding deep context about what the tool does under the hood.

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

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

The description is lengthy but well-structured with clear sections: modes, semantic anchor, partition filter, fill check. Every sentence adds necessary detail for a complex tool. Slightly verbose but justified given the depth of information. Front-loaded with main purpose.

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

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

Despite having only 2 optional parameters and no output schema, the description covers all necessary context: modes of operation, parameter usage, behavioral edge cases (similarity threshold, placeholder filter), fill check with criteria for not trading, and response structure (gap_pp, suggested_trade, etc.). It also references a sibling tool, making it self-contained and complete 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% but the description adds substantial meaning beyond field names and basic descriptions. For 'event' it gives examples of slugs and explains it walks child markets. For 'topic' it describes cross-event scanning and gives seed question examples. It explains how parameters affect behavior (e.g., cross-event mode catches patterns single-event misses). This adds significant value.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between no-args trending scan, single-event mode, and cross-event mode with specific examples. The purpose is specific and easily distinguishable from sibling tools.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains the semantic anchor, partition filter, fill check scenario when not to trade, and directs to polymarket_fill_risk for custom sizing. Comprehensive guidance with alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses many behavioral traits: model families, edge calculation, slippage subtraction, caching (1h), diagnostic output, Fed exclusion with rationale. 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 quite long and detailed, which is arguably necessary given the complexity. It is well-structured with sections and front-loaded purpose, but some redundancy exists (e.g., listing model families). Could be slightly more concise.

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

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

Given the tool's complexity (9 params, no output schema), the description is exceptionally complete. It explains not only what the tool does but also how results are structured, diagnostics, caching, caveats (Fed signal reliability), and parameter interactions.

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 significant value beyond the schema, such as explaining the interplay between min_kelly and min_partition_leg_kelly, the rationale for default slippage_pp, and how tradeable-edge knobs work.

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: scanning top Polymarket markets and returning opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan') and resource ('top Polymarket markets'), and distinguishes itself 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 explicitly states the tool is built for 'what should I bet on today' and explains how to use tradeable-edge knobs and parameter filters. While it doesn't explicitly say when not to use it, the context is clear and the detailed parameter explanations provide strong 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 indicate read-only, open-world, idempotent, and non-destructive. The description adds substantial context: it reads snapshots, computes trends and decay, explains response structure (tracked, expired, snapshot_dates), and notes limitations (60-day TTL, snapshot gaps). 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 (purpose, args, response, limits). It is verbose but every part adds value. Could be slightly more concise, but the structure aids readability.

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

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

Given the tool has no output schema, the description fully explains the response structure including tracked[], expired[], and snapshot_dates[] arrays. It also covers limitations (TTL, snapshot gaps) and interpretation of signed values. This is comprehensive for a data-fetching 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?

Both parameters (days, window) have schema descriptions, and the description adds default values, range, and valid families. This extra context helps the agent understand valid inputs beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal dynamics.

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

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

The description implies when to use (to assess edge age and decay) but does not explicitly state when not to use or compare with alternatives like polymarket_edges or bet_research. The context 'a fresh wide edge and a 3-week-old wide edge are different trades' provides some guidance but lacks explicit usage rules.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds significant behavioral context: it walks the order book, returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and warns about partial basket fills converting arb into unhedged directional positions. This goes well beyond what annotations convey.

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

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

The description is front-loaded with the core purpose and uses clear section headings (SINGLE-MARKET, BASKET) and emphasis (REQUIRES, USE THIS). It is verbose but each sentence adds necessary detail. The structure is effective for an agent parsing key points. Could be slightly tighter, but overall well-organized.

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

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

Given the tool's complexity (two modes, many output fields), the description covers all essential information: input modes, parameter behavior, expected outputs, and critical warnings about partial fills and directional risk. There is no output schema, so the description bears full burden and meets it comprehensively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters behave differently in single-market vs. basket mode, such as size_usd being interpreted as settlement notional for baskets, and side defaulting to auto based on partition sum. However, the schema already has reasonable descriptions, so the additional semantics are useful but not extensive. Score 4 reflects good supplementary context.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with specific verbs and parameters, and explicitly differentiates from siblings by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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 context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause directional risk) and implies when not to use (when trades are small or theoretical edge is capturable). No explicit alternatives are named, but the reference to sibling tools in 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 significant detail beyond annotations (readOnlyHint, etc.), including safety fields, compatibility warnings, and temporal alignment. No contradiction with annotations.

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

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

Well-structured and front-loaded, though slightly verbose. Every sentence adds value.

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

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

Given no output schema, description adequately explains response fields and safety warnings. Comprehensive for a 3-parameter tool.

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

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

Schema coverage is 100%, and description adds value by explaining the two modes, topic list, and override behavior.

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

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

Description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Provides clear context on when spreads are meaningful via compatibility_warning and temporal_alignment fields, but does not explicitly mention alternative tools.

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

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

Adds scoping detail (identifier-based) and pairing guidance beyond annotations. No contradictions with readOnlyHint or idempotentHint.

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 focused sentences, no waste. Front-loaded with purpose.

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

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

Fully covers a simple retrieval tool with one optional param and no output schema. Includes scoping, examples, and sibling pairing.

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

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

Schema coverage is 100%. Description adds meaning by explaining that omitting key lists all, and providing context for key usage.

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

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

Clearly states verb (retrieve/list) and resource (saved memories). Distinguishes from sibling tools (remember, forget) by explicitly pairing.

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 concrete examples of when to use (target ticker, address, research notes). Implicitly suggests when not to use (omit key to list all).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the returned fields (source, citation_uri, raw payload) and explaining the mark_read side effect, which is consistent with read-only behavior.

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

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

The description is concise at a few sentences, covering purpose, filter options, return fields, and usage context. It is front-loaded with the main action and includes all necessary information 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 the absence of an output schema, the description adequately explains what is returned and key parameters. It covers polling, filtering, and the mark_read flag, providing sufficient context for a read-only tool.

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

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

The input schema has 100% description coverage for all 5 parameters, but the description adds context by providing an example filter (e.g., 'sec_8k') and explaining the effect of mark_read, enhancing understanding beyond the schema alone.

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

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

The description clearly states it pulls fired events from a subscription feed, returning most recent alerts with specific fields like source and citation_uri. It differentiates from siblings by focusing on alert/event retrieval, which is distinct among the listed 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 provides explicit guidance on filtering by type and timestamp, setting mark_read, and mentions polling suitability. It also notes an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or contrast with siblings.

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

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

Annotations already indicate non-destructive, read-only, idempotent behavior. The description adds significant context: fan-out to multiple sources, fallback mechanisms, return structure (changes[] grouped by source, total_changes, citation URIs), and soft-fail for USPTO.

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

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

The description is moderately long but well-structured. It front-loads example queries and clearly separates sections. Every sentence adds value, though some minor redundancy exists (e.g., repeating the window concept). Still efficient.

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

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

Given no output schema, the description explains the return structure and behavior comprehensively. It covers all parameters, edge cases (relative dates, CIK vs ticker), and source fallbacks. Complete for a complex, multi-source 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%, so baseline is 3. Description adds extra meaning: 'since' accepts ISO or relative shorthand with examples, 'value' can be ticker or CIK, 'type' only supports company. This goes beyond what the schema provides.

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

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

The description explicitly states the tool's purpose as a change feed for a company over a recent time window, with specific verb+resource (retrieve changes) and clear scope (multiple sources). It distinguishes from sibling 'entity_profile' which is for static profiles.

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

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

Provides explicit when-to-use guidance, including the alternative 'entity_profile' for static profiles. Also describes fallback behavior between GDELT and GNews, and soft-fail for USPTO, helping the agent decide when to invoke this tool.

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

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

Description adds scoping by identifier, persistence duration (persistent for authenticated users, 24h for anonymous), and the storage mechanism (key-value pair). Annotations provide idempotentHint and destructiveHint; description complements well without contradiction.

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

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

Four sentences, each with distinct value: purpose, usage context, behavioral details, and related tools. No redundant or unnecessary information.

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

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

Given low complexity (2 params, no output schema), description covers purpose, usage, persistence, scope, and related tools. No gaps identified.

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. Description repeats that it stores key-value pairs but does not add additional syntax or constraints beyond the schema's parameter descriptions.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource. It distinguishes from siblings by mentioning paired tools 'recall' and 'forget'.

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

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

Explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also outlines persistence differences and alternative tools.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds valuable behavioral details: graceful degradation of LEI/FIGI enrichment, explicit listing of unresolved identifiers, source labeling, and internal cascading through lookup endpoints.

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: it opens with query patterns, then the core purpose, then supported types with internal subsections. Each sentence adds information, but the multiple paraphrased examples could be trimmed without losing intent.

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

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

With no output schema, the description fully covers the expected outputs for both entity types (CIK, ticker, LEI, FIGI, RxCUI, etc.), including fallback behavior and source provenance. It is complete for the tool's complexity.

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

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

Even though schema coverage is 100%, the description enriches both parameters substantially: type=company explains the cross-source identity spine (CIK, LEI, FIGI, ISIN mapping) and accepted input formats; type=drug details RxCUI, ingredient, and brand. This goes far beyond the bare schema.

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

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

Clearly states the tool resolves a user-spoken NAME to canonical/official identifiers, with a specific verb and resource. Distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID' and by outlining supported entity types.

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 when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and context about replacing 2-3 manual lookups, but does not explicitly name alternative tools or when-not scenarios.

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

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

Annotations declare safe read-only, open-world, idempotent hints. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density per entity. 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?

Three sentences: first states purpose, second explains mechanism, third provides use case and output summary. Every sentence adds value; no fluff.

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

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

Given no output schema, the description adequately covers output structure. It lacks mention of error handling or constraints (e.g., entity count limit of 2-8), but overall is sufficient for a 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%, but the description adds meaning by specifying that the first entity in 'entities' is treated as the 'subject' for narrative and that 'context' disambiguates names. This goes beyond the schema descriptions.

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

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

The description clearly states the verb 'Compare AI visibility across multiple entities side-by-side,' specifying the resource (entities) and action (compare). It distinguishes from sibling tool ai_visibility_check by emphasizing multiple entities and ranking.

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

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

The description provides context for use ('competitive AI-marketing audits') and gives an example question. However, it does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single-entity checks.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds critical behavioral details: the tool fans out across two external services, bundlephobia's first measurement can take 5-30s, and partial failures are handled gracefully with a sources_failed list. No contradictions with annotations.

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

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

The description is dense but well-organized: starts with the core purpose, then usage, then return structure, then limitations. Every sentence contributes information. Slightly verbose due to parenthetical examples and ecosystem notes, but still efficient for the information density.

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 composite tool with no output schema, the description thoroughly covers what is returned (summary block, per-advisory detail, links, alternative versions), ecosystem restrictions, and failure modes. It leaves no obvious gaps for an agent to invoke or interpret the result.

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

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

Schema coverage is 100%, so the description does not need to add meaning for parameters. It echoes the schema's info about defaults and mentions scoped packages, but this adds minimal value beyond what is already in 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's composite function: a single call to check npm package advisories, license, version history, and bundle size. It explicitly distinguishes from sibling tools that may cover other ecosystems or different scanning purposes, and names the external services used (deps.dev, bundlephobia).

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 when-to-use examples ('is X safe / popular / small') and when-not-to-use (other ecosystems like PyPI, Maven, Cargo, Go, which fall under deps.dev:version directly). Also notes graceful degradation and potential delays, guiding the agent on expectation.

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, idempotent, read-only behavior. The description adds beyond: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars) with truncation flag, and return format (passages with offsets and similarity scores). No contradictions.

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

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

The description is concise yet comprehensive: 5 sentences covering purpose, use case, pairing, and technical details. No wasted words; every sentence adds information. Front-loaded with the core 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?

Despite having no output schema, the description explains the return value (top-N passages with character offsets and similarity scores) and mentions truncation behavior. For a tool with 3 parameters and no output schema, this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the max character limit for 'text', providing example queries for 'query', and noting the range and default for 'limit'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool does semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes it from general search by noting it saves context when the record is too large. The verb 'search_within' and resource 'a source' are well-defined.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. It also mentions a complementary tool (ask_pipeworx_grounded) and explains how to pair them. This provides clear context for the AI 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=true and destructiveHint=false, so description adds value by explaining the tool queries packagephobia.com and returns sizes in bytes including dependencies. No contradictions with annotations.

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

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

Single sentence with no redundancy. Front-loaded with key information about what is returned and from where.

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

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

Given the simple tool with 2 well-documented parameters, rich annotations, and an output schema (exists), the description fully covers what the tool does without missing critical information.

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

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

Schema coverage is 100%, with both parameters having descriptions. The description adds minimal parameter-specific meaning beyond restating that version is optional and default is latest. The mention of 'packagephobia.com' provides external context but not parameter semantics.

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

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

Description explicitly states verb 'Return', resource 'publish size and full install size', and source 'npm package name and optional version via packagephobia.com'. It clearly distinguishes itself from sibling tools, none of which perform this specific 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?

Description does not provide explicit guidance on when to use this tool versus alternatives. While the tool's purpose is clear, there is no mention of prerequisites, when to avoid, or related tools. However, given its unique function, the need for such guidance is lower.

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

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

The description discloses behavioral traits beyond annotations: persistence requirement (OAuth), type-specific parameter examples, delivery channel details (always-on feed, optional email/sms/webhook with limits 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 and front-loaded with purpose and requirements. It is slightly long but every sentence adds value. No unnecessary repetition.

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 3 params, nested objects, multiple types and delivery options, the description is complete. It covers all types, channels, constraints, and return value. No output schema exists, but return value is stated.

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 richer meaning with concrete examples for each type and delivery constraints. Adds value beyond schema descriptions.

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

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

The description clearly states the verb 'create' and the resource 'subscription', specifies it returns the new subscription id, and lists supported types. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context: requires Pipeworx OAuth, types with example parameters, and delivery channels. It does not explicitly state when NOT to use, but the context is sufficient to guide selection.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description reveals that the tool returns 'category-bucketed example questions' with 'exact tool + argument shape', and that it draws from a 'live catalog of thousands of tools'. This adds behavioral context not present in 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 lengthy but well-structured: starts with example queries, then explains the output, then usage. Every sentence adds value, but the list of categories could be slightly trimmed without losing clarity. Still, it's appropriately detailed.

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 purpose, usage, parameter behavior, and output format. With one optional parameter and no output schema, the description is fully sufficient for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the topic values (finance, pharma, etc.) and explaining the behavior when omitted, enhancing 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 explicitly states the tool is the onboarding entry point for Pipeworx, listing synonymous questions like 'What can I ask Pipeworx?' and 'what is Pipeworx good for?'. It clearly distinguishes from siblings by focusing on getting started and learning what questions to ask, contrasting with tools like 'discover_tools' 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?

The description provides explicit usage instructions: 'Call with no arguments for the full spread, or pass `topic` to focus.' It also advises 'Use this FIRST when you do not yet know what Pipeworx can do for you', offering clear when-to-use guidance.

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

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

Adds value beyond annotations: ownership enforcement, soft-delete (deactivated not deleted), and retention of historical events. Aligns with idempotentHint and destructiveHint. 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 sentences, front-loaded with main action. No wasted words. Efficient and clear.

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?

Simple tool with single parameter; description covers purpose, behavior, side effects, and references sibling tool. Complete for correct agent invocation.

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 already explains the id parameter. Description adds 'by id' but no new semantics beyond schema. Baseline 3 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?

Clearly states action (cancel), resource (subscription), and identifier (by id). Distinguishes from sibling tools like subscribe and list_subscriptions by specifying cancel and ownership enforcement.

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?

Tells when to use (cancel a subscription), who can use (only own subscriptions), and what happens (deactivated, not deleted). Implicitly guides away from non-own subscriptions and points to recent_alerts for history. No explicit when-not to use, but adequate.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, so the description adds the crucial behavioral nuance of verdict semantics: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim.' It also discloses error handling via verification_error and the fallback from EDGAR to the grounded pipeline, going well beyond annotation-provided safety signals.

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 fairly long but each sentence adds distinct value: trigger phrases, usage rule, routing logic, verdict semantics, error differentiation, and a replacement note. It is front-loaded and structured so the agent quickly understands when to invoke it, and the extra length is justified by the tool's complexity.

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

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

There is no output schema, so the description must explain return values; it does, enumerating the verdict types, the actual value with citation, and reasoning. It also covers the two pipeline paths and the error case, making it sufficiently complete for reliable tool selection and invocation.

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 behavior beyond the schema: it explains that tolerance_pct overrides wording-implied tolerance, recommends 1–2% for hallucination detection, and states a default cap of 5%. This enriches the bare schema definition with operational guidance.

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

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

The description opens with concrete natural-language trigger phrases and states the tool performs claim verification against authoritative sources. It explicitly distinguishes company-financial claims via SEC EDGAR/XBRL from other facts, and names the verdict types, making the tool's function unmistakable and distinct from sibling tools like deep_research or ask_pipeworx.

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

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

The description provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic and notes it replaces multiple sequential calls, but it does not name specific alternative tools or state when not to use it, so it stops short of a 5.

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