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?

Annotations already mark the tool read-only, idempotent, and open-world, so the safety profile is covered. The description adds useful behavioral context: it routes across 1,506 verified sources, auto-fills arguments, and returns structured answers with stable citation URIs.

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

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

The description is front-loaded with the key preference over web search and a clear domain list, but it is long and the tail becomes bloated and confusing, repeating 'single best answer' and listing near-identical beta variants. Some examples are valuable, but the ending could be trimmed.

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 general router with no output schema, the description explains what the tool takes (natural-language question), what it does (routes and fills arguments), and what it returns (structured answer with citation URIs). It lacks details on error behavior or output shape, but provides enough context for an agent to invoke it 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% and the schema fully documents question plus its aliases, so the description does not need to explain parameters. The examples illustrate appropriate question values but add no parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: it routes natural-language questions to one of 5,767 tools over verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It distinguishes the tool from web search and gives a concrete domain list, but the ending is muddled and does not cleanly separate this tool from ask_pipeworx_grounded or the beta siblings.

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

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

The description gives explicit when-to-use criteria: prefer over web search for authoritative/current/historical data, use for trigger phrases like 'look up', 'get the latest', and 'current', even when web search could work. It names ask_pipeworx_grounded as the evidence-focused variant, but the guidance for beta_multi/beta_single is repetitive and unclear.

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 beyond the readOnlyHint=true and idempotentHint=true annotations by explaining the beta nature: no candidate is currently active, it behaves identically to ask_pipeworx right now, it does not fall back to anything else (it is a full working router), and its purpose is comparison against the stable router. This is meaningful context an agent needs before calling a beta variant.

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

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

The description is thorough but every sentence earns its place: it identifies what the tool is, what currently differs, how to use it, and what results are used for. It is front-loaded with the most important fact (beta version of ask_pipeworx) and does not waste 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 read-only, idempotent, non-destructive query tool, the description covers the safety profile via annotations, the routing semantics, the current operational state, and the relationship to the stable sibling. The output schema is absent, but the description explicitly states the response shape is identical to ask_pipeworx, which fully compensates.

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

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

Schema description coverage is 100% and the schema already documents every alias and the main 'question' parameter. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline 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 identifies this as the beta version of ask_pipeworx with the same universal routing function and even quantifies the scope (5,767 tools). It distinguishes itself from the stable ask_pipeworx primarily by its experimental nature and live routing improvements, though it doesn't explicitly name ask_pipeworx as the sibling to compare against.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It lacks an explicit 'when not to use' statement, but the context of beta/experimental candidate routing is clear enough for an agent to decide between this and the stable sibling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description adds substantial behavioral context beyond that: it returns a structured {answer, evidence, confidence, source, fetched_at, refusal_reason} payload, enforces closed-world extraction from tool results, and enumerates explicit refusal reasons. It also discloses the cost tradeoff of one extra LLM call. 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 dense but every sentence earns its place: purpose, routing, extraction behavior, return contract, refusal semantics, use cases, and cost tradeoff are all covered without redundancy. It is front-loaded with the core differentiator, 'Hallucination-resistant answer mode,' before diving into mechanics.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it specifies the return shape, refusal reasons, grounding constraint, cost, and when to prefer the sibling tool. An agent can decide whether to invoke this tool and understand what it will receive without needing additional documentation.

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

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

Schema description coverage is 100%, so the input schema fully documents the question parameter and its aliases. The description does not add parameter-level detail, but the baseline of 3 is appropriate because the schema carries the semantic load sufficiently.

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

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

The description states a specific, differentiated purpose: a hallucination-resistant, grounded answer mode for high-stakes reads that picks and fills the right tool, fetches data, and extracts answers only from tool results. It names the sibling ask_pipeworx and clarifies that it uses the same routing but adds grounded extraction, so an agent can distinguish it from all 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 gives explicit when-to-use guidance: use whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples such as financial verdicts, legal claims, medical lookups, and public statements. It also states when not to use it, directing casual lookups to ask_pipeworx because of the extra LLM call cost.

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?

Adds substantial behavior beyond annotations: auth/paywall requirements, parallel routing to 5,767 tools, gaps[] never invented, citation_uri only when resolvable, semantic excerpting of large records, contradictions[] scans, hop behavior, and latency expectations. No annotation 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?

Front-loaded with auth requirements and the alternative tool, and organized into clear FORK/section headings. It is long and repeats the paid-plan constraint and return-packet details, so it is not maximally concise, but the structure makes the detail navigable.

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 still explains the return packet's fields, auth tiers, depth variants, latency, and alternatives. Nothing essential for correct invocation is missing.

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

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

The schema already documents both parameters well, so the baseline is 3. The description adds useful examples for the question parameter and reinforces depth-tier semantics with hop, cost, and latency details, slightly exceeding what the schema alone provides.

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

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

