gutendex

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the default model is free, Anthropic calls require a user-supplied key and are billed directly by Anthropic, and the response includes per-model data plus a combined view. This exceeds the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core action and scoring metric, then configuration details, then return format and use cases. Each sentence is information-dense with zero 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?

Even though there is no output schema, the description discloses the return shape: per-model {score, confidence, signals, raw_response} plus a combined view. It covers prerequisites (API key for Anthropic), default behavior, and typical use cases. It does not discuss error handling or rate limits, but the annotations already handle the safety profile, and an agent can confidently select and invoke the tool.

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

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

Input schema descriptions cover all 4 parameters at 100% coverage, so the baseline is 3. The description does not add new parameter-level meaning beyond what the schema already says; it reinforces the _apiKey billing nuance but that is already implied by the schema's 'BYO key' language. No extra syntax or constraints are introduced.

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

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

The description states a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes the tool from siblings like ask_pipeworx (generic QA) and scan_competitor_ai_presence (focused on competitors) by emphasizing cross-LLM visibility scoring.

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 names explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also gives operational guidance (default model is free, pass _apiKey for Anthropic, BYO key). It does not explicitly mention alternative tools, but the use-case framing makes the intended context clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantive context beyond annotations: it routes across many tools, fills arguments, returns citations, works on every tier, and is 'one fast call.' No contradiction with annotations. A slight deduction because it doesn't mention any potential limitations or failure modes, but overall it adds strong behavioral detail.

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

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

The description is dense and front-loaded with the most important usage directive ('PREFER OVER WEB SEARCH'), then moves through rationale, trigger phrases, examples, and escalation paths. Every sentence adds value, though it's a long single paragraph that could benefit from bullet points.

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 broad routing tool with no output schema, the description thoroughly covers return format (structured answer with citations), scope (real-world entities, events, numbers), trigger conditions, examples, tier compatibility, and when to use alternatives. It provides all necessary context for correct invocation.

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

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

Schema coverage is 100%: all 6 parameters are aliases for the single 'question' parameter, and the schema explicitly says 'Accepts query, q, prompt, text, input as aliases.' The description adds no additional parameter-level semantics, 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?

States specific function: routes questions to 5,462 tools across 1419 verified sources and returns structured answers with stable pipeworx:// citation URIs. Clearly distinguishes from siblings by labeling itself the default entry point and naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, lists trigger phrases ('what is', 'look up', 'find', etc.), provides concrete examples, and gives clear escalation guidance: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is model usage 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context about the experimental nature, live candidate routing improvements, and that it currently matches ask_pipeworx exactly. 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 organized and front-loaded with the beta status, but it is slightly repetitive (mentions ask_pipeworx multiple times) and could be tightened without losing meaning. Still, each sentence contributes valuable information.

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

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

Given the rich annotations and 100% parameter schema coverage, the description fully explains the tool's purpose, experimental status, current equivalence to stable router, and how results are used. No output schema exists, but the description notes the same response shape as ask_pipeworx, making it complete.

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

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

Schema coverage is 100% with clear descriptions for the question parameter and its aliases. The description adds no new parameter meaning beyond stating 'same arguments' as ask_pipeworx, so it meets the baseline without exceeding it.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx by highlighting it as the experimental edge, fulfilling the specific verb+resource requirement.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. This tells the agent when to choose this tool over the stable ask_pipeworx and clarifies it's a full working router, not a fallback.

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 reveals crucial behavioral traits: it uses only tool result content, returns structured evidence (verbatim quote), and explicitly lists refusal_reason values when data doesn't directly answer. This goes well beyond what annotations provide, and there is no contradiction with the readOnlyHint.

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 each sentence serves a purpose: defining the mode, explaining mechanics, listing return format/refusal reasons, giving usage context, and noting cost trade-off. It is longer than a simple tool description, but the complexity of the tool justifies the length. Slight over-elaboration in the return-format sentence could be trimmed, but it remains well-structured and front-loaded with the key purpose.

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

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

This is a complex tool (routing across 5,462 tools, extraction, refusal handling), and the description covers all essential aspects: the routing behavior, the evidence-based output structure, clear refusal reasons, use cases, and cost comparison. With no output schema provided, the detailed return format explanation is necessary and complete. No gaps remain for an agent to misuse 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 schema has 100% description coverage for all six parameters (question plus five aliases), so the schema already fully explains the parameter. The description only implicitly refers to 'fetches the data' and 'extracts the answer' without adding new meaning about the question parameter itself. With full schema coverage, the baseline of 3 is appropriate; no compensation is 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 clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by specifying 'Same routing as ask_pipeworx' but with added ground-to-source extraction, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' directly addressing trade-offs against the sibling tool.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds a wealth of behavioral details beyond that: GDELT 429 fallback behavior with retry timers, low-confidence short-circuit statuses, closed-market handling, wide-spread liquidity warnings, and cancellation-rule parsing risks (flat-50¢ void settlements). This is exactly the kind of context agents need to avoid sizing on phantom matches.

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 densely packed with operational details organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence conveys a concrete behavioral implication; there is no fluff or repetition. It's appropriately sized for a complex tool with many edge 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?

Without an output schema, the description fully carries the burden of explaining return shapes, resolver confidence fields, parent-event extraction, news fallbacks, and blocking statuses. It also covers edge cases such as wide spreads and cancellation-rule risks, leaving little ambiguity for agent invocation.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful usage context: the 'market' parameter accepts slug/URL/question text, 'depth' is explained via quick vs thorough fan-out, and 'include_raw' is tied to response-size tradeoffs and downstream use cases. This goes beyond the schema but doesn't completely rewrite param docs.

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 clarifies accepted input formats (slug, URL, question text), lists the classifier taxonomy, and explicitly states the intended use cases ('should I bet on X', etc.), distinguishing it from sibling tools like edge or arbitrage tools.

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

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

The description gives explicit use-case triggers and shows how different bet types fan out to different data packs. However, it does not explicitly name alternative sibling tools or say when *not* to use it, so it's not a full usage guideline.

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, so the safe read-only nature is covered. The description adds that it returns matching titles, authors, and IDs, but does not disclose behaviors like ordering, no-results handling, or topic matching semantics, providing only modest value beyond annotations.

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

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

The description is a single, front-loaded sentence with concrete examples and return fields. It contains no unnecessary words, making it highly scannable and efficient.

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

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

For a one-parameter, read-only browse tool with comprehensive schema annotations and an output schema, the description covers the core purpose and return content. It could mention result ordering or matching behavior, but the low complexity and existing schema make this reasonably complete.

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

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

The input schema already fully documents the single 'topic' parameter (100% coverage) with a description and examples. The tool description gives additional examples ('science fiction', 'philosophy') but does not add substantive meaning beyond the schema, 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 clearly identifies the action ('Browse books by subject or topic') and the resource (books), with concrete examples. It does not explicitly contrast with sibling tools like search_books or popular_books, so it lacks explicit sibling differentiation.

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

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

The description implies the tool is for topic-based lookup ("by subject or topic") but provides no explicit when-to-use instructions or alternatives. Sibling tools exist (e.g., search_books, popular_books) but are not mentioned, leaving the agent to infer when this tool is preferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, setting a safe-read baseline. The description adds valuable behavioral context beyond annotations: it pulls specific financial metrics from SEC EDGAR/XBRL, handles off-calendar fiscal years (AAPL Sep, NVDA Jan), sorts results by primary metric, and returns paired data with citation URIs. This enriches the agent's understanding of what happens during invocation without contradicting 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 compact but information-dense, with every sentence contributing functional value—from trigger phrases to data sources to sorting behavior. It's slightly long, but the density is justified and it front-loads the most actionable guidance (when to use) before technical details. A small reduction in length would make it perfect, but it remains well-structured and free of fluff.

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

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

With only two parameters and no output schema, the description fully covers the essential context: what data is returned for each entity type, how results are sorted, that citations are included, and that it replaces many sequential calls. It also mentions off-calendar fiscal year handling, which is a subtle correctness guarantee. The description is complete enough for an agent to select and invoke this tool 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?

Schema description coverage is 100%, with type and values both documented. The description adds meaning beyond the schema by explaining what each type retrieves (10-K revenue/net income/cash/debt for company; FAERS counts, FDA approvals, trials for drug) and clarifying that values are tickers/CIKs or drug names. This goes beyond the baseline but doesn't fully detail edge cases like CIK formatting or drug name variations, so a 4 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 performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, with specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes itself from sequential lookups and sibling tools by explicitly noting it replaces 8-15 sequential lookups, making its purpose unmistakable.

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

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

The description gives explicit trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and states when to prefer it ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). It also differentiates between company and drug types, specifying the data pulled for each, which guides the agent on when to use this tool over alternatives like entity_profile.

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

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

The description adds substantial behavioral context beyond annotations: account requirement, paid tier for 'thorough', returns gaps[] when data can't answer (never invented), second-hop iteration behavior, contradictions[] for standard/thorough, citation resolvability, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is quite long but every sentence earns its place: no filler. It is front-loaded with the account warning and fallback, then proceeds logically through capability, use cases, alternatives, and depth details. Dense but appropriately detailed for a complex tool.

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

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

For a high-complexity tool with no output schema, the description fully explains return values (findings packet with evidence+confidence+source+fetched_at, gaps[], contradictions[]), caveats (news topics yield empty gaps), and operational expectations (15-60s latency, thorough up to 90s). No important aspect appears missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond schema by explaining depth trade-offs (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with lead chasing), cost implications, and that question accepts broad/multi-part natural language. This exceeds 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It clearly distinguishes from sibling tools by explicitly noting this is NOT open-web search and contrasting with ask_pipeworx for single lookups, making the tool's unique role 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?

Explicit when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking/current news 'prefer ask_pipeworx'. It also warns about account requirements and gives a fallback alternative, which is comprehensive usage direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds worthwhile behavioral context beyond annotations: it promises 'top-N most relevant tools with names, descriptions, and full input schemas' and notes results are 'ready to call directly, no second schema lookup needed.' This discloses return format and efficiency without contradicting 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 3 sentences: purpose, usage guidance, and return behavior. It is front-loaded with the primary action ('Find tools'), and every sentence earns its place. No redundant phrases or qualifications. It is compact yet information-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?

For a tool with no output schema, the description adequately explains what is returned (tool names, descriptions, full input schemas). It also covers purpose, usage context, and a direct call-to-action. Minor gaps like 'relevant' ranking criteria or default limit (found in schema) are acceptable, so 4 is justified.

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 reinforces that the core parameter (query) is a 'description of the data or task' and mentions 'top-N' which maps to the limit parameter, but it adds little detail beyond what the schema already provides. The schema's aliases and examples carry most of the semantic weight.

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: 'Find tools by describing the data or task.' It clearly distinguishes this meta-tool from sibling task-specific tools (e.g., search_books, compare_entities) by positioning itself as the discovery layer. The extensive list of domains (SEC filings, financials, FDA drugs, etc.) further clarifies 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 explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear context and priority guidance. However, it lacks an explicit 'when not to use' statement or named alternatives, so it stops short of 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral detail: fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; patents soft-fails due to API sunset; news uses GDELT→GNews fallback; returns specific fields and 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 long but front-loaded with trigger phrases and a concise summary before enumerating outputs. Every sentence carries operational information, though it is formatted as a dense single paragraph rather than structured sections, making it slightly harder to scan.

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?

Since there is no output schema, the description takes on the full burden of explaining return values, and it does so thoroughly: cik/company_name, recent_filings with pipeworx URIs, fundamentals fields and sorting, patents status, news fallback, and LEI. It also covers input restrictions and the resolve_entity alternative, making it complete for a tool with 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?

The input schema already covers both parameters at 100% detail, including the enum for type and the zero-padded CIK vs. ticker distinction for value. The description repeats this information with examples but does not meaningfully add semantics beyond the schema, so the high-coverage 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 clearly states the tool creates a full cross-source profile of a US public company, with specific trigger phrase examples. It also distinguishes itself from sibling tools by explicitly saying to prefer it over chaining single-pack lookups and directing name-only requests to resolve_entity.

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

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

It provides explicit when-to-use guidance ('ALWAYS PREFER... when the user asks for a holistic view') and when-not-to ('names not supported — use resolve_entity first'). It also clarifies the input format (ticker or zero-padded CIK) and describes fallback behavior for news and patents.

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 that it deletes a stored memory and adds context about clearing sensitive data, which goes beyond the annotations' destructiveHint and idempotentHint. It does not contradict annotations; rather, it reinforces them. The added usage context (stale context, task completion) provides behavioral nuance beyond the raw structured metadata.

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 short sentences: the action, when to use, and related tools. Every sentence adds value, with no filler or repetition. It is front-loaded with the core action and efficiently conveys all necessary 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 one-parameter deletion tool with no output schema, the description covers purpose, usage, and pairing, while annotations cover destructive/idempotent behavior. The description is complete and leaves no critical gaps for an agent to 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?

The input schema already provides 100% coverage with the key description 'Memory key to delete,' making the parameter semantics clear. The description's 'by key' adds little beyond the schema. Baseline 3 is appropriate because 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 begins with 'Delete a previously stored memory by key,' which clearly states the verb (delete) and resource (previously stored memory) with the mechanism (by key). It distinguishes itself from sibling tools remember (store) and recall (retrieve), making the purpose unambiguous.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names alternatives/companions with 'Pair with remember and recall,' giving the agent clear decision 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 the description adds that it fetches the page, extracts title/description/links, and emits standard markdown — useful behavioral context beyond the annotations. No contradiction.

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

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

Two tight sentences followed by a brief use-case list; every sentence earns its place. 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 2-param read-only tool, the description covers process (fetch, extract, emit), output (standard markdown blob), and use cases. Lacks error behavior, but that's unnecessary for this simplicity level.

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. The description adds general context (emits a text blob) but doesn't go deeper on parameter nuances; 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 opens with a specific verb+resource: 'Generate a production-ready llms.txt file' and explains the outcome for AI crawlers. It firmly distinguishes this tool from siblings like scan_competitor_ai_presence by focusing on file generation, not just scanning visibility.

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 lists three concrete use cases (client indexing, own project drafting, competitor auditing), giving clear when-to-use context. Does not explicitly state when not to use it, but the use cases alone provide strong guidance versus sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds return field details but these are likely captured in the output schema, so the description contributes minimal behavioral context beyond annotations.

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

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

The description is a single, focused sentence that front-loads the purpose and lists return fields without any wasted words.

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

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

For a simple one-parameter read-only tool with full annotations and output schema, the description is sufficiently complete. It explains both what the tool does and what it returns.

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 the id parameter already described as 'The numeric Project Gutenberg book ID.' The description adds no additional parameter semantics, aligning with the baseline score of 3 for high schema coverage.

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

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

The description uses a specific verb 'Get' with a clear resource 'book' and scope 'by ID', distinguishing it from sibling tools like search_books or popular_books. It also lists the key fields returned.

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

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

The description implies the intended use case (when you have a book ID) but does not explicitly mention when to use this tool instead of alternatives like search_books or books_by_topic. There is no exclusion or alternative 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, covering safety and side effects. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope of active subscriptions. This goes beyond the 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?

Two sentences with no redundancy. The first sentence combines purpose and return fields; the second gives direct usage guidance. Every word earns its place.

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

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

Given the simple structure (one optional param, no output schema, rich annotations), the description is fully adequate. It explains what the tool returns, the default scope, and when to use it. No critical information is missing for an agent to select and correctly invoke this 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 one optional parameter (include_inactive) with a description at 100% coverage. The tool description does not add any further explanation about parameters, which is acceptable since the schema already fully documents the flag. 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 starts with the specific verb 'List' and a clear resource: 'the caller's active subscriptions.' It also distinguishes this from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing rather than creating or removing. The return fields are enumerated, making the tool's function unambiguous.

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

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

The description explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke this tool relative to subscribe/unsubscribe actions, making it highly actionable.

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 are all false, so the description carries the burden. It discloses meaningful behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, and advice to not paste end-user prompts. It doesn't state the return value, but for a feedback tool this is minor.

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, use cases, scope exclusions, content guidance, operational details (rate limit, quota), and signal impact. It is front-loaded with the action verb and remains well-structured, 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?

Covers what the tool does, when to use it (including non-Pipeworx exclusions), how to phrase feedback, rate limits, quota, and team read cadence. No output schema exists, but the description sufficiently prepares the agent for a one-way feedback submission, and missing return value details are not critical.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by mapping type values to usage scenarios ('bug = wrong/stale data') and giving concrete guidance for message/context: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.'

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 leads with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings like ask_pipeworx or discover_tools, which are for querying, not providing feedback.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives exclusion criteria and an alternative: 'if the tool came from a different MCP server ... file it with that server 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?

Description discloses key behaviors: derived from CF analytics-engine, no PII, only (pack, tool, count) data, plus cache freshness (5min-1h). This adds valuable context beyond the readOnly/idempotent 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 core purpose, followed by practical use cases and a brief data provenance note. No wasted words.

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

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

For a simple one-parameter, no-output-schema tool, the description covers what it returns, the data shape, caching behavior, and use cases. Nothing critical is missing.

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

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

Schema already fully documents the window parameter with enum and explanations, so baseline is 3. The description adds extra meaning by noting cache freshness depends on the chosen window, which helps the agent choose appropriately.

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

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

The description clearly states the tool returns trending AI agent calls on Pipeworx, listing specific outputs (top tools, packs, call volume) and window options. This distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated trending signal.

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 a 'Useful for' list with three concrete scenarios, giving clear context on when to use it. However, it does not explicitly name alternatives or state when not to use the tool, so it stops short of fully explicit guidelines.

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 generic readOnly/idempotent annotations, disclosing specific behaviors: the 3pp partition-check threshold, placeholder-slug filtering with >20% null-arb return, zero-Jaccard semantic anchor, and the fill-check logic with realizable_edge_pp <= 0 warning. These are non-obvious operational details that materially affect interpretation of 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?

Although long, the description is well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every sentence carries operational weight—no filler or tautology—making the length justified given the tool's complexity.

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

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

The description fully covers the tool's modes, input variants, algorithmic thresholds, response structure, and edge-case behaviors. Since no output schema exists, the detailed 'Response: opportunities[]...' section compensates. It also provides a safety caveat about not trading when the overround exists only at last-trade, making it complete for safe usage.

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

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

Schema coverage is 100%, but the description adds substantial value: concrete example slugs ('fed-decision-may-2026'), acceptance of full Polymarket URLs, and detailed mode semantics for event vs topic that is absent from the schema property descriptions. This transforms schema placeholders into actionable usage knowledge.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between event, topic, and no-arg modes, and names a sibling for custom sizing (polymarket_fill_risk), making the tool's purpose unambiguous.

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

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

Explicit guidance is given: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains when the fill check applies and defers custom sizing to polymarket_fill_risk, providing clear when-to-use and alternative 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond this by detailing caching ('Cached 1h at the KV level'), response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), the 24h-move warning, and caveats like Fed signal unreliability. This is substantial additional behavioral disclosure.

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 long, running to hundreds of words, and dives into model-family internals (e.g., 'lognormal barrier from 90d FRED log-returns') that are unlikely to be needed for correct invocation. While the opening sentence is front-loaded, the excess detail hurts conciseness; many sentences could be trimmed or moved to separate documentation.

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 the length, the description is remarkably complete for a tool with no output schema: it specifies top-level response segments, key per-opportunity fields, diagnostic counters, and explains degenerate conditions ('WHY a segment is empty'). It also covers caching and parameter effects, making it fully adequate for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a high-level grouping ('TRADEABLE-EDGE KNOBS') but doesn't provide new semantics beyond what parameter descriptions already state; it merely summarizes them. It reinforces the 'net of slippage' concept, but that's already in 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 a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' and frames the use case as 'what should I bet on today.' This clearly distinguishes it from sibling tools like polymarket_arbitrage (cross-market arbitrage) and polymarket_edge_tracker (tracking existing edges) by emphasizing Pipeworx-data disagreement as the signal.

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 clear context: it's built for discovering opportunities without paging hundreds of markets, and notes that Fed bets are excluded from ranking due to unreliable signals. However, it never explicitly mentions when to use this tool over siblings (e.g., polymarket_arbitrage) or states when not to use it, so it lacks explicit alternative 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?

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: snapshot TTL (60-day), cache-miss-driven snapshot writing (gaps mean no scan), daily-close decay calculation (not intraday), signed edge values (negative = SELL YES), and the full response structure including expired opportunities. This is exceptional transparency.

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

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

The description is long but each sentence earns its place, structured with explicit labels (Args, RESPONSE, LIMITS). Core purpose and edge-case context are front-loaded, making it scannable yet comprehensive. Zero filler 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?

Given the tool's complexity and absence of an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), defines computed fields (trend, decay_pp_per_day), and clarifies data limitations. It is complete enough for an agent to invoke and interpret results 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 both params well-documented. The description adds value by specifying defaults ('default 14, max 30' for days; '24hr | 1wk | 1mo' for window), the concept of 'snapshot family' for window, and the purpose of each parameter in context. Omits the clamp range but the schema covers it.

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

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

The description clearly states the tool's function: '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?') with concrete terms, distinguishing it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides clear context for when to use this tool ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions it is built from daily polymarket_edges snapshots, implicitly positioning it as the historical analysis counterpart. However, it does not explicitly name alternatives or state when not to use it, falling short of a 5.

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

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

Annotations already state readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond these: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, and a verdict, and explains the risk of partial basket fills converting an arb into an unhedged directional position. It also discloses forced_directional_risk as a named output, providing deep transparency into 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 long but densely packed with essential information. It front-loads the core purpose ('Realizable-vs-theoretical edge check'), then methodically explains single-market mode, basket mode, and usage context. It could be improved with bullet points or subheadings for readability, but every sentence carries operational meaning, so it earns a high score.

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

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

Given the tool's complexity (two modes, multiple parameters, no output schema), the description is remarkably complete. It details the returned fields (top_of_book, vwap_fill_price, capture_ratio, thin_legs, max_clean_notional_usd, forced_directional_risk), explains the key risk (unhedged directional position), and provides thresholds for use. It even ties the basket mode to arbitrage capture, making the tool self-sufficient for an agent.

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

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

While the schema already provides 100% parameter coverage with descriptions, the tool description adds meaningful semantics, especially for size_usd: in single-market mode it is 'max spend on buys, target proceeds on sells,' and in basket mode it is 'settlement notional S (shares per leg; each share pays $1).' It also clarifies the 'side' parameter's default behavior in basket mode, going beyond the schema's enum listing.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly defining the tool's function. It explicitly distinguishes two modes (single-market and basket) and names sibling tools (polymarket_arbitrage, polymarket_edges) as related use cases, making its unique role unmistakable.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable) and gives context for both modes. It does not explicitly state when not to use, but the threshold and the reference to specific sibling signals serve as a clear exclusion guide.

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 rich behavioral details: the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), temporal_alignment semantics, skipped_cross_type/subtype counters, and the underlying reason for price differences (participant pools). This adds substantial context for interpreting results and handling edge cases.

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

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

The description is lengthy but densely packed with essential information. It is front-loaded with the core purpose, then systematically covers modes, response fields, and safety warnings. Each sentence contributes to understanding the tool's behavior, though it could be trimmed slightly without losing critical context.

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 complex tool with no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and the meaning of each field. It also covers limitations (e.g., temporal misalignment, non-equivalent bet shapes), making it highly complete for agent use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how the parameters interact: topic is a shortcut that maps to both venues, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. It also lists the exact valid topic strings, going beyond the schema's brief mentions. The 'custom pairings' phrase and examples reinforce 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 opens with a specific verb+resource+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons, and outlines two distinct modes (topic and explicit ticker/slug) that define its exact 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 clear context on when to use the tool via its two modes and explains the macro-shortcut topics. It also warns that most pre-mapped topics return compatibility_warning, effectively signaling when the tool may not be appropriate. However, it does not explicitly compare against alternative sibling tools or state 'use this when...' as opposed to other Polymarket/Kalshi tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety details. It adds some behavioral context by specifying the ranking criterion ('most downloaded') and the return fields, but does not disclose other behaviors like pagination, update frequency, or data source limitations.

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

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

The description is concise, consisting of two clear sentences. It is front-loaded with the main purpose and avoids redundancy, making every word count.

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 zero-parameter list tool with a read-only, idempotent annotation profile and an output schema, the description is complete. It conveys the core purpose and return contents, and no additional context is necessary.

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 tool has zero parameters, so the schema is trivially complete. According to the rubric, a baseline of 4 is appropriate since the description does not need to compensate for any parameter documentation gaps.

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 with a specific verb ('get'), resource ('books'), and scope ('most downloaded ranked by popularity'), and it mentions the return content (titles, authors, IDs, download statistics). This differentiates it from sibling tools like search_books and books_by_topic.

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 does not explicitly state when to use this tool versus alternatives such as search_books or books_by_topic. The usage is only implied by the purpose, which is to retrieve popular books, but no direct guidance or exclusions are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds useful behavioral context by explaining that omitting the key lists all saved keys and that data is scoped to an identifier (anonymous IP, BYO key hash, or account ID). It also notes the relationship to remember and forget.

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 concise sentences, each carrying distinct value: behavior, use case, scoping, and pairing with sibling tools. Front-loaded with the core action and 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?

For a simple tool with one optional parameter, strong annotations, and no output schema, the description covers behavior, use cases, scope, and relationships. It does not explicitly describe the return format (e.g., value string vs. list of keys), but that is largely inferable from the described behavior.

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

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

Schema coverage is 100% (the key parameter is described as 'Memory key to retrieve (omit to list all keys)'). The description reinforces the omit-to-list behavior and explains the key's provenance ('value previously saved via remember'), but adds no new parameter-level details beyond what the schema already provides.

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

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

The description clearly states the tool's primary function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It identifies the resource (memory store), the verb (retrieve/list), and distinguishes itself from sibling tools by naming remember and forget.

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

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

The description explicitly provides use cases: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions companions: 'Pair with remember to save, forget to delete.' It lacks an explicit when-not-to-use, but the guidance is otherwise clear.

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

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

The description reveals that mark_read:true changes read state, contradicting the annotations that declare readOnlyHint=true and idempotentHint=true. This is a direct conflict, so the description's transparency is undermined by inconsistent metadata.

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 tight and front-loaded: the first sentence states the core function, the second details return fields, and the last two cover filtering, side effects, and alternative access. No wasted words.

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

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

For a 5-param optional tool with no output schema, the description covers return fields, filtering, read-marking behavior, and even points to an external mirror for scripts. However, the contradiction between mark_read behavior and the read-only annotation leaves a gap in the overall 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 description complements the schema by providing an example type ('sec_8k'), confirming the since ISO timestamp format, and clarifying the effect of mark_read. Since schema coverage is 100%, this added explanation elevates it 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 opens with a specific verb ('Pull') and resource ('fired events from your subscription feed'), and further specifies the alert content and filtering options, clearly distinguishing it from sibling tools like list_subscriptions or recent_changes.

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 explains the tool is appropriate for polling ('Polls work fine') and directs script/automation users to an alternative HTTP endpoint, giving context on when to use this tool. However, it doesn't explicitly name sibling tools as alternatives or state exclusion criteria.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details fan-out behavior, source fallbacks, the PatentsView sunset soft-fail, accepted date formats, and return shape (changes[], total_changes, pipeworx:// URIs). This gives the agent a robust model of what will happen when the tool is invoked.

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-organized, with a front-loaded intent list followed by source details, input formats, output summary, and alternative tool guidance. It could be slightly trimmed (e.g., multiple example queries), but every sentence contributes useful decision-making or behavioral information.

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

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

Given no output schema, the description adequately explains the return structure and data provenance. It covers input flexibility, fallback behavior, failure modes, and explicitly tells the agent when to use a different tool. This is complete for a multi-source, moderate-complexity 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 schema already covers all parameters (100%), but the description adds practical guidance on `since` formats and recommends '30d' or '1m' for typical monitoring. It reinforces the zero-padded CIK/ticker semantics. This goes slightly beyond the schema, though most parameter detail is already present.

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

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

The description clearly identifies the tool as a change feed for a company over a configurable window, with concrete natural-language triggers ('What's new with X', 'updates on Acme'). It names the underlying data sources (SEC EDGAR, news, patents) and explicitly contrasts with entity_profile, making it easy to distinguish from siblings.

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

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

The description provides explicit when-to-use guidance: it targets recent-change queries over a window, and says to use entity_profile instead when a static profile is needed regardless of window. It also explains internal fallback behavior (GDELT→GNews) and the USPTO soft-fail, which helps the agent decide when this tool is appropriate.

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by disclosing storage is key-value scoped by identifier, persistence differs for authenticated users vs anonymous sessions (24 hours), and it pairs with recall/forget. 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 four sentences, front-loaded with the purpose, and each sentence contributes distinct information (what, when, storage behavior, companion tools). No redundancy or fluff.

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

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

For a two-parameter write-only tool, the description fully covers purpose, usage timing, persistence semantics, and related tools. The input schema supplies parameter details, and the absence of an output schema is unnecessary for this simple operation.

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

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

Schema coverage is 100% with descriptions for both key and value. The description supplements this by giving example key formats (e.g., 'subject_property') and clarifying that value accepts any text, enhancing the semantic understanding of parameters.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It provides concrete use cases (resolved ticker, target address, user preference, research subject) and explicitly distinguishes itself from siblings 'recall' and 'forget' by its role in 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 states 'Use when you discover something worth carrying forward' and gives examples, which clearly signals when to invoke the tool. It also directs pairing with 'recall to retrieve later, forget to delete', offering explicit alternative/complementary tool 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: the tool cascades through several lookup endpoints internally, auto-disambiguates inputs, and returns citation URIs. No contradictions, and the added details help set expectations.

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

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

The description is longer than average but front-loaded with user-intent examples and organized by supported types. It avoids fluff; each sentence either clarifies usage, describes outputs, or explains internal behavior. Slightly verbose, but everything earns its place.

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

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

Despite having no output schema, the description fully details what each entity type returns (ticker + CIK + company_name, RxCUI + ingredient + brand, and citation URIs). It also explains the internal cascading behavior, making the tool understandable in isolation. Given the simplicity of the parameters and the annotations, nothing critical is missing.

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

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

The schema already has 100% coverage for the two parameters, but the description adds meaningful examples and clarifies accepted formats (ticker, CIK, name; brand or generic) plus auto-disambiguation. This goes beyond the schema's enums and value descriptions, making it more actionable.

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

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

The description clearly states the verb 'resolve' and the resource: user-spoken names to canonical/official identifiers. It lists concrete examples ('What's the ticker for...') and supported entity types, distinguishing it from sibling tools that likely consume these identifiers. The phrase 'other tools require as input' reinforces its role.

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

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

It provides an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also implies alternatives by noting it 'replaces 2-3 manual lookups,' but does not explicitly name alternative tools or state when not to use it. This is strong guidance but not exhaustive.

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, idempotent, and non-destructive. The description adds value by disclosing that it internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and provides useful behavioral insight.

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 the core purpose in the first sentence, mechanism and output in the second, and use case in the third. Every sentence earns its place, with no filler or repetition.

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

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

For a tool with no output schema and moderate complexity, the description covers key aspects: what it does, how it executes, what it returns, and a typical use case. It lacks explicit mention of entity count limits (though schema provides that) and model/key handling, but overall it is sufficiently complete for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the 'first entity as subject, rest competitors' concept but adds minimal parameter-specific detail beyond what the schema already documents. It does not need to compensate for missing schema information.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities by mentioning it probes with ai_visibility_check and ranks results.

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 a clear use case: competitive AI-marketing audits, with an illustrative example. It implies when to use this tool (when comparing multiple entities) but does not explicitly name alternatives or exclusions, leaving some room for interpretation.

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 significant behavioral traits beyond the annotations: it fans out to external services, can take 5-30s on bundlephobia's first measurement, may time out, and degrades gracefully with sources_failed listing failures. This adds valuable context about latency and failure modes that annotations do not cover.

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, front-loading the one-call composite check. It uses lists and separators effectively to convey many details without wasted words. It is slightly long, but every sentence earns its place for a tool of this complexity.

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

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

With no output schema, the description compensates by enumerating the returned summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases like partial failures and timeouts, making it highly complete for the tool's purpose.

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 describes both parameters with 100% coverage, including the default behavior for version. The description adds minor context (e.g., scoped packages, NPM-only) but largely relies on the schema. Baseline 3 is appropriate since the schema carries the semantic 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 clearly states the tool is a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It names the source resources and the overall purpose, distinguishing it from unrelated siblings by its focus on npm dependency evaluation.

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

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

Explicitly states 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', giving direct usage context. It also notes NPM-only in v1 and directs other ecosystems to deps.dev:version, providing a clear alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the bar. The description adds useful context by listing the exact return fields (book IDs, titles, authors, download counts), which goes beyond the annotations. It does not mention pagination or limits, but the addition of return fields justifies a 4.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every phrase adds value, stating the search criteria and return fields compactly.

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 search tool with one parameter, an output schema, and strong annotations, the description covers the essential behavioral and return-value context. It does not need to explain pagination or filters given the tool's simplicity and existing structured metadata.

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 parameter description ('Title or author name to search for') fully matches the tool description. The description adds no additional meaning beyond the schema, 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 uses a specific verb ('Search') and resource ('books'), clearly stating search criteria (title or author) and return fields (book IDs, titles, authors, download counts). This distinguishes it from sibling tools like 'books_by_topic' (topic-based) and 'get_book' (single book retrieval).

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

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

The description implies when to use it: when searching by title or author. It provides clear context but does not explicitly name alternative tools or exclusions, so it falls short of a 5.

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

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

Goes well beyond annotations by detailing output format (top-N passages with character offsets and similarity scores), underlying mechanism (BGE-base-en embeddings, cosine, 500-char overlapping windows), and limits with truncation flags. 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?

Four sentences, each packed with distinct, high-value information: purpose, usage scenario, mechanics, and limits. Front-loaded with the primary action and no redundant phrasing.

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

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

Despite no output schema, description fully covers input, output, use case, and edge cases (truncation). Combined with strong annotations, the description is complete for an agent to invoke correctly.

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

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

Schema covers 100% of params, and description adds context beyond schema: explains 'text' as fetched record, gives example queries, and notes truncation behavior. This enriches parameter meaning more than the 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?

Description states specific action: 'Semantic search INSIDE a fetched record.' It clearly identifies the resource (a fetched record) and the operation (semantic search), distinguishing it from siblings by emphasizing it operates on already-pulled text and pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and gives a pairing with ask_pipeworx_grounded. This directly addresses alternatives and provides a decision rule for the 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?

The description adds substantial behavioral context beyond the annotations: it requires an OAuth account, returns the new subscription id, describes the always-on feed, and specifies delivery constraints (SMS phone verification, 10/day cap). This is valuable transparency for a write operation, and it does not contradict 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 a single dense paragraph packed with essential information: purpose, return value, auth requirement, types, and delivery channels. While it is not as concise as some examples, every clause contributes meaning, and the structure is logical (purpose → return → auth → types → delivery).

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers the core aspects well: it states the return value, auth constraint, and primary delivery channels. The schema fills in remaining details (webhook, full type list), so overall context is fairly complete. It misses webhook in the main description but that is covered by the schema.

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

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

The input schema already has 100% parameter coverage, so the baseline is 3. The description enriches this by providing concrete examples for sec_8k, polymarket_edge, and fred_series (e.g., items:["5.02"] = officer change), which clarifies the semantics beyond the schema. However, it does not add examples for all supported types (patent_grant, clinical_trial), so it earns a 4 rather than a 5.

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 with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also enumerates supported types (sec_8k, polymarket_edge, fred_series) and explicitly distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use this tool: for proactive monitoring of live-data events. It also notes important prerequisites ('Requires a Pipeworx OAuth account') and how to consume the feed ('pull via recent_alerts'). However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotation flags (readOnly, idempotent, non-destructive), the description adds meaningful behavioral context: it draws from a live catalog of thousands of tools, returns category-bucketed examples with exact tool/argument shapes, and supports focusing via a topic. This gives the agent a clear picture of what to expect. It could mention that results are illustrative examples (already implied by 'example questions') or any rate limits, but the added context is substantial.

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 most, but every part carries value. The initial list of user queries helps the agent recognize when a human is asking about capabilities. The subsequent explanation of return content, parameter behavior, and when-to-use is dense and well-integrated. While it could be tightened, the elaboration serves the tool's onboarding purpose effectively.

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 a single optional parameter and no output schema, the description sufficiently explains return values (category-bucketed example questions with tool/argument shapes) and usage patterns. It also positions the tool within the broader ecosystem by naming meta-tools and the 'first step' role. This is complete for the tool's complexity and role.

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

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

The input schema provides 100% coverage, fully describing the optional 'topic' parameter, including possible values and the omit-for-cross-category behavior. The description repeats this with examples (e.g., 'finance', 'pharma', 'betting') but introduces no new semantics beyond what the schema already states. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point for an agent that wants to know what to ask. It specifies the output: category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the 'FIRST' step when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also mentions learning to call meta-tools (ask_pipeworx, entity_profile, compare_entities), providing clear context about alternatives. The distinction between using no arguments vs. a topic is also clearly explained.

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

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

Annotations already indicate non-destructive and idempotent behavior, but the description goes further by disclosing ownership enforcement, that the row is deactivated (not deleted), and that historical events remain available via recent_alerts. This adds 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 two sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by essential behavioral details. Every sentence earns its place 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?

For a simple one-parameter tool with rich annotations and full schema coverage, the description provides sufficient context for an agent to select and invoke it correctly. It covers ownership, soft-delete behavior, and the impact on historical data, making it complete without needing an output schema.

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

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

The schema already provides 100% coverage for the single parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description only refers to 'by id' without adding new semantic meaning, 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 a specific verb ('Cancel') with a clear resource ('subscription') and scope ('by id'), immediately distinguishing it from sibling tools like subscribe and list_subscriptions. It also adds relevant details about ownership and deactivation, making the purpose unambiguous.

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

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

The description gives clear context: you can only cancel your own subscriptions, and the operation is a soft-delete. This implies when to use it (when you want to stop receiving alerts) without explicitly naming alternatives or exclusions. It is slightly above baseline but lacks explicit 'use this instead of' 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 signal read-only/idempotent behavior. The description adds valuable context: dual-path execution (SEC EDGAR fast path vs grounded pipeline), return value structure, and efficiency gain over sequential calls. No contradiction with annotations.

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

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

The description is detailed but well-structured: starts with user intents, then purpose, routing, return values, and efficiency. Each sentence earns its place, though it is 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 sufficiently explains return values (verdict types, citation, reasoning). It covers input, behavior, and output for a complex two-path tool, though it omits edge cases or error handling.

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 has 100% coverage with detailed descriptions for both parameters. The description reinforces tolerance_pct behavior but does not introduce new semantic details beyond what the schema already provides.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, with concrete user phrases ('Is it true that…', 'fact check'). It clearly distinguishes from siblings by focusing on factual claim verification rather than general research or search.

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

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

It provides clear when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes routing for company-financial vs other claims. However, it does not explicitly name alternative tools or provide when-not-to-use cases.

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