Peopledatalabs

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

The description goes beyond the annotations by disclosing the default model (Workers AI Llama-3.3-70b), the cost implication of passing _apiKey ('you pay Anthropic directly'), and the return structure. These behavioral details are not present in the annotations and are important for cost and expectation management.

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

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

The description is three sentences with no extraneous wording. The first sentence states the core function, the second covers defaults/cost/return format, and the third lists use cases. Every sentence earns its place and it is front-loaded with the primary action.

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

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

The description covers purpose, parameters, default behavior, cost, return format, and use cases, which is substantial for a tool without an output schema. It includes the per-model return structure and combined view. A minor gap is the lack of explanation for what 'signals' contains or how scoring works, but that is not necessary for invoking 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?

The input schema has 100% coverage for all four parameters, so the baseline is 3. The description only reinforces that _apiKey enables Anthropic probing and that the default model is Workers AI, which is already stated in the schema. It adds no meaningful new 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?

The description uses the specific verb 'Probe' and clearly identifies the resource (one or more LLMs) and the output (visibility score 0-100). It is specific and unambiguous. However, it does not explicitly distinguish this tool from sibling tools like scan_competitor_ai_presence or compare_entities, so it falls short of a 5.

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 specifies concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use the tool. It does not mention exclusions or alternative tools, but the provided use cases are enough to guide an agent.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: routing to 5,462 tools, filling arguments, returning structured data with pipeworx:// citation URIs, and being a fast default entry point. This adds significant context about how the tool operates and what the agent can expect.

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 every sentence earns its place: it front-loads the key directive ('PREFER OVER WEB SEARCH'), then lists domains, explains mechanics, gives examples, and closes with alternatives. It is well-structured and not redundant.

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 routing tool with no output schema, the description completely covers behavior, use cases, and output format (structured answer with citations). It also situates the tool among siblings, making it fully self-contained for an agent to decide when to invoke it.

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 already explains aliases and provides examples. The description reinforces the expected input as a natural language factual question but does not add substantive parameter-level meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it routes questions to the right tool among 5,462 across verified sources, fills arguments, and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by stating when to use each.

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 extensive usage guidance: 'PREFER OVER WEB SEARCH', 'USE whenever...', and explicitly lists when to step up to alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). Also handles edge cases like news queries.

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?

Goes beyond the annotations by disclosing the experimental live-testing behavior, current inactive candidate status, identity with ask_pipeworx, and that it is a full working router, not a fallback. This is rich behavioral context that annotations alone do not provide.

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

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

Four sentences, each providing meaningful information about the beta status, current equivalence, usage, and behavior. Slightly verbose but no filler; the structure flows logically from definition to current state to usage guidance.

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 question-routing tool with no output schema, the description covers purpose, usage, current behavior, and relationship to the stable router. It mentions the response shape is identical to ask_pipeworx, compensating for the missing output schema. Lacks explicit error/edge-case info but that's minor.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for question. The description adds no parameter-specific details, only stating 'same arguments' as ask_pipeworx, which is redundant given the schema. 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 defines this as a beta version of ask_pipeworx, a universal router with the same toolset and arguments. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental routing status and current exact match.

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 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use condition. It also clarifies that no candidate is active now, so it matches the stable version, and notes that results are compared to the stable router for merge decisions.

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 read-only, open-world, idempotent, non-destructive hints, but the description adds substantial beyond that: the refusal behavior with specific refusal_reason enums, the verbatim evidence quote, the extra LLM call cost, and the constraint to only use tool result content. No contradictions with annotations.

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

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

The description is longer than two sentences but every sentence carries unique value: purpose, return format, refusal format, usage guidance, and cost tradeoff. It is well-structured and front-loaded with the core concept, though slightly dense.

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

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

With no output schema, the description fully specifies the return format and failure modes. It covers routing, scope (5,462 tools across 1419 sources), usage contexts, alternatives, and cost implications, making it complete 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 all parameters documented as aliases for 'question'. The description adds no parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode that extracts answers only from tool results, explicitly distinguishing it from the sibling ask_pipeworx by highlighting the additional extraction step and refusal mechanism. The verb 'ask' and resource 'Pipeworx' are present, with 'grounded' indicating the safe-mode variant.

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 it ('whenever an answer will be quoted, cited, or acted on') and provides a direct alternative preference ('prefer ask_pipeworx for casual lookups') with a cost-based reason. Also notes it routes identically to ask_pipeworx, clarifying the relationship.

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

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

The description goes far beyond the annotations (readOnly, idempotent) by detailing resolver contract (market_match_confidence, score, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), spread warnings (illiquid_wide_spread), cancellation-rule risk, and news fallback behaviors. It also explains what happens on closed/dead markets. Annotations are consistent, so no contradiction.

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

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

The description is long but highly structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). Each section delivers essential information for a complex tool, and there is no redundant filler. It is dense but every sentence earns its place; slightly more conciseness could be achieved, but complexity justifies the length.

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

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

No output schema is present, so the description fully carries the burden of explaining response shapes: result.market fields, result.analysis with model_probability and edge_pp, result.evidence keyed by source, parent_event for partition bets, and status codes. It also covers edge cases like illiquid spreads, closed markets, and cancellation rules, making the tool safe and usable for an AI agent.

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

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

Schema coverage is 100% with parameter descriptions for market, depth, and include_raw. The description adds meaningful context beyond the schema by explaining how the market parameter is resolved, how depth affects fan-out with concrete examples (BTC, Fed, Hormuz, Yankees), and the tradeoff for include_raw (response size). This enriches parameter understanding without repeating schema details entirely.

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+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further explains the resolution, classification, fan-out, and return of an evidence packet. This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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

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

Explicit use cases are given: 'Use for “should I bet on X”, “what does the data say about Y”, or “is there edge in Z”.' This provides clear when-to-use context. However, there are no explicit when-not-to-use instructions or named alternative tools, so it doesn't reach the full 5.

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

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

Annotations already mark it read-only/idempotent, but the description adds meaningful behavioral context: SEC EDGAR/XBRL source, off-calendar fiscal year handling, FAERS/approval/trial counts for drugs, sorting by primary metric, and citation URIs. This goes well beyond the structured annotations.

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

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

The description is dense but every sentence carries functional value: triggers, core purpose, preference rule, per-type data details, sorting behavior, and return format. It is front-loaded with the most critical usage guidance.

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

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

Despite lacking an output schema, it tells the agent what to expect ('paired data + pipeworx:// citation URIs per entity') and explains data sources, sorting, and scope. For a 2-parameter tool, this is a complete picture.

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 enriches both parameters: 'type' semantics are explained with concrete data pulled per entity type, and 'values' usage is demonstrated with ticker/name examples and the 2–5 count. This adds real value beyond the raw schema.

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

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

The description opens with explicit trigger phrases and a crisp definition: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly differentiates from sequential single-entity lookups and sibling tools, stating it replaces 8–15 sequential lookups.

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

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

It gives explicit when-to-use signals via natural-language examples and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also breaks down behavior by type (company vs. drug), effectively directing usage per request.

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 convey safety hints, and the description adds substantial behavioral context: decomposition, parallel routing, gaps[] for unanswered facets, contradictions[], 'never invented,' latency expectations, semantic excerpting, and a hop/citation_uri structure. This goes far beyond what annotations alone provide, and nothing contradicts the readOnly/openWorld/idempotent hints.

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 every sentence earns its place by providing actionable information: account requirements, alternatives, output structure, latency, and depth semantics. It is front-loaded with a critical prerequisite (account required) and clearly scopes the tool as structured research, not open-web search. It could be tightened, but the detail is justified given the tool's complexity and lack of an output schema.

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 fully specifies the return shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap/contradiction behavior, iteration semantics, latency, auth requirements, and differences from ask_pipeworx. An agent has everything needed to decide when to invoke this tool and what to do with 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% and the schema descriptions are informative, so the baseline is 3. The description adds real value by explaining depth tiers in terms of facet counts and behavior ('quick=3 (single hop), standard=5 ... thorough=8 ... re-angles unanswered facets'), plus the paid-plan constraint for 'thorough,' which enriches 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 core function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources ... in ONE call.' It also distinguishes itself from siblings by emphasizing it decomposes questions, routes to 5,462 tools in parallel, and returns a findings packet, making it unmistakably different from 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 when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It even instructs unsigned-in users to use ask_pipeworx instead, which is exactly the kind of decision support an agent needs.

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 (readOnly, idempotent, non-destructive), the description explains that results include names, descriptions, and full input schemas with curated examples, and that results are 'ready to call directly, no second schema lookup needed.' This is valuable behavioral context about the return format that annotations do not provide.

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

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

The description is front-loaded with the core purpose and includes a long list of example data domains, which is informative but somewhat lengthy. Each sentence earns its place: the list helps the agent understand scope, and the final sentence gives critical usage guidance. Slightly verbose but not wasteful.

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 is a meta-tool for discovering other tools, the description fully explains what it returns (top-N tools with schemas and examples), how to use it (natural language query), and when to call it (first). With rich annotations and a 100% covered schema, this is complete for an agent to invoke confidently.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds the concept of 'top-N most relevant tools' which corresponds to the limit parameter, but does not add meaningful semantics beyond what the schema already provides. No compensation needed.

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 'Find tools by describing the data or task' which clearly states the verb (find) and resource (tools). It explicitly distinguishes this from siblings by positioning it as a discovery/search tool for the agent's toolset, not a domain-specific data tool.

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

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

It provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This makes the use case crystal clear and implicitly advises against using it when the agent already knows the specific 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?

The description adds substantial behavioral context beyond the annotations: it details the sources fanned out (SEC EDGAR, XBRL, USPTO, news, GLEIF), the specific fields returned, the limit of up to 5 filings, and includes graceful degradation notes like the PatentsView API sunset with soft-fail and GDELT→GNews fallback. This is highly transparent and beyond what readOnly/openWorld/idempotent hints 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 information-dense and includes many concrete examples, but it's structured as a single long run-on paragraph with semicolon-separated return field details, which makes it less scannable than it could be. Still, every section adds value, and the front-loaded example queries help with pattern matching, so it's slightly above average.

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

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

With no output schema, the description fully explains the return values in detail: CIK and company name, recent filings with URIs, fundamental fields with ordering, patent status, news fallback chain, and LEI. It also covers edge cases like name resolution and accepted input formats, making the tool's expected behavior completely clear for an AI agent.

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

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

Schema description coverage is 100%, and the schema already thoroughly describes both parameters with type restrictions, examples, and the caveat that names are unsupported. The description only repeats the same parameter guidance (e.g., 'Pass ticker "AAPL" or zero-padded CIK') without adding new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: building a full cross-source profile of a US public company in one parallel call, with examples like "Tell me about X" and "research Acme". It distinguishes itself from sibling tools by explicitly saying it should be preferred over chaining single-pack SEC/XBRL/news lookups for holistic queries, making its specific use case obvious.

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

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

The description provides explicit when-to-use guidance: use for holistic company profile requests, prefer it over chaining individual lookups. It also gives clear exclusions: names are not supported, and users should use resolve_entity first if they only have a name, along with the exact input format (ticker or zero-padded CIK).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the safety spectrum. The description adds that a 'previously stored memory' is deleted, which clarifies the target resource, but falls short of explaining behavior beyond that, such as irreversibility or errors on missing keys.

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 main verb, and is compact with no filler. Every sentence adds value: the first defines the action, the second provides usage context and sibling relationships.

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 single-key delete with annotations handling destructive and idempotent flags, so the description doesn't need to re-explain those. It covers purpose and usage, though it omits what happens if the key does not exist, but that is not critical for a minimal delete operation given the 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?

The input schema has 100% coverage for the only parameter, including a description 'Memory key to delete'. The description repeats 'by key' but adds no new syntax, formatting, or edge-case semantics beyond the schema, so the baseline of 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 opens with 'Delete a previously stored memory by key', a specific verb and resource that clearly states the tool's function. It also distinguishes from siblings by explicitly pairing with 'remember and recall', clarifying the memory lifecycle.

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 scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also names related tools 'remember and recall' as companions, but does not explicitly state when not to use the tool.

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

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

Annotations already signal readOnly/idempotent/non-destructive behavior, so the bar for additional disclosure is lower. The description adds useful process details: it fetches the page, extracts title/description/key links, and outputs a single text blob ready for site-root/llms.txt. This goes beyond annotations without contradicting them.

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

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

Three sentences, front-loaded with the primary purpose, and every clause adds value. It covers the process, output format, and use cases without fluff or redundancy.

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

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

For a tool with only two simple parameters and no output schema, the description sufficiently explains the output (single text blob) and the input (any URL). It could have mentioned edge cases (e.g., JS-heavy pages) but is largely complete given the tool's complexity.

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

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

Schema coverage is 100% and both parameters (url, max_links) are well-described in the schema. The description mentions 'any URL' and 'extracts ... key links' but adds no new meaning for the parameters beyond what the schema already 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 states the tool generates a production-ready llms.txt file for any URL, with a specific verb+resource (generate file) and the purpose (AI crawler indexing). It distinguishes itself from siblings by focusing on producing the actual file format, unlike ai_visibility_check or scan_competitor_ai_presence which likely analyze presence rather than create a deliverable.

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 'Useful for' scenarios (client indexing, own project drafting, competitor auditing) that effectively communicate when to use the tool. However, it does not mention alternatives from sibling tools or when not to use it, stopping short of a fully explicit when/when-not comparison.

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 value beyond these by stating that only the caller's subscriptions are listed and by enumerating the return fields (id, type, params, created_at, last_fired_at, fire_count), which gives the agent a clearer picture of the response.

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

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

Two concise sentences, with the main purpose front-loaded. Every word earns its place, and the description is easily scannable.

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

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

The description is complete for this simple tool: it specifies scope, return fields, and usage context. Even without an output schema, the field enumeration compensates. No notable gaps.

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

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

Schema description coverage is 100% for the sole parameter include_inactive, which is fully explained in the schema. The description does not add any extra parameter semantics, so the 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 uses 'List' with the specific resource 'subscriptions' and limits scope to 'the caller's active subscriptions'. This clearly distinguishes it from sibling tools like subscribe and unsubscribe, and the phrase 'Returns id, type, params...' clarifies the tool's function.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use it, though it does not explicitly mention alternatives or exclusions.

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

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

Annotations already flag readOnly, idempotent, openWorld, non-destructive behavior. The description adds behavioral value by specifying the exact return fields and the input requirement (name and/or website), plus an example invocation. It does not contradict the annotations and provides useful context beyond them.

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

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

Two concise, information-dense sentences plus a compact example. The opening sentence establishes the core action and source immediately, and every element earns its place without redundancy.

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

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

For a simple 3-parameter external lookup with no output schema, the description covers purpose, inputs, output fields, and usage example. The annotations provide safety traits, and the description fills all necessary operational details for an agent to select and invoke 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?

All 3 parameters are fully described in the schema, so baseline is 3. The description adds extra meaning by clarifying that 'name' and 'website' are alternatives ('and/or') and providing a usage example that shows parameter interplay, which goes beyond the schema's individual field 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 'enriches a company' using People Data Labs and lists the specific output fields (size, employee count, industry, founding year, location, LinkedIn, website). This distinguishes it from the sibling 'pdl_person_enrich' which targets individuals.

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: supply a company name and/or website to get enrichment data. It includes a concrete example. However, it does not explicitly mention when NOT to use it or point to the sibling 'pdl_person_enrich' as the alternative for person data.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior. The description adds useful context about what fields are returned (job title, company, emails, etc.) and the constraint 'Provide at least one identifier', which goes beyond the annotations. It does not describe potential error cases or rate limits, but that is acceptable given the strong annotation coverage.

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

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

The description is two sentences plus an example, with no wasted words. It front-loads the main purpose and immediately follows with a concrete usage example, making it 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?

Given the 100% schema coverage, annotations, and no output schema, the description adequately explains the tool's purpose, inputs, and return fields. It lacks details on error handling or match quality, but for a straightforward enrichment API this is sufficient. It falls just short of 5 because it doesn't mention what happens when no match is found.

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

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

Schema coverage is 100% (all 7 parameters documented). The description adds key nuance beyond the schema by indicating that email, LinkedIn, name+company, and phone are valid identifiers, and implies that name alone or company alone may not suffice. It also provides an example using _apiKey, which reinforces the parameter usage.

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

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

The description clearly states 'Enrich a person from their email / LinkedIn / name+company / phone' using a specific verb and resource, and lists the return fields (job title, company, emails, phone numbers, location, skills). This distinguishes it from the sibling tool pdl_company_enrich by focusing on 'person' data.

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

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

It provides clear context on when to use the tool (to enrich a person from one or more identifiers) and gives input options. However, it does not explicitly mention when not to use it or point to alternatives like pdl_company_enrich, so it misses a 5.

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

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

With annotations all set to false, the description carries the full burden of behavioral disclosure. It goes above and beyond by explaining the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and human-read cycle ('team reads digests daily'). It even cautions not to paste end-user prompts, which is an important behavioral constraint. 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 longer than average but every sentence serves a purpose: purpose, usage, exclusions, claim_token flow, rate limit, and context. It is front-loaded with the primary action and structured logically. Slightly verbose, but the density of actionable detail justifies the length, earning a 4 rather than a 3.

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

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

The tool has 4 parameters, no required params, a nested object, and no output schema. The description explains the unusual claim_token round-trip and gives operational context (daily digests, roadmap impact). It does not explicitly state the exact response structure, but for a feedback tool the output is straightforward and the description mentions what to expect ('returns a claim_token', 'read whether it was fixed'). Given the complexity, this is a solid 4.

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 baseline is 3. The schema already explains each parameter and enum value. The description adds context about claim_token usage via a follow-up call, but this is largely redundant with the schema's own description. It does not introduce new parameter-level meaning beyond what the schema provides, so a 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 opens with a clear, specific verb-resource pairing: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This immediately distinguishes it from sibling tools like ask_pipeworx (which asks questions) and discover_tools (which lists tools). The resource is the Pipeworx team and the action is providing feedback, leaving no ambiguity.

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: bug, feature/data_gap, praise, and includes a hard exclusion—only for tools served by this Pipeworx connection, not other MCP servers. It even advises where to file if the tool is from another server ('file it with that server instead'). This is textbook usage guideline clarity.

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, covering safety. The description adds valuable non-obvious context: the data is self-aggregated from 'CF analytics-engine', contains 'no PII', and is 'cached 5min-1h depending on window'. This goes beyond the structured hints and helps set expectations about freshness and privacy.

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

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

The description is a bit longer than average but well-structured: an opening summary, a bulleted 'Useful for' list, and a closing note on data source and caching. Every sentence contributes value, and the structure makes it skimmable. Slight deduction for redundancy ('top tools, top packs' is repeated in spirit by the use cases).

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 clearly states what will be returned (top tools, top packs, total call volume) and the data grain ('pack, tool, count'). With only one optional parameter and full schema coverage, the tool is simple; the description fully equips an agent to use it correctly without additional context.

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 the 'window' parameter with enums and a brief description. The description enriches it by explaining the trade-off: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds interpretive meaning beyond the raw enum values, helping the agent choose a window intentionally.

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 clear, specific statement of what the tool does ('Returns the top tools, top packs, and total call volume'), and the informal framing ('What other AI agents are calling on Pipeworx right now') makes its purpose instantly understandable. This distinguishes it from siblings like discover_tools, which likely focuses on static discovery rather than live trend data.

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

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

Provides three concrete 'Useful for' scenarios that tell the agent exactly when to invoke this tool, including timing relative to other actions (e.g., 'confirming a popular tool is the canonical choice before asking your own question'). While it doesn't explicitly name alternative tools, the guidance is actionable and implies a decision point between trending lookup and direct asking.

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

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

The description goes far beyond the annotations by explaining the internal thresholds (3pp, 0.30 Jaccard similarity), the placeholder filter, the partition_check response, and the fill check behavior that prices against live CLOB depth and warns when realizable_edge_pp <= 0. This extra behavioral context is valuable for the agent to know when the tool's output is actionable.

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

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

The description is front-loaded with the main purpose and mode invocation, then details each component (semantic anchor, partition filter, response, fill check) in labeled sections. Every sentence adds substantive information for this complex tool, and the length is justified by the number of behaviors it must convey.

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, the description covers all key aspects: invocation modes, filtering criteria, output structure, and the fill-check caveat. It even points to a sibling tool for alternative use cases, ensuring the agent has a complete picture.

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 provides 100% description coverage for both `event` and `topic`, the description augments this with concrete examples, explains what the tool does with the slug or seed question, and clarifies the difference between single-event and cross-event modes. For instance, it explains that passing an event slug walks child markets and runs the partition_check, while passing a topic searches related events and flattens markets.

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 phrase 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which clearly states the tool's function and mechanism. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection through these two specific methods.

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 provides explicit mode selection: no args for trending_scan, `event` for a specific market, `topic` for cross-event scanning, with a recommendation for `event` when a specific market is known. It also names an alternative, polymarket_fill_risk, for custom sizing, making the when-not 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 the readOnly/idempotent/openWorld annotations, the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), the existence of empty segments and diagnostics (_diagnostics with funnel counters, category_counts, filter_skips), a 24h-move warning that the edge may already be in the price, and model-specific limitations (e.g., Fed bets unreliable without paid OIS/SOFR-futures data). This is rich behavioral context that materially helps an agent interpret 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 extremely dense and long, especially the model-family breakdown. While every sentence carries information, the lack of formatting (headings, bullets, line breaks) makes it a wall of text that could be harder for an agent to parse quickly. It is front-loaded with the core purpose, and the logical flow from models to knobs to output is clear, but a more structured layout would improve readability without losing content.

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

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

Despite no output schema, the description thoroughly specifies the response structure: top-level by_segment, fed_candidates/fed_note, and _diagnostics including funnel counters. It also covers all model families, edge metrics, tradeable-edge filters, caching, and failure reasons for empty segments. This is exceptionally complete for a complex tool with 9 parameters.

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 already 100%, but the description adds significant extra meaning. It groups knobs as 'TRADEABLE-EDGE KNOBS' and explains why min_partition_leg_kelly exists when min_kelly doesn't apply to partition arbs (parent-level kelly_fraction_half is 0 by design). It also explains slippage_pp assumptions (zero trading fees but bid/ask and thin depth typically eat 20-50bp). This goes well beyond the schema's field 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and how it differs from reasoning about arbitrage or other sibling tools. The phrase 'Built for "what should I bet on today"' further nails the scope and differentiates it from tools like polymarket_arbitrage or 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 gives strong usage context: it's for discovering betting opportunities without paging hundreds of markets, and it explains the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) to filter feasible edges. It also explains why Fed bets are excluded (unreliable signal without paid data). However, it doesn't explicitly name sibling tools as alternatives (e.g., 'use polymarket_arbitrage for pure arbitrage'), so it's not a perfect 5.

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

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

The description discloses behaviors beyond the annotations: snapshots are written only on cache-miss, leading to gaps ('gaps mean nobody scanned that day'), history is bounded by a 60-day TTL, and decay numbers are based on daily closes rather than intraday data. These limitations directly affect interpretation of results and are not present in the annotations.

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

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

The description is dense but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds value—from purpose to parameter handling to detailed output semantics. It is front-loaded with the core question and appropriately detailed for a telemetry 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?

Despite no output schema, the description fully documents the response structure: tracked[] items, expired[] opportunities, snapshot_dates[], and the meaning of trend categories and lifespan. It also covers limitations and edge cases (snapshot gaps, TTL, slippage). No apparent gaps for an agent to choose/invoke this tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description merely restates the defaults and mentions 'max 30' versus schema's 'clamp 2-30' and window family, adding no semantic meaning beyond what the input schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's role: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools by focusing on historical persistence rather than current edge values.

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

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

The description gives context for when this tool is valuable: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' This implies use when assessing edge durability, but it does not explicitly name alternatives or state when not to use. Clear context but no explicit exclusions.

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

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

Annotations already declare safe read-only behavior, but the description adds substantial behavioral context beyond that: it details the internal walking of the order-book ladder, the distinction between top-of-book vs VWAP calculations, the two modes, and the 'forced_directional_risk' field that names legs most likely to strand the user. It also warns that partial basket fills convert an arb into an unhedged directional position, which is a critical behavioral caveat not inferable from annotations alone. No contradiction with annotations is present.

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

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

Although long (~200 words), the description is densely structured with labeled sections (SINGLE-MARKET/BASKET), a clear opening verb, and a prioritized usage note at the top. Every sentence adds functional information—there is no fluff or repetition. The format is front-loaded with the core purpose, then mode-specific details, making it efficient for an AI agent to parse.

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

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

The tool has no output schema, so the description carries the full burden of describing return values—and it does so comprehensively. It enumerates all key fields returned in both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also addresses edge cases (thin books), constraints (size clamp), and the core risk rationale. For a tool with 4 parameters and no output schema, this is a complete and self-sufficient description.

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

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

The schema already covers all four parameters with descriptions, but the tool description enriches their meaning substantially. It explains the dual interpretation of size_usd (max spend vs target proceeds for singles; settlement notional for baskets), clarifies the side default behavior ('auto') in basket mode, and emphasizes that market vs event selects the mode. This goes significantly beyond the baseline schema, adding clear operational semantics for each parameter and their interplay.

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 and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) 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.' This is a specific, well-scoped purpose that leaves no ambiguity about what the tool does.

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

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

The description provides explicit context for when to use the tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the two distinct modes with required inputs. It also gives practical guidance on interpreting size_usd differently for buys vs sells and singles vs baskets. It clearly implies alternatives (arbitrage and edges tools) and warns about partial fills, making usage conditions unambiguous.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: compatibility_warning firing conditions, temporal_alignment implications, skipped_cross_type/subtype counters, and the explanation that non-equivalent bet shapes mean no arbitrage. This significantly exceeds annotation coverage.

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

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

The description is long but well-structured with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the purpose and each sentence adds value, though some information (e.g., topic list) is redundant with the schema.

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 full responsibility for explaining return values. It enumerates leg-by-leg prices, top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters, plus the caveat that real spreads are rarer than the shortcut list suggests. This is comprehensive for the tool's complexity.

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

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

The input schema already documents all three parameters with 100% coverage, including the list of topic shortcuts and override behavior. The description adds the two-mode distinction and clarifies that explicit parameters override topic-mapped sides, providing useful complementary context 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs and resources. It distinguishes itself implicitly by focusing on cross-venue comparison, but does not explicitly name alternatives like the sibling polymarket_arbitrage tool.

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

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

The description explicitly explains two usage modes: pre-mapped topic shortcuts and explicit kalshi_event_ticker + polymarket_event_slug pairings. It also advises that most pre-mapped topics return compatibility warnings and are not automatically tradeable, providing clear when-to-use and cautionary guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations by specifying scoping ('Scoped to your identifier...'). It does not contradict annotations.

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

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

Two sentences with no filler. The main action is front-loaded, and every clause adds value: retrieval/list behavior, use case, scoping, and sibling tool pairing.

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

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

For a tool with one optional parameter, no output schema, and supportive annotations, this description is complete. It covers how to use, when to use, scoping, and relationship to remember/forget—leaving no meaningful gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the omit-to-list behavior already in the schema and adds example keys, but does not fundamentally extend parameter understanding beyond what the schema provides.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes from siblings by naming them (remember, forget) and provides concrete use examples (target ticker, address, research notes).

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 states when to use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and companions: 'Pair with remember to save, forget to delete.' This gives explicit context and tool relationships.

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 readOnly/idempotent annotations, the description discloses the stateful effect of mark_read, the structure of returned events, and that polling is acceptable. This adds useful context and does not contradict annotations.

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

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

Four sentences pack purpose, return structure, filtering, and stateful behavior without redundancy. Each sentence serves a distinct function and is front-loaded with the primary action.

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

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

For a read-oriented tool with no output schema, it covers return payload, filtering, stateful marking, and alternative access. Missing details like pagination limits are minor and the description is complete for 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 already covers all 5 parameters. The description adds a concrete type example ('sec_8k'), describes since as ISO timestamp, and explains the side-effect of mark_read, adding value beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, identifying the action (pull) and resource (fired events from subscription feed). It distinguishes from sibling tools like list_subscriptions by focusing on recent alerts rather than subscription management.

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

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

Provides clear context for polling use cases and filtering options. Mentions the same feed is available via URL, implying an alternative access method, but does not explicitly contrast with sibling tools like recent_alerts vs recent_changes.

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 valuable behavioral context: it fans out to SEC EDGAR, GDELT→GNews with fallback, and USPTO with soft-fail due to PatentsView API sunset. It also discloses the return structure (changes[] grouped by source + total_changes count + citation URIs). No contradictions with annotations.

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

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

The description is information-dense but well-structured. It leads with relatable query examples, then explains the data sources, fallback behavior, date format, return shape, and alternatives in a single flowing passage. Every sentence contributes meaningful detail; there is no filler.

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

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

Given the tool's complexity—multiple data sources, fallback logic, soft-fail mode, and no output schema—the description covers all critical aspects: sources, failure modes, return structure, and the alternative tool. It even notes the single parallel call efficiency. No important gap is evident.

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 provides 100% coverage of all three parameters. The description adds practical value by explaining the 'since' format: ISO date or relative shorthand ('7d', '30d', '3m', '1y'), and recommending '30d' or '1m' for typical monitoring. This goes beyond the baseline schema description.

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

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

The description opens with concrete user query examples and defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes itself from entity_profile, stating that recent_changes is for time-windowed changes, while entity_profile covers static profiles. This is a specific verb+resource description that fully clarifies purpose.

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

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

Provides clear when-to-use signals: examples of user intents ('What's new with X', 'latest on Y') and explicit alternative guidance: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also explains the fallback logic (GDELT preferred, GNews when rate-limited or 5xx), helping the agent choose appropriately.

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 (write, idempotent, non-destructive), the description adds key behavioral details: 'scoped by your identifier' and the persistence distinction between authenticated (persistent) and anonymous (24h) sessions. This context is not present in the annotations and meaningfully informs an agent about side effects and lifetime.

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 that front-load purpose and usage, then detail storage behavior and related tools. Every sentence carries necessary information with no filler, making it both concise and well-structured.

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

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

For a tool with only 2 parameters and no output schema, the description covers purpose, when to use it, scoping, persistence, and pairing with related tools. Combined with the fully descriptive schema and adequate annotations, the agent has complete guidance for correct 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?

The input schema already covers both parameters with clear descriptions and examples, so the baseline is 3. The description only refers to 'key-value pair' without adding new semantic nuance, though it does reinforce the storage model already implied by 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 opens with 'Save data the agent will need to reuse later', a specific verb+resource statement that clearly defines the tool's purpose. It distinguishes itself from siblings by mentioning 'Pair with recall to retrieve later, forget to delete', and provides concrete examples like tickers and preferences, leaving no ambiguity.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and gives specific scenarios, making the triggering conditions clear. It also references alternating tools (recall, forget), effectively covering usage and alternatives in one concise sentence.

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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, the description adds valuable context: it internally cascades through multiple endpoints, returns specific fields (ticker, CIK, company_name; RxCUI, ingredient, brand), and provides citation URIs. It also mentions auto-disambiguation of inputs, which goes beyond the structured annotations.

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

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

The description is dense but well-organized, front-loaded with example queries and structured by supported types. It could be slightly more concise, but every sentence adds useful information about inputs, outputs, and internal behavior. The use of a bullet-like 'SUPPORTED TYPES' format aids scannability.

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

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

Despite lacking an output schema, the description fully explains what the tool returns for each entity type, including citation URIs. It covers input formats, supported types, and the benefit of reducing manual lookups. For a lookup tool with two simple parameters, this is complete and self-contained.

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

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

Schema coverage is 100% with detailed descriptions for both parameters, so the baseline is 3. The description adds the 'auto-disambiguated' behavior and clarifies the return types per entity type, which reinforces but does not significantly extend the schema. It provides enough extra context to justify a score above baseline.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides concrete examples (ticker, CIK, RxCUI) and explicitly distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID.' The supported types (company, drug) are clearly specified, making it distinguishable from sibling tools like entity_profile or pdl_company_enrich.

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 a strong usage directive: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups, implying it is the go-to preliminary step. However, it does not explicitly list when not to use it or mention alternatives for unsupported entity types, so it falls short of full exclusionary guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description rightly focuses on behavioral traits beyond that: it probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds valuable context not present in the annotations.

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

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

The description is three sentences and front-loaded with the core purpose, followed by the workflow and a concrete use case. Every sentence provides distinct value, with no redundancy or filler.

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

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

For a tool with no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It references the underlying ai_visibility_check and clarifies the entity ordering. However, it doesn't mention the 'models' parameter or that '_apiKey' is needed for Anthropic, though the schema covers these. Slight incompleteness prevents a 5.

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 description coverage is 100%, so all four parameters are already well-documented. The description doesn't add per-parameter semantics beyond what the schema provides, such as explaining the 'models' array or the '_apiKey' requirement. It references 'entities' generically but does not enrich parameter understanding. 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 the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a distinct verb (compare) and resource (AI visibility), and explicitly differentiates from sibling tools like ai_visibility_check by mentioning that it probes each entity with that tool and ranks results. The competitive audit use case further clarifies its 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?

The description provides clear context for when to use the tool (competitive AI-marketing audits) with a concrete example ('does Claude know about us as well as our competitors?'). It implies that single-entity checks should use ai_visibility_check, but it doesn't explicitly state exclusions or alternative tools, so it's a 4 rather than a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds substantial behavioral specifics: 'Partial failures degrade gracefully', 'bundlephobia's first measurement on a new version can take 5-30s', and 'sources_failed will list it if it times out, the rest still returns'. This moves beyond the annotations without contradiction.

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

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

The description is moderately long but well-structured: it front-loads the core composite purpose, then gives usage, return fields, scope limitations, and failure behavior in separate clauses. Every sentence adds value; it is dense but not wasteful.

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, but the description explicitly enumerates the return block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also covers ecosystem limitations and timeout behavior, making it complete for a complex composite tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (package name, specific version, default to latest). The description adds no new parameter-level details beyond reinforcing the context; baseline 3 is appropriate because the schema carries the load.

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 defines the tool as a 'Composite "should I add this npm package to my project" check in ONE call' and names the exact sources (deps.dev and bundlephobia). The verb 'scan' and resource 'dependency' are specific, and the tool is clearly differentiated from siblings by its focus on npm package adoption decisions.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'—no ambiguity. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clearly stating when not to use this tool and what to use instead.

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 richly discloses behavior beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char windows, and caps input at 200K chars with truncation flagging. Annotations already cover readOnly/idempotent/destructive, and description adds meaningful operational details without contradiction.

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

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

The description is dense but every sentence earns its place: purpose, use case, pairing, technical methodology, and constraints. It is front-loaded with the core action and progressively adds details without redundancy.

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

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

Despite lacking an output schema, the description explains return values (passages with offsets and similarity scores) and the truncation flag. It also covers the technical context (embeddings, window size) and integration with a sibling tool, making it fully self-contained for an agent to use correctly.

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

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

Schema descriptions already cover all three parameters comprehensively (100% coverage). The description restates the purpose of text and query but adds no new parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific input/output details (passages with offsets and similarity scores). It distinguishes from siblings by emphasizing 'INSIDE a fetched record' and explicitly pairs with ask_pipeworx_grounded, making its unique role clear.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' Also names a complementary alternative (ask_pipeworx_grounded) and explains how to combine them, offering clear context for choosing this tool over others.

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

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

Discloses key behaviors beyond annotations: returns subscription id, requires OAuth, SMS 10/day cap, webhook auto-disable after 10 failures, one-time webhook signing secret, and always-on feed. These are important operational implications that the annotations alone (readOnlyHint=false, openWorldHint=true) do not 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?

Dense but well-factored: front-loaded with purpose and return, then organized by subscription type and delivery channels. Every clause adds operational detail (OAuth requirement, feed default, channel specifics) 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?

No output schema exists, yet the description covers return value, allowed types, parameter shapes, delivery mechanisms, verification prerequisites, and edge behaviors. Given the tool's complexity (3 params, nested objects, multiple channels), this is remarkably complete.

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

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

The schema already has 100% coverage, but the description adds substantial extra meaning: concrete examples for each type (sec_8k item codes, polymarket topic, fred_series), delivery channel options with verification details, and HMAC signing mechanics. This goes well beyond the schema's baseline.

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

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

The description opens with a specific verb phrase 'Create a proactive monitoring subscription to a live-data event stream' and immediately states the return value. It clearly distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation of a persistent subscription.

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

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

Provides explicit context on when to use this tool: for proactive monitoring of live-data streams, with a required OAuth account. It names alternative consumption methods for the feed ('recent_alerts or GET registry.pipeworx.io/alerts.json') and specifies prerequisites for email/SMS/webhook delivery. However, it does not explicitly state when NOT to use subscriptions versus one-time queries.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond these annotations: returns category-bucketed examples with exact tool + argument shapes, drawn from the live catalog of thousands of tools. It also discloses that the response content varies with optional `topic` parameter. This is a transparent and accurate representation of the tool's 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 somewhat long but every sentence earns its place. It front-loads typical user queries to set context, then explains the output and usage in a well-organized manner. The structure is logical, but the opening list of example phrases adds length without being strictly necessary.

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 all essential aspects: what the tool does, what it returns (category-bucketed questions with tool shapes), how to call it (no args or with topic), and when to use it (onboarding). Since there is no output schema, the description compensates by describing the return structure sufficiently. Complexity is low given the simple single-parameter input and read-only nature.

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 baseline is 3. The description adds meaningful nuance by explaining that omitting `topic` yields a cross-category spread and providing concrete examples of valid topics ('finance', 'pharma', 'betting'). This enriches the schema's dry enumeration and clarifies the default behavior.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions to help users know what to ask Pipeworx. It specifies the verb+resource (suggest questions about Pipeworx) and distinguishes itself from siblings by claiming 'use this FIRST' and mentioning meta-tools it teaches. The title 'What Can I Ask Pipeworx?' reinforces the purpose.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains parameter usage: 'Call with no arguments for the full spread, or pass `topic`...' This clearly indicates when to use the tool and how to tailor it, though it doesn't explicitly mention exclusions.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement (only your own subscriptions), non-destructive deactivation (row not deleted), and retention of historical events via recent_alerts. This aligns with and enriches the provided annotations (non-destructive, idempotent, open world).

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 tightly written sentences, front-loaded with the core action, followed by two key behavioral caveats (ownership and deactivation). No fluff or redundancy, every sentence contributes useful 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 mutation tool with one parameter, no output schema, and strong annotations, the description covers all essential context: what it does, who can do it, side effects, and where to see the data afterward. It is fully sufficient for an agent to invoke correctly.

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

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

The single parameter 'id' is already fully described in the schema as 'Subscription id (uuid) returned by subscribe', with 100% schema coverage. The description adds no extra param detail beyond the word 'by id', so it does not exceed the schema baseline.

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

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

The description opens with 'Cancel a subscription by id', a specific verb (cancel) and resource (subscription), clearly distinguishing this tool from siblings like subscribe and list_subscriptions. It also adds the ownership constraint, further clarifying its exact 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?

Clear context is provided for when to use this tool: to cancel an existing subscription. It does not explicitly state when not to use it or name alternatives, but the sibling set and the mention of recent_alerts imply the appropriate alternative for viewing historical data after cancellation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining the two-path routing (SEC EDGAR + XBRL vs. grounded pipeline) and the output structure. It does not contradict annotations and provides meaningful behavioral context beyond the structured fields.

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

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

The description is detailed but well-organized, starting with concrete example queries, then usage guidance, then routing logic, then output. Every sentence earns its place, though it is a bit long. It is structured and front-loaded with the most important usage cues.

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 lack of an output schema, the description is very complete. It explains the verdict values, the citation mechanism, the fallback behavior for non-financial claims, and the performance benefit over sequential calls. The agent has enough context to understand the tool's full scope and expected results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples for the 'claim' parameter and mentions percent-delta math for tolerance, but it does not significantly extend the schema semantics. The parameter meanings are already well-documented in the schema, so the description is adequate but not additive.

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 a specific verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by explaining its role in fact-checking and by mentioning that it replaces multiple sequential calls, which sets it apart from other query tools like 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 explicitly says to use it 'whenever the agent needs to check whether something a user said is factually correct' and provides example phrasings. It also explains the routing logic for financial vs. other claims, offering clear context. However, it does not name specific alternative sibling tools to use instead, so it stops short of the top score.

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