The description names a specific action and resource: grounded multi-source research across Pipeworx's 1506 structured data sources, and explicitly states 'this is NOT open-web search'. It also distinguishes itself from ask_pipeworx, so an agent can tell what deep_research is for.

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: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'. It also clarifies depth tiers, including the paid restriction on thorough.

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?

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds meaningful behavioral details: sources_used/sources_failed distinguish 'no data' from bugs, empty FDA sections are expected for small-molecule-only companies, and name resolution via SEC EDGAR is explained. This substantially exceeds what annotations alone 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 long and dense, but the content is front-loaded with intent examples and every clause carries operational detail. It would benefit from more structured formatting, but it does not waste words given the complexity of the tool.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, and it does so thoroughly: fields like cik, resolved_from/resolved_to, recent_filings, fundamentals, sources_used, and sources_failed are enumerated. It also covers fallback behavior and expected no-data cases, making it sufficiently complete for an agent to invoke and interpret 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%, and the description still adds value by explaining that 'company' and 'ticker' are interchangeable, that value can be a ticker, zero-padded CIK, or company name, and how name resolution behaves. This goes beyond the baseline expected from a fully documented 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 opens with concrete user phrasings and then states a specific function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chaining single-source lookups, and the resource (company profile) and scope (US public companies) are explicit.

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

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

The description gives direct routing guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies boundary cases such as private companies returning resolved:false with a notes line, so an agent knows when this tool is appropriate and what to expect outside its scope.

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?

While annotations already mark the tool as readOnly and non-destructive, the description goes well beyond them by disclosing important behavioral details: safety fields and codes, probability of spurious pairings via keyword matching, temporal alignment pitfalls, gross vs. net fee treatment, and skipped-leg counters. It also warns that empty compatibility_codes are not guaranteed, and that unresolved temporal months must be checked manually. This is rich behavioral disclosure beyond what structured 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 dense and lengthy, but nearly every sentence conveys necessary detail: modes, safety fields, fee caveats, temporal alignment semantics, and skipped-leg counters. It is front-loaded with the core purpose and organized with labeled sections (RESPONSE, SAFETY FIELDS, codes, skipped counters). It loses a point only for being somewhat overwhelming in a single block, but the structure is still strong.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, safety fields, compatibility_codes, temporal_alignment, fees_note, and skipped-cross counters. It also covers edge cases like unclassified legs being excluded and low-confidence pairs being returned only for inspection. The description is complete enough for an agent to invoke the tool and correctly interpret its response.

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 covers all three parameters with descriptions, so the baseline is 3. The description adds meaningful semantics by explaining the two-mode operation, the behavior of explicit parameters as overrides, and the shared token-overlap logic across modes. It also clarifies that zero parameters are valid (the topic mode), which is not apparent from 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 opens with a precise definition: "Cross-venue spread between Kalshi and Polymarket for the same resolving question," with a specific verb and resource. It also clearly distinguishes the two operational modes and explains what the tool computes in both modes, leaving no ambiguity about its purpose relative to other market 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 usage context by detailing the two modes (topic shortcuts vs. explicit ticker/slug) and instructs readers that "BOTH modes run the identical token-overlap matcher." It also gives practical caution that "most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable." It does not explicitly compare against sibling tools like polymarket_arbitrage, but it gives clear enough context for when to invoke this tool and how to interpret its results.

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?

Beyond the read-only/idempotent annotations, it discloses several important behaviors: ambiguous names return figi_candidates and assert nothing, unresolved identifiers are listed explicitly under unresolved, and LEI/FIGI enrichment degrades gracefully if upstream services fail. It also reveals internal cascade behavior and precise matching semantics (exact ticker map vs name search), which materially changes how an agent interprets results.

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 and dense, but it is structured and front-loaded with a recognizable user-query preamble and a direct 'Use FIRST' directive. Some parentheticals are heavy, so it is not maximally concise, but few sentences are wasted.

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 carries the burden of explaining what is returned; it does so in detail, including source labeling, unresolved fields, candidate lists, and graceful fallback. It also specifies coverage limitations (non-US issuers, non-equity instruments) and input constraints, so an agent can predict behavior across failure and ambiguity cases.

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

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

Although the schema already covers both parameters, the description significantly extends their meaning: it lists accepted input forms for company (ticker, CIK, ISIN, or name), explains how ISIN resolves via GLEIF, and warns against trailing security-class words for bond lookups with a concrete example. This is the kind of nuance an agent needs to pass values correctly.

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

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

The description names a concrete action—resolving user-spoken names to canonical/official identifiers—and specifies the entity types (company, drug) and identifier systems involved. It also distinguishes itself from generic entity-related siblings by framing the tool as the name-to-ID mapping step that feeds other 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?

It gives explicit trigger conditions ('Use FIRST whenever you have a name but need an ID') and many example phrasings. It does not explicitly name a when-not-to-use alternative such as entity_profile, so the exclusion is only implied by the 'need an ID' condition.

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.