Microsoft Onenote

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

Annotations already label the tool as read-only and idempotent. The description adds value by detailing the default model, the need for an API key for Anthropic, cost implications, and the return format. This goes beyond 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 concise (4 sentences) and front-loaded with the main action. Every sentence provides necessary information without redundancy.

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

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

Given the tool's complexity (4 params, no output schema), the description covers the main behavioral aspects: what it does, how to use it, and use cases. It lacks error handling details but is sufficient for effective 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 baseline is 3. The description adds context: explains the default model, how to use the API key, and the purpose of the 'context' parameter. It also describes the return structure, supplementing the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and returns a visibility score. It uses a specific verb ('probe') and resource ('LLMs') and distinguishes the tool from siblings like 'scan_competitor_ai_presence' by focusing on multi-model probing and 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 provides use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which helps the agent decide when to use this tool. However, it does not explicitly exclude alternatives or compare to similar 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?

Beyond annotations (readOnly, openWorld, idempotent), the description explains internal routing to 4,482 tools, automatic argument filling, and returns structured answers with citation URIs, with no contradictions.

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

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

The description is comprehensive and front-loaded with key purpose, but slightly lengthy. However, each sentence adds value, making it appropriately sized for 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?

Given no output schema, the description covers return format (structured answer with citation URIs), internal routing, tier compatibility, and step-up guidance, making it fully complete.

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

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

Schema coverage is 100%, describing all 6 parameters as aliases for the question. The description only restates the schema ('Your question or request in natural language'), adding no additional semantics.

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

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

The description clearly states it answers factual questions using structured data from thousands of sources, provides many examples, and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says to prefer over web search, gives query patterns like 'what is', 'look up', and specifies when to use alternatives for hallucination-resistance or broad questions.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds value by detailing the extraction process, refusal reasons, and the exact return format. 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?

Single dense paragraph but front-loads key point. Every sentence adds substance. Could be more structured (e.g., bullet points) but highly 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?

No output schema exists, so description fully explains the return format with success and refusal cases, including all fields and refusal reason values. Complete given tool complexity.

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

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

Schema coverage is 100% with all parameters described. Description does not add additional parameter semantics beyond the schema. Baseline 3 is appropriate; no extra value for 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Explains it routes the same as ask_pipeworx but extracts answer only from tool result. Distinguishes from sibling ask_pipeworx by specifying it's for cases where answers will be quoted/cited/acted on.

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

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

Explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also advises preferring ask_pipeworx for casual lookups due to extra LLM cost.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral context: fan-out to multiple sources, market-match confidence levels, handling of closed markets and wide spreads, resolution rule risk, and safety short-circuits. This far exceeds what annotations provide.

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

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

The description is long but well-structured with labeled sections (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). Every sentence adds value, though brevity could be improved.

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 thoroughly explains return fields (market, analysis, evidence, market_match_confidence), edge cases (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation rule parsing. It leaves no gaps for the agent.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: market can be slug, URL, or question text; depth enum with examples; include_raw default with rationale. The description adds examples and clarifies usage beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + model comparison), distinguishing it from sibling tools like polymarket_arbitrage by focusing on pulling data for a single bet.

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 lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool blocks (low-confidence matches, closed markets) but does not explicitly contrast with 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?

Beyond annotations (readOnlyHint, openWorldHint, etc.), description discloses data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

Single dense paragraph is efficient but could benefit from slight structuring (e.g., separate lines for company vs drug). Every sentence is informative, no fluff, but slightly less scannable.

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

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

Given complexity (two types, multiple data sources, lack of output schema), the description covers input forms, output behavior (sorted results, citations), and efficiency note. Missing details like pagination or error handling, but adequate for core task.

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

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

Schema coverage is 100%, but description adds significant meaning: explains the two enum values for 'type' with specific data pulled, and for 'values' specifies format (tickers/CIKs vs drug names) and count constraints. This goes well beyond the schema.

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

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

Description starts with natural language examples, specifies side-by-side comparison of 2-5 companies or drugs, and clearly differentiates from siblings like entity_profile. It unambiguously states the verb (compare) and resource (companies/drugs) with specific data sources.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides trigger phrases. This gives strong when-to-use guidance and implies when not to use (e.g., single entity lookups).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds crucial behaviors: account requirement, depth tiers, 15-60s latency, return of gaps[] when data unavailable, and never inventing. No contradictions.

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

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

Description is comprehensive but slightly long; however, it is front-loaded with critical caveats (account, alternatives) and each sentence contributes unique information. Structure is logical and efficient for 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?

Given no output schema, description fully explains return format (findings packet with evidence, confidence, source, citation, gaps[]). Covers all key aspects: input constraints, behavior, results, and limitations. Contextually 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 coverage is 100% (both params documented). Description adds meaning: 'depth' enum values explained (quick=3, standard=5, thorough=8 with paid plan), and 'question' clarifies broad/multi-part is appropriate. Adds value beyond schema.

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

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

The description clearly states the tool's function: 'grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and contrasts with open-web search and sibling ask_pipeworx. It explains decomposition and parallel tool routing, making the specific verb+resource clear.

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

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

Explicitly recommends for 'broad/multi-part questions' and advises against single lookups (use ask_pipeworx) or breaking news (prefer ask_pipeworx). Provides exact alternatives and context, including account requirements and depth limits.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by explaining that the tool returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond what annotations provide and helps the agent understand the output 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 well-structured and front-loaded with the primary purpose. It uses bullet-like lists (comma-separated) for data categories and examples. However, it is slightly verbose (multiple sentences) and could be more concise by trimming some redundant phrasing. Still, every sentence adds value.

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

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

Given the absence of an output schema, the description adequately explains what the tool returns (top-N tools with names, descriptions, and input schemas). The parameter count is 6 with 1 required, and all aliases are documented in the schema. The description covers the tool's role in the ecosystem (first call) and its behavior. It is sufficiently complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description reinforces the meaning of the 'query' parameter by describing it as a 'natural language description of what you want to do' and listing aliases. The examples in the schema also aid understanding. While the description adds some context, the schema carries the primary burden, justifying a 4 rather than 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: 'Find tools by describing the data or task.' It specifies the action (find/browse/search/discover) and the resource (tools). The examples (SEC filings, FDA drugs, etc.) further clarify the scope, and the description distinguishes this from sibling tools by its role as the first-stop for tool discovery.

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 this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides concrete examples of tasks (e.g., 'analyze housing market trends') and lists data categories, giving clear context for when it's 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, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: parallel fan-out across multiple sources, patent soft-fail status, return fields (filings, fundamentals, patents, news, LEI), and input constraints (ticker or CIK, no names). No contradictions.

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

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

The description is comprehensive but efficiently structured: starts with examples, then explains behavior, sources, and constraints. No redundant sentences, though slightly verbose; remains clear and focused.

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 details all returned data (CIK, filings, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail). Covers edge cases (names not supported). Sufficiently complete for a complex aggregator tool.

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

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

Schema description coverage is 100% with detailed descriptions for type and value. The tool description restates these but does not add new parameter-level meaning beyond what the schema already provides, so 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 it returns a full cross-source profile for a US public company, provides example queries (e.g., 'tell me about X', 'company profile for Microsoft'), and distinguishes itself from related tools like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' for holistic views, and directs users to resolve_entity when only a name is provided, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description only restates deletion without adding new behavioral context beyond the schema.

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?

Only three sentences, each serving a distinct purpose: action, usage guidance, and pairing with siblings. No redundant 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 tool with one required parameter and no output schema, description fully covers purpose, usage conditions, and relationships with sibling tools. Annotations cover safety aspects.

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

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

Schema coverage is 100% and parameter 'key' has description 'Memory key to delete'. Description adds no additional meaning beyond what schema provides.

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

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

Description clearly states verb 'Delete' and resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall' by explicitly pairing with them.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with alternatives 'remember and recall'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds process details: fetches the page, extracts title/description/key links, emits standard markdown format. No contradictions. Discloses output as text blob ready to drop at site-root/llms.txt.

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: purpose, process, use cases. Front-loaded with core action. No unnecessary words.

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

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

Given no output schema and two parameters, description covers purpose, process, and output format. Could mention error handling or URL validation, but overall adequate.

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%. Description repeats schema for url and max_links without adding new semantic information. Baseline 3 given high 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?

Description clearly states what the tool does: generate a production-ready llms.txt file for any URL. Specifies verb 'generate' and resource 'llms.txt file', and distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation.

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

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

Explicit use cases are listed (getting client's site indexed, drafting for own project, auditing competitor). No explicit when-not-to-use or alternatives, but the use cases provide clear context for selection among siblings.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds that only active subscriptions are returned by default and lists the returned fields, which is helpful but not extensive.

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

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

The description is two sentences: the first states purpose and return fields, the second gives usage guidance. No wasted words; front-loaded with key information.

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

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

Given the simplicity of the tool, the annotations, and the schema coverage, the description is nearly complete. It lists return fields and provides usage context. Missing details like pagination or limits are minor for this list 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 only parameter, include_inactive, has a full description in the input schema (100% coverage). The tool description does not add additional semantics 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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description explains when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance, though it does not explicitly mention when not to use.

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

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

Discloses behavioral traits beyond annotations: rate limit of 5 per identifier per day, free usage, and that the team reads digests daily. All annotations are false; no contradictions.

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

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

Four sentences, each serving a distinct purpose: purpose, usage, formatting tip, policy. No wasted words. Front-loaded with primary action and use-case enumeration.

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

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

Given the tool's simplicity (3 params, 2 required, nested context object, no output schema), the description fully covers how to construct effective feedback, what types exist, and behavioral constraints like rate limits and team response.

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

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

Schema coverage is 100%, but description adds rich meaning: explains each enum option with concrete examples, advises on formatting message in terms of Pipeworx tools/packs, and clarifies optional context fields.

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 specific verb 'Tell' and resource 'Pipeworx team'. It lists exact use cases (bug, feature, data_gap, praise) and differentiates from sibling tools which are about querying or retrieving information.

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 guidance for each feedback type, plus a clear exclusion: 'don't paste the end-user's prompt'. Also mentions rate limits and quota implications, providing complete context for appropriate use.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds key behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h, and self-aggregating. This goes beyond annotations and is essential for trust and usage 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 concise: one sentence for output, three bullet points for use cases, and two sentences for additional details. Every sentence adds value, no fluff. Front-loaded with the core action.

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

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

For a simple tool with one optional enum parameter and no output schema, the description fully explains what is returned, how it is derived, privacy, caching, and use cases. Agents have enough info to decide when to call 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?

Schema description coverage is 100% for the single parameter. The description adds default value ('24h') and explains the effect of window size on hotness vs. steady-state demand, enhancing understanding beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a window. It specifies the verb 'Returns' and resource 'trending data from Pipeworx'. The use cases further clarify its purpose and distinguish it from siblings like 'discover_tools'.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use case with demand. It does not mention when not to use or alternatives, but the context is clear enough for an agent to select appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: walks child markets, checks ordering, computes partition_check, returns fill_check warnings, and handles edge cases like low similarity and placeholders. No contradictions.

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

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

Long but well-structured with sections (REQUIRES, SEMANTIC ANCHOR, etc.). Front-loaded with requirements. Some redundancy in explaining event mode twice, but overall efficient for the complexity.

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

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

Given 2 params and no output schema, description fully specifies return structure (opportunities[], partition_check, fill_check details), covers error cases (empty args, placeholders, low similarity), and links to sibling for sizing. No missing pieces for an AI agent to use correctly.

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

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

Schema covers both parameters with descriptions. Description adds meaning: event uses slug, topic uses seed question; provides examples and explains when to use each mode. Coverage is 100% and description enriches understanding.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishes event and topic modes with examples, and is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states event mode for specific markets, topic mode for cross-event scanning, warns that calling with no args fails, and provides examples of when to use each. Also mentions fill_check and polymarket_fill_risk for trade execution.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: data sources (FRED, GDELT), caching (1h at KV level), response structure with diagnostics, and details on model families. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (model families, knobs, response segments, diagnostics). It is front-loaded with the purpose. While dense, it remains organized and informative, though some details could be condensed.

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

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

For a read-only tool with 9 parameters and no output schema, the description provides comprehensive details: response structure (by_segment, fed_candidates, _diagnostics), caching, and usage limitations. It covers edge cases and diagnostics, making it complete for an agent.

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

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

Schema coverage is 100% with all 9 parameters described. The description adds meaning beyond the schema by explaining tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) with practical examples and behavioral implications (e.g., 'Set to 5000 to drop thin-book opportunities').

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and 'return', the resource 'Polymarket markets', and distinguishes from sibling tools like 'polymarket_arbitrage' and 'polymarket_kalshi_spread' by focusing on model-driven, structural arbitrage, and concentrated longshot opportunities.

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 it is built for 'what should I bet on today' and explains the three model families with contexts (e.g., 'rare-by-design' for concentrated longshots). It provides limitations for Fed bets and explains knobs for filtering. However, it does not explicitly differentiate when to use this tool over siblings like 'polymarket_arbitrage'.

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

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

The description adds significant behavioral context beyond the annotations, including response structure (tracked, expired, snapshot_dates), computation details (trend, decay_pp_per_day), and data characteristics (daily closes, cache-miss gaps). No contradictions with annotations.

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

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

The description is detailed and front-loaded with the core purpose, followed by output breakdown and limitations. While slightly long, every sentence provides useful information without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response fields, their meanings, and operational details (e.g., snapshot gaps, decay calculation). It covers all necessary context for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100%, but the description adds defaults, clamps, and clarifies the 'window' parameter as a 'snapshot family'. This adds value beyond the schema definitions.

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

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

The description clearly states the tool's purpose as 'edge persistence and decay telemetry' and answers a specific question about edge age. It differentiates from the sibling 'polymarket_edges' by focusing on persistence over time rather than just current edges.

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

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

The description provides context for when to use the tool (e.g., understanding if an edge is fresh vs. decaying) and mentions limitations like the 60-day snapshot TTL. However, it does not explicitly state when not to use it or suggest alternatives.

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

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

The description adds significant behavioral context beyond the annotations, such as that it walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, and a verdict. It also discloses the risk of forced directional risk and thin legs. The annotations already indicate readOnlyHint=true, and the description aligns with that, so no contradiction.

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

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

The description is long but well-structured with clear sections (SINGLE-MARKET and BASKET) and bolded key terms. Every sentence adds value, though some consolidation might be possible. The front-loading is good with the core purpose stated first.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains what the tool returns in both modes, lists all output fields, provides usage context, and warns about risks. No important aspect seems 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?

While the input schema already provides parameter descriptions (100% coverage), the description adds substantial meaning by explaining the different interpretations of `size_usd` in single-market vs basket mode, specifying that exactly one of `market` or `event` is required, and detailing default behaviors. This goes well beyond the schema's simple 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 explicitly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket), making its purpose very clear. It also differentiates from sibling tools by specifying when to use it before acting on arb signals or trades above ~$500.

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

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

The description provides explicit guidance on when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It explains the two modes and warns about the risk of partial basket fills converting an arb into an unhedged directional position, which is the dominant loss mode.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral details: response format (leg-by-leg prices, top spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains when spreads are meaningless. No contradictions.

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

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

The description is dense but each sentence adds value. It is front-loaded with the core purpose. Minor verbosity could be trimmed (e.g., repeating 'pre-mapped' multiple times), but overall structure is logical 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?

Given the tool's complexity (two modes, compatibility checks, temporal alignment) and lack of output schema, the description fully explains the return structure and safety fields. It covers edge cases explicitly (e.g., matched_pairs:0 scenarios). No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the two modes, listing topic shortcuts, specifying that explicit tickers override topic, and detailing the relationship between parameters. This enriches the schema's raw info.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket. It distinguishes itself from siblings by focusing on spread calculation for equivalent outcomes, and explicitly describes two modes (topic shortcuts and explicit tickers). The purpose is specific and well-defined.

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

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

The description explains when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and includes compatibility warnings for non-tradeable cases. It sets expectations that pre-mapped topics often return warnings. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, but the context is sufficient for most use cases.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint; description adds scope (identifier-based) and dual behavior (key retrieval vs listing), which is useful but not critical.

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

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

Three concise sentences, front-loaded with the core action, no unnecessary words.

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

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

For a tool with one optional parameter and no output schema, the description fully explains input, behavior, and return possibilities.

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

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

Schema coverage is 100%, and description adds meaning: 'omit to list all keys' and explains the purpose of the key parameter beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted, distinguishing it from siblings like 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?

Explicitly says when to use (look up stored context) and provides context about scoping and pairing with remember/forget, giving clear 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?

The description explains that setting mark_read:true flags returned events as read, affecting subsequent calls. This adds behavioral context beyond the annotations (readOnlyHint, idempotentHint). However, there is a slight contradiction: readOnlyHint true implies no state change, but mark_read does modify state.

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: about 5 sentences, front-loaded with the main purpose, and each sentence adds specific value. No redundancy or irrelevant 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 5 optional parameters and no output schema, the description adequately explains the return fields, the effect of mark_read, and filtering options. It also mentions the alternative endpoint for other use cases. This covers the tool's functionality well.

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

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

Schema coverage is 100% with parameter descriptions. The description adds a concrete example for type (sec_8k) and clarifies that since expects an ISO timestamp. While the schema already documents parameters, the description provides useful usage hints.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the return fields (source, citation_uri, raw payload). This distinguishes it from siblings like list_subscriptions, which list subscriptions rather than fired events.

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

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

The description mentions that polls work fine and provides an alternative endpoint for scripts/dashboards. It gives filtering options (type, since) but does not explicitly state when not to use this tool or compare to alternatives beyond the same feed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: fans out to multiple sources, GDELT preferred with GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and return structure (changes grouped by source, total_changes count, citation URIs).

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

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

The description is a single dense paragraph containing all necessary information. It is front-loaded with purpose and examples. Slightly verbose but still efficient; could be structured with bullet points for readability, but not required.

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

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

No output schema provided, but description explains return structure (changes[] grouped, total_changes, citation URIs). Does not detail individual fields within changes, but given complexity of multiple sources, this is acceptable. Provides enough context for agent to understand output.

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

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

Schema coverage is 100% and description adds extra meaning: explains type (only company), since format with examples and relative shorthand (7d, 1m, 1y), value as ticker or CIK, and usage tip for monitoring. Provides more than schema alone.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with concrete query examples and a list of sources (SEC EDGAR, GDELT→GNews, USPTO). It also distinguishes from the sibling tool entity_profile.

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

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

Explicitly states when to use entity_profile instead (static profile regardless of window) and covers fallback behavior for GDELT→GNews. Provides practical guidance on the since parameter ('use 30d or 1m for typical monitoring').

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

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

Annotations indicate non-readOnly, non-destructive, idempotent. Description adds scope (scoped by identifier) and session vs. persistent memory (24h for anonymous, persistent for authenticated), providing valuable 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?

Four sentences, front-loaded with purpose, followed by usage, storage mechanics, and pairing with siblings. Every sentence is informative with no waste.

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 key aspects: purpose, when to use, storage details (key-value, scope, persistence), and sibling tools. No output schema needed for this simple store 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 key and value. The tool description reinforces this with examples but adds minimal new semantic nuance, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, specifying key-value storage scoped by identifier. It distinguishes from sibling tools like recall and forget.

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

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

Provides explicit guidance on when to use ('discover something worth carrying forward') and mentions pairing with recall/forget. Includes details on persistence based on authentication but lacks explicit when-not-to-use scenarios.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals internal cascading behavior and auto-disambiguation, adding value that annotations alone do not provide.

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

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

The description is well-structured with example queries upfront, followed by purpose and detailed type breakdowns. Every sentence adds value; no fluff.

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

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

Without an output schema, the description adequately explains return fields for each type. It could mention error handling or lookup failure cases, but overall it is sufficient for a read-only lookup tool.

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

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

Schema coverage is 100% with descriptions, but the description adds concrete examples (e.g., 'AAPL' for ticker, 'ozempic' for drug) and explains output per type, enhancing understanding beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific example queries and detailed output per type. It distinguishes itself from siblings like compare_entities and entity_profile by focusing on ID lookup.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides clear context but does not explicitly state when not to use or list alternatives, though the purpose is sufficiently clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: probes each entity, returns a ranked list with score/confidence/signal density, and treats the first entity as the subject. No contradictions with annotations.

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

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

The description consists of two sentences, each earning its place. The first sentence states the core functionality; the second provides an example and output details. No redundancy.

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

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

Given 4 parameters and no output schema, the description covers output format (ranked list with score, confidence, signal density) and explains purpose and usage. Minor gap: does not mention error handling or rate limits, but annotations already handle safety. Overall sufficient.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds semantic value by noting that the first entity is treated as the 'subject' for narrative purposes and extra clarification on model options (e.g., omitting models for default workers-ai). This goes slightly beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use or mention alternatives beyond the implied distinction from ai_visibility_check.

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

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

Annotations already indicate idempotent and read-only. The description adds transparency about partial failures, the 5-30s wait for bundlephobia first measurement, and the sources_failed field. Could be improved by mentioning any rate limits or quotas.

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

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

Description is somewhat long but front-loaded with purpose. Every sentence adds value, though a slight reduction in length could improve conciseness.

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

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

Given the complexity (composite of two external services, no output schema), the description explains the return structure (summary, advisories, links, alternatives) and partial failure behavior, making it fairly 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 already describes both parameters fully (100% coverage). The description adds context that version defaults to latest and that scoped packages are accepted, providing useful extra 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 it's a composite check for npm packages using deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying the NPM ecosystem and the combined functionality.

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 tells when to use: whenever an agent asks about safety, popularity, or cost of adding an npm package. Also notes that PyPI/Maven/Cargo/Go should use deps.dev directly, providing clear alternatives.

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

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

Adds detailed behavioral context beyond annotations: BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag, return of offsets and similarity scores. Annotations already provide readOnlyHint, idempotentHint, but description enriches understanding.

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, front-loaded with core action, each sentence adds unique value. No extraneous information.

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

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

Despite no output schema, description explains return format (passages with offsets and scores), processing details, truncation behavior, and pairing with another tool. Complete for the tool's complexity 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 has 100% coverage with descriptions. Description adds value: clarifies max chars for text, default for limit, and examples for query. Baseline 3, extra examples and nuances raise to 4.

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

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

Description clearly states 'Semantic search INSIDE a fetched record', specifying verb and resource. It distinguishes from siblings like ask_pipeworx_grounded by focusing on searching within a fetched record rather than grounding over passages.

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 how it pairs with ask_pipeworx_grounded for grounding. Implies not to use for small records.

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

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

The description goes far beyond annotations, detailing account requirements, supported event types, delivery channel behaviors (including SMS cap, webhook auto-disable, HMAC signing), and that the feed is always-on. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, etc.) are present.

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

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

The description is lengthy but well-structured and front-loaded with the primary action and return. Every sentence adds value, but some details (e.g., exact webhook signing algorithm) could be considered overly specific. However, given the complexity, it balances detail and clarity well.

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

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

The description covers all necessary context: required authentication, supported types with parameters, delivery options with limitations, and the always-on feed. It even mentions how to retrieve alerts (recent_alerts tool). No output schema exists, but the description states the return value (subscription id) and the one-time webhook secret.

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 adds significant meaning beyond the schema. For each type, it provides concrete examples (e.g., sec_8k items codes, polymarket_edge topics) and explains delivery channel details (webhook signing, phone verification). The schema already covers 100% of parameters, but the description enriches understanding and usage.

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

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

The description clearly states that the tool creates a proactive monitoring subscription to a live-data event stream, with clear verb and resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The return value (subscription id) is also specified.

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 guidance on when to use this tool: for creating persistent subscriptions with a Pipeworx OAuth account. It explicitly states that anonymous and BYO cannot persist subscriptions, setting expectations. However, it does not explicitly contrast with alternatives for simple one-time queries, but the tool's purpose is clear enough.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it returns example questions with exact tool+argument shapes drawn from a live catalog, and explains the no-argument vs topic-focus behavior. No contradictions with annotations.

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

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

The description is a single paragraph but efficiently packs all necessary information: common questions, return format, usage instructions, and parameter details. It is front-loaded with key trigger phrases. Could be slightly more structured with bullet points, but overall concise.

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

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

Given the tool's complexity as an onboarding discovery tool with one parameter and no output schema, the description adequately covers what to expect (category-bucketed examples with tool shapes) and how to use it. It is complete enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% (one optional parameter). Description adds meaning: lists valid topic values (finance, pharma, etc.) and explains that omitting the topic gives a cross-category spread. This goes beyond the schema description which only says 'Optional focus area'.

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 as the onboarding entry point for Pipeworx, listing common user queries like 'What can I ask Pipeworx?' and explaining it returns category-bucketed example questions. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by emphasizing its role as a first-use discovery tool.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' The optional topic parameter is described with focus areas. While no direct exclusions are stated, the context implies when to use this tool versus alternatives.

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

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

Beyond annotations (idempotent, non-destructive), the description reveals that the row is deactivated not deleted, preserving history. Adds valuable behavioral context without contradiction.

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

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

Two concise sentences front-load the action and then add constraints. No wasted words, 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 simple one-param tool with no output schema, the description fully covers purpose, constraint, and behavioral nuance. 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% and describes the 'id' parameter. The description does not add extra meaning beyond what's in the schema, so baseline 3.

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

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

The description clearly states 'Cancel a subscription by id' which is a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly notes ownership enforcement, implying when not to use (cannot cancel others). No alternative tools named, but context is clear given sibling list.

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 the data source (SEC EDGAR + XBRL), return fields (verdict, structured form, actual value, citation, delta), and the efficiency gain (replaces multiple 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 moderately long but front-loaded with usage examples and a clear purpose. Every sentence adds value, and the structure (examples, use case, supported domain, return info) is logical.

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 adequately explains return values (verdict, structured form, actual value, citation, percent delta). It also covers the single parameter well. Completeness is high for a tool with a single parameter and no 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?

Schema coverage is 100% with a clear description for the single 'claim' parameter. The description adds meaning by specifying the types of claims (company-financial) and providing example phrasing, which goes beyond the schema's generic description.

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

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

The description uses specific verbs like 'verify', 'confirm or refute' and identifies a clear resource: natural-language claim verification against authoritative sources. It distinguishes itself by explicitly replacing 4–6 sequential calls, setting it apart from sibling tools.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain (company-financial claims for public US companies). It lacks explicit when-not-to-use instructions but the domain restriction is clear.

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