Data Pa

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint; description adds cost implications (free vs. BYO), default model, and response structure. No contradictions; provides 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?

Two sentences with clear front-loading of action and output. No unnecessary words; each part 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?

Explains return format despite no output schema, covers inputs and use cases. Lacks mention of rate limits or error handling for invalid API keys, but overall adequate for the complexity.

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

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

Schema coverage is 100% with descriptions; description adds examples for entity, clarifies default model behavior, and explains _apiKey pass-through. Adds meaningful 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?

Description clearly states verb 'Probe' and resource 'LLMs for visibility about an entity', with specific output format and use cases. Distinguishes from siblings like entity_profile or scan_competitor_ai_presence by focusing on AI knowledge 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?

Describes when to use (AI-marketing audits, etc.) and mentions default vs. paid model, but lacks explicit when-not-to-use or alternatives. Usage guidance is implied rather than explicit.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: routing to 4,396 tools, returning structured answers with stable pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is slightly long but front-loaded with the key guidance ('PREFER OVER WEB SEARCH'). It includes multiple examples and alternatives, each sentence adding value. Could be tightened by removing redundant example list, but still well-structured.

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

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

For a complex tool (6 params but only 1 required, no output schema), the description covers purpose, usage, alternatives, and return characteristics (structured answers with citations). It does not detail error handling or rate limits, but annotations cover safety. Adequate for the agent's selection needs.

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 the question parameter and its aliases. The description does not add per-parameter semantics beyond the schema, but it does guide the type of questions appropriate, which indirectly helps. Baseline 3 is appropriate as schema carries the load.

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

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

The description uses specific verbs ('ask', 'routes', 'returns') and resource ('Pipeworx tool system with 4,396 tools across 1,102 sources'). It clearly distinguishes from siblings by naming alternatives like 'ask_pipeworx_grounded' and 'deep_research', and lists dozens of concrete data domains (SEC filings, FDA data, etc.).

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 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance with examples ('current US unemployment rate', etc.). It also specifies when to step up to alternatives ('ask_pipeworx_grounded for verbatim evidence', 'deep_research for broad questions') and when not to use (breaking news routes already).

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 context about refusal reasons, extra LLM cost, and that it extracts only from tool result. 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 somewhat long but well-structured with clear purpose, usage guidance, and returns details. Front-loads key info. Could be slightly more concise but still effective.

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

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

Despite no output schema, the description comprehensively covers success and failure return structures, including refusal reasons. It explains the extra LLM call and when to prefer the cheaper variant, making it complete for this complex 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 has 6 parameters but all are aliases for 'question'. Schema coverage is 100% with descriptions. The description clarifies the parameter is a natural language question and lists aliases, adding 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 explicitly states it's a 'hallucination-resistant answer mode for high-stakes reads' and details the process: routing, fetching, extracting. It distinguishes from sibling 'ask_pipeworx' by noting the extra LLM call and specific use cases.

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: use when answers will be quoted, cited, or acted on (e.g., financial verdicts, legal claims, medical lookups, public statements) and recommends preferring 'ask_pipeworx' for casual 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?

The description goes far beyond annotations (readOnlyHint, etc.) by detailing fan-out behavior, market matching confidence levels, blocking conditions for low-confidence and closed markets, tradeability warnings, and resolution-rule risk. 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 very long and contains extensive detail, which is partly justified by tool complexity. It is front-loaded and well-structured (sections for classifiers, fan-out examples, response shapes). However, some redundancy and over-explanation reduce 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?

With no output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence, resolver contract, parent event extractor, news fields, safety behaviors). It covers matching, fan-out, edge cases, and blocking conditions, leaving no ambiguity 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?

The input schema already provides 100% parameter descriptions. The tool description adds value by explaining input formats for 'market', the effect of 'depth', and the implications of 'include_raw' (e.g., summary vs. full payloads). This supplements the schema well.

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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'research' and resource 'Polymarket bet', and distinguishes from siblings (e.g., validate_claim, ask_pipeworx) by offering comprehensive evidence packing.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). However, it does not explicitly say when not to use it or mention alternatives, which would further clarify usage boundaries.

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. Description adds specifics: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), fiscal year handling, sorting by primary metric, and citation URIs. 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?

Slightly long but well-structured with front-loaded purpose, query examples, usage guideline, and data details. Every sentence adds value; could be trimmed slightly but remains effective.

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

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

Given complexity (two entity types, multiple data sources, no output schema), description adequately covers behavior, data sources, and return format (paired data + citations). Missing explicit output fields but reasonable for a tool with 100% schema coverage.

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 all 2 parameters with 100% description. Description adds concrete examples (tickers/CIKs, drug names) and explains behavior per type, adding 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 compares 2-5 entities side-by-side, with specific verbs like 'compare' and 'side-by-side comparison'. It distinguishes from sibling tools like 'entity_profile' by emphasizing multi-entity comparison and replacing sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and provides example query patterns. The sibling 'entity_profile' is implicitly the alternative for single entities.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, etc.). The description adds valuable behavioral details: it returns specific fields (resource_id, name, description, category, update date) and advises on subsequent tool usage.

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, front-loaded with action and resource, every word earns its place. Perfectly sized.

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 100% schema coverage, full annotations, and no output schema, the description is complete. It explains the tool's purpose, return fields, and how to use the result, leaving no gaps.

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

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

Schema covers all three parameters with descriptions (100% coverage). The tool description adds no additional parameter-level meaning beyond what the schema provides, 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 uses a specific verb ('Search') and resource ('Pennsylvania Open Data catalog'), clearly stating action and scope. It also distinguishes from siblings by mentioning that the returned resource_id should be passed to 'query/metadata'.

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 (search by keyword) and hints at next steps (pass resource_id to other tools), providing clear context without explicit exclusions.

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

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

Discloses account requirements, parallel execution, return format (findings packet with evidence, confidence, gaps), and expected latency (15-60s). Annotations already indicate read-only, open-world, idempotent traits; description adds rich 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?

Despite length, every sentence adds necessary information. Front-loaded with critical account requirement. No filler; structured with clear sections. Concise for the level of detail needed.

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 fully explains the return structure (findings packet with citations, gaps) and expected latency. Addresses account tiers, data sources, and decomposition. Complete for a complex 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%, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8 requires paid plan) and clarifies that question can be broad/multi-part. Adds value beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1102 structured data sources in one call. It distinguishes from siblings like ask_pipeworx for single lookups and current news, 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?

Explicit guidelines on when to use (broad/multi-part questions over structured data) and when not (single lookups, breaking news). Also provides alternative tool (ask_pipeworx) for non-signed-in users and for news. Covers context thoroughly.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Description adds value by detailing return structure (top-N, names, descriptions, schemas) and readiness to call directly.

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

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

Front-loaded with purpose, every sentence adds value, well-structured with examples and clear guidance. Efficient for its information density.

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

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

Despite no output schema, description fully explains what is returned (tools, descriptions, schemas) and when to use. No missing context needed for 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%. Description enriches meaning with examples (e.g., 'analyze housing market trends'), explains natural language acceptance, and lists aliases.

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 finds tools by describing data/task, lists many domains, and distinguishes from siblings like query or deep_research by emphasizing discovery over execution.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and examples.

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

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

Description adds behavioral context beyond annotations: parallel fan-out across sources, patent sunset status, URI generation for filings. Annotations already indicate read-only and idempotent; description aligns and enriches.

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 informative but somewhat verbose; could be tightened slightly. However, it is front-loaded with examples and key instructions, making it usable despite length.

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

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

Given the tool's complexity and no output schema, the description adequately explains outputs (cik, filings, fundamentals, patents, news, LEI) and limitations (patents sunset, name dependency). Missing minor details like pagination or rate limits, but sufficient 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 baseline is 3. Description adds value by explaining type/value meanings, providing examples (AAPL, CIK), and clarifying name restriction, which goes beyond schema descriptions.

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

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

Description clearly states the tool provides a holistic cross-source profile of US public companies in one parallel call. It lists example queries and specifies it aggregates data from multiple sources, distinguishing it from siblings like resolve_entity 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 states when to prefer this tool (holistic view over chained lookups) and when not to use it (if only a name, use resolve_entity first). Also notes patent soft-failure caveat.

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 adds no behavioral context beyond confirming deletion, which is already implied. No contradiction.

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

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

Three sentences: core function, usage guidance, and pairing with siblings. No fluff, every sentence serves a 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?

For a simple delete tool with single parameter and no output schema, description fully covers purpose, usage, and relationships. Complete for its 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 one parameter. Description adds 'Memory key' providing semantic context that it's a key for stored memories, adding 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?

Description clearly states 'Delete a previously stored memory by key' which is a specific verb+resource action, and distinguishes it from sibling tools 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly provides when to use: 'stale context, task done, clear sensitive data'. Mentions companion tools, giving context for appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds behavioral detail: fetches page, extracts title/description/key links, emits standard markdown, and outputs a single text blob. It does not mention error handling or rate limits, but annotations already indicate safe operation.

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 purpose and output, no wasted words. Every sentence contributes to understanding.

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 low complexity (2 params, no output schema, safe operation), the description covers all necessary aspects: purpose, behavior, output format, and use cases. Annotations provide sufficient safety 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?

Input schema has 100% description coverage for both parameters. The description reinforces the 'url' parameter with an example and clarifies its scope. It adds marginal value beyond the schema, slightly improving clarity for an agent.

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 generates a production-ready llms.txt file for any URL, specifying the verb ('generate'), resource ('llms.txt'), and target audience (AI crawlers). It distinguishes from sibling tools, none of which offer this 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?

The description provides concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors), giving clear context for when to use. However, it does not explicitly mention when not to use or suggest alternative tools, though none are obvious.

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, etc. Description adds return field details (id, type, params, timestamps) and parameter behavior (include_inactive). No contradictions.

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

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

Two concise sentences; first explains purpose and output, second gives usage guidance. 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?

For a simple list tool with good annotations and one optional parameter, the description fully covers what is needed.

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 description adds no extra meaning beyond the schema's description of 'include_inactive'. 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. 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?

Explicit advice: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific return fields (columns, types, row count, category, last-updated), providing useful 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?

Single sentence with no extraneous details. Includes a concrete example, making it highly concise and structured.

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

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

Given the simple purpose, one parameter, and clear annotations, the description is fully complete. It specifies what data is returned and how to invoke the tool.

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

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

Schema coverage is 100% for the single parameter. The description adds value by providing an example ('mcba-yywm') and specifying the parameter is a resource_id, 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 gets schema and metadata of a Pennsylvania Open Data dataset using a resource_id, with a specific example. It distinguishes from siblings like 'datasets' by focusing on metadata 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?

No explicit guidance on when to use this tool versus alternatives. It implies usage when dataset metadata is needed but lacks when-not-to-use or sibling comparisons.

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

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

The description goes beyond annotations (which are all false) by revealing rate-limiting, free usage, no quota impact, and that feedback is read daily and influences the roadmap. This provides critical behavioral context for the agent.

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 and well-structured: starts with the core action, then offers usage conditions, then restrictions (rate limit, quota). Every sentence adds necessary information without 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?

Despite no output schema, the description adequately explains the outcome (team reads digests, influences roadmap) and covers all aspects: when to use, what to include, constraints on usage and content.

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?

With 100% schema coverage, the description adds value by advising not to paste the end-user prompt and recommending concise, tool-focused messages. It reinforces the parameter meanings without redundancy, earning a high score.

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: sending feedback (bugs, features, data gaps, praise) to the Pipeworx team. It specifies the exact use cases and distinguishes itself from unrelated sibling tools by focusing on feedback submission.

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 each feedback type (wrong/stale data -> bug, missing tool -> feature/data_gap, etc.) and what not to do (don't paste end-user prompt). It also details rate limits (5/day) and that it's free, which helps the agent decide to use this tool.

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

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

Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data source and caching behavior, going 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 4-5 sentences, front-loaded with the result. Every sentence adds value, including the self-aggregation and caching notes. No superfluous text.

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 1 optional parameter, no output schema, and annotations covering safety, the description fully explains what the tool returns, uses, and caching. Complete for the tool's simplicity.

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% for the single parameter with enum. The description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides practical guidance 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 returns 'top tools, top packs, and total call volume' for recent windows. The verb 'returns' and specific resource 'what other AI agents are calling on Pipeworx' distinguish it from sibling tools like discover_tools, which is for discovering tools in general.

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 the canonical choice, and aligning use case. It does not directly state when not to use it, but the context is 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond, detailing the semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder rejection), fill check against live CLOB depth, and edge cases. 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 every sentence adds necessary detail for a complex tool. It is well-structured with clear sections for each mode, but slightly verbose for an agent to parse quickly. Front-loaded with the requirement.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array, partition_check object, fill check results) and how each component works. Covers both modes, edge cases, and recommended usage, making it complete for an AI agent.

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

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

Schema covers both parameters completely (100%). The description adds value by providing example slugs, explaining that full URLs work, and clarifying the distinction between event and topic modes with concrete use cases.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It explains two modes (event and topic) and provides concrete examples. This distinguishes it 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 'REQUIRES one of event or topic', describes when to use each mode (event for a specific market, topic for cross-event scanning), and notes that calling with no args fails. Also points to polymarket_fill_risk for custom sizing, providing clear 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?

The description extensively details behavioral traits beyond annotations: edge calculation (edge_pp_net, kelly_fraction), slippage, 24h-move warnings, caching (1h at KV level), and diagnostics. Annotations already declare readOnlyHint=true, so the description adds valuable context about the tool's operation and 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 extremely long and dense, containing detailed model formulas and nested logic that could be simplified. While well-structured with sections, it is not concise and may overwhelm an agent scanning for 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 tool's complexity (9 parameters, no output schema, three response segments), the description is remarkably complete. It explains the response structure (by_segment, diagnostics, fed_candidates), edge cases where segments may be empty, and the rationale behind model families. No output schema exists, so this textual description fully compensates.

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

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

Despite 100% schema coverage, the description adds significant meaning: each parameter's purpose (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity), usage advice (e.g., 'Bump for very thin partitions'), and explanations of how filters interact (e.g., min_kelly vs min_partition_leg_kelly). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings by focusing on three specific model families (model_driven, structural_arbitrage, concentrated_longshot) and is explicitly built for the 'what should I bet on today' use case.

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

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

The description provides clear context for when to use the tool ('discover opportunities without paging hundreds of markets') and includes tradeable-edge knobs for filtering. While it does not directly state alternatives, the sibling list includes similar tools (e.g., polymarket_arbitrage) and the description implies this is the daily scanning 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 indicate read-only and idempotent behavior. Description adds value by explaining computation (daily closes of edge_pp_net), data gaps (snapshot writes on cache-miss), and limits (60-day TTL). 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?

Front-loaded with purpose and example, then details response fields and limitations. Dense but efficient; could benefit from bullet points but remains informative without 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?

No output schema, so description fully explains all three response components (tracked, expired, snapshot_dates) with field details, plus limitations. Covers what the agent needs to 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 already describes both parameters with 100% coverage. Description adds default values (days=14, window=1wk) and clarifies 'window' as snapshot family, but adds limited extra meaning 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?

Clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity and freshness. Distinguishes from sibling 'polymarket_edges' by focusing on historical tracking.

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 decision guidance through the example contrasting fresh vs. old wide edges, and explains response structure for usage. Lacks explicit when-not-to-use or alternative tool references, but context is 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 details internal behavior (walking the order book ladder, calculating slippage), return fields (top_of_book, vwap_fill_price, verdict, etc.), and risks (partial basket fills leading to unhedged positions). Annotations already confirm readOnly, idempotent, and non-destructive, and the description adds valuable context beyond those.

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 front-loaded with the core purpose. Every sentence adds necessary detail given the tool's complexity. It could be slightly more concise by grouping related details, but the trade-off for completeness is acceptable.

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 values for both modes, including per-leg detail and risk indicators. It covers the main operational aspects but does not address error scenarios or validation of inputs (e.g., non-existent slugs). Overall, it is adequate for agent understanding.

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 4 parameters described), but the description adds significant meaning: explains how `size_usd` is interpreted differently in single-market vs basket mode, specifies default values for `side` and `size_usd`, and clarifies that `side` auto-defaults in basket mode based on partition sum. This greatly enriches the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with explicit modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it before those 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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and provides rationale about thin books and partial fills, giving clear guidance on when and why to use this tool.

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

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

Annotations already declare readOnly and idempotent, but the description adds rich behavioral context: compatibility_warning triggers, temporal alignment significance, skipped_cross_type meanings, and the real-world rarity of tradeable spreads. 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?

Well-structured with clear sections (intro, modes, response, safety, warning). Front-loaded with purpose. However, the safety fields and explanation are somewhat lengthy; could be trimmed slightly without losing meaning for a more agent-friendly length.

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

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

Despite no output schema, the description thoroughly explains all relevant aspects: how to use, what to expect in response, edge cases (compatibility, temporal alignment, skipped comparisons), and limitations. Nothing significant 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 coverage is 100% with good parameter descriptions. The description adds value by explaining the relationship between parameters (topic vs override), and provides concrete examples. Slightly above baseline because it clarifies mode interactions.

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: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairs) and distinguishes it from sibling tools by focusing on cross-venue differences.

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

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

Provides clear context on when to use each mode and warns that pre-mapped topics often yield compatibility warnings, discouraging blind reliance. However, it does not explicitly state when to use an alternative tool like polymarket_arbitrage or when the spread is not applicable.

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 read-only, idempotent, non-destructive, and open-world hints. The description adds that it returns JSON rows, but lacks detail on defaults (e.g., limit=1000) or error behavior. Minimal additional value over annotations.

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

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

Two sentences, zero wasted words. Essential information is front-loaded, and the structure is optimal.

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 rich annotations and 7 params (all documented), the description covers purpose, parameters, and return format. Minor gaps like default limit or pagination guidance are addressed by schema or annotations, leaving the description adequately 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%, meeting baseline of 3. The description adds value by noting SoQL clauses should omit the leading '$' and giving an example resource_id, aiding parameter usage beyond schema descriptions.

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

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

The description clearly states the tool runs a Socrata SoQL query against a specific Pennsylvania Open Data dataset using resource_id. It lists filtering capabilities and provides an example, making the purpose highly specific and 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?

While no explicit 'when not to use' is given, the tool is unique among siblings (no alternative query tool), so usage context is implicit. The description effectively communicates its domain without needing exclusion 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?

While annotations already indicate read-only and idempotent behavior, the description adds value by explaining the dual retrieval/list functionality and scoping to identifier. It does not contradict annotations.

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

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

The description is a single, well-structured paragraph. Every sentence is informative and necessary. No redundant wording.

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 retrieval tool with no output schema, the description sufficiently explains what the tool returns (a value or list of keys). It covers use cases, scoping, and pairing with siblings.

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 one parameter described. The description adds extra semantics: 'omit the key argument to list all keys', which provides context beyond the schema.

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

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

The description clearly states the action (retrieve/list) and resource (saved values/keys). It distinguishes from siblings by mentioning 'remember' and 'forget'. Verb+resource is specific and unambiguous.

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

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

Provides explicit guidance on when to use: 'to look up context the agent stored earlier'. Mentions alternatives ('Pair with remember to save, forget to delete') and scoping information ('Scoped to your identifier').

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 safe read operations, and the description adds behavioral details: setting mark_read:true flags events as read, and returned events include source, citation_uri, and raw payload. 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 concise, front-loading the purpose and then detailing parameters. It is efficiently structured without 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?

With no output schema, the description explains return values (source, citation_uri, payload). All five parameters are covered, and the tool's behavior is well-described, making it complete 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%, so the baseline is 3. The description adds context on parameter usage, such as filtering by type, since ISO timestamp, and the effect of mark_read, 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 starts with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It is specific enough to distinguish from sibling tools like list_subscriptions, which list subscriptions but do not fetch 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 polling works fine and provides an alternative endpoint for scripts and dashboards, guiding when to use this tool versus external access. However, it does not explicitly state when not to use it or compare directly to 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?

Discloses fan-out to multiple sources, GDELT→GNews fallback behavior, and soft-failure for PatentsView. Annotations already declare readOnly, openWorld, idempotent; description adds meaningful 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?

Dense but clear, front-loaded with example queries. Every sentence adds value 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?

With no output schema, description explains return structure (changes[] grouped, total_changes, citation URIs). Adequately covers behavior and fallbacks.

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%, but description adds value by explaining since format (ISO date or relative shorthand with examples), value as ticker/CIK, and type restriction.

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 provides a change feed for a company, covering SEC filings, news, and patents. Differentiates from sibling entity_profile for static profiles.

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

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

Provides explicit example queries and when to use vs entity_profile. Explains fallback logic between GDELT and GNews based on rate limits/errors.

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 idempotentHint true and destructiveHint false, but description adds context: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 front-loaded with purpose, followed by usage guidance and technical details. Every sentence adds value, no redundancy. Efficient and clear.

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

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

With 2 parameters and no output schema, the description provides complete context: scope, persistence, and pairing with recall/forget. Sufficient 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?

Input schema covers 100% of parameters with descriptions. The description adds examples of keys (e.g., 'subject_property', 'target_ticker'), enhancing understanding beyond schema. Baseline 3 with slight improvement.

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 across conversations or sessions. It specifies verb 'Save', resource 'data', and distinguishes itself from siblings 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?

Explicitly says when to use: 'when you discover something worth carrying forward...so you don't have to look it up again.' Also pairs with 'recall' and 'forget' for retrieval and deletion, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds beyond annotations by noting internal cascading through multiple endpoints and replacing 2-3 manual lookups. However, it does not disclose potential failure modes (e.g., unresolvable names) or rate limits.

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 that front-loads examples and usage guidance. It is efficient but could benefit from bullet points for the two types to improve scanability. Every sentence adds value; 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?

Despite lacking an output schema, the description explains return values for each type (including citation URIs) and the internal cascading behavior. For a tool with only 2 required params and no nested objects, this is largely complete. Missing details on error handling or ambiguous input resolution.

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 parameters. The description enriches by providing concrete examples for value ('AAPL', '0000320193', 'ozempic') and clarifying output mapping per type. This adds practical context beyond the schema's generic 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 starts with concrete example queries, then clearly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It specifies verb (resolve), resource (name to ID), and scope (multiple entity types). This unequivocally distinguishes it from siblings like entity_profile or 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?

The description explicitly directs: 'Use FIRST whenever you have a name but need an ID.' It provides clear context for when to use (name-to-ID scenarios) and implicitly excludes cases where an ID is already known. The supported types section further clarifies acceptable inputs per entity type.

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, destructiveHint=false. The description adds value by explaining the internal mechanism ('Probes each entity... with ai_visibility_check') and the output structure ('ranked list with score, confidence, signal density per entity'). No contradictions.

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

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

The description is three sentences long, front-loaded with purpose and action, followed by a use case and return format. Every sentence serves a purpose, no redundancy.

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

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

The tool has no output schema, but the description specifies the return structure: 'ranked list with score, confidence, signal density per entity.' All 4 parameters are documented, and the context (2-8 entities, first as subject) is clear. The description is fully adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context: the first entity in the array is treated as the 'subject' for narrative, and the tool uses 'ai_visibility_check' internally. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs like 'probes,' 'ranks,' and 'surfaces,' and distinguishes itself from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (likely different 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 concrete use case: 'competitive AI-marketing audits' with an example question. It implies when to use it (comparing multiple entities) versus alternatives (single entity check via ai_visibility_check). However, it does not explicitly state when not to use it or list alternatives.

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

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

The description goes well beyond the annotations (which already indicate readOnly, idempotent, non-destructive). It explains composite behavior, partial failures (bundlephobia initial measurement 5-30s timeout), graceful degradation, and that sources_failed will list timeouts. This is rich behavioral context.

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

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

The description is somewhat long but well-structured with clear front-loading of purpose. Each sentence adds value, covering purpose, usage, behavior, limitations, and return data. Minor redundancy, but overall 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 complexity (composite API, partial failures, timing), the description thoroughly covers all aspects: ecosystem limitation, return structure (summary, advisories, links, alternatives), and fallback behavior. No output schema exists, so the description compensates 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 descriptions for both parameters. The description adds value by noting scoped packages are accepted for 'package' and that 'version' defaults to latest. This exceeds the baseline of 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 uses a specific verb ('scan') and resource ('dependency'), clearly stating it's a composite check for npm packages addressing questions like 'is X safe / popular / small'. It distinguishes itself from siblings by noting that other ecosystems (PyPI, Maven, etc.) fall under a different 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?

Explicitly tells when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. It also scopes the ecosystem (NPM only v1) and points to alternatives (deps.dev:version) for other ecosystems, providing 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?

Annotations already declare safe read-only behavior. The description adds technical details (BGE-base-en embeddings, cosine, 500-char windows, cap, truncation flag) and confirms returns passages with offsets and scores. 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?

Every sentence adds value. Front-loaded with purpose and usage, then technical details. Efficiently written.

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 3-param tool with no output schema, the description explains return format (passages, offsets, scores), truncation behavior, and pairing advice. Complete for the 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?

Schema coverage is 100%, so description adds minimal new meaning beyond examples and defaults. It repeats schema descriptions for text and query, but provides useful examples for query.

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 'Semantic search INSIDE a fetched record' with a clear verb and resource. It distinguishes from siblings by mentioning pairing 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 says 'Use when the record is too big to cram into the prompt' and names an alternative (ask_pipeworx_grounded) with guidance on how to pair them.

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 and description align: readOnlyHint=false indicates write, description explains subscription creation. Adds behavioral details like idempotent creation, verification requirements, and rate limits 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?

Packed with information and well-structured, but slightly lengthy. Front-loaded with purpose, then organized into types and delivery. Minor verbosity but still effective.

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

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

Covers all aspects: prerequisites, type-specific parameters, delivery channels with verification and rate limits, webhook signing details, and always-on feed. Complete for agent decision-making.

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 context: explains each enum value, provides detailed parameter objects per subscription type, and explains delivery channel options with constraints. No repetition of schema details.

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 creates a proactive monitoring subscription and returns the new subscription id. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of persistent 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 requires Pipeworx OAuth account, lists supported types with examples, and details delivery channel constraints including SMS verification and daily cap. Provides clear when-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context by explaining the tool is an onboarding entry point that returns example questions drawn from a live catalog, without contradicting any 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?

Front-loaded with the primary purpose, followed by return content and usage instructions. Every sentence is informative and necessary; no redundancy.

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

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

Given the tool has one optional parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage, and return structure, leaving no gaps for an agent to misunderstand.

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 explaining the default behavior when topic is omitted and providing concrete examples of topic values, enhancing understandability.

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 category-bucketed example questions with tool+argument shapes, and explicitly differentiates it from sibling meta-tools like ask_pipeworx and compare_entities by positioning it as the first tool to use for onboarding.

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 the tool ('use this FIRST'), provides calling conventions (no args for full spread, optional topic to focus), and lists alternative meta-tools for further actions.

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

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

Description adds behavioral context beyond annotations: ownership enforcement and that the row is deactivated (not deleted), preserving historical events. Annotations already indicate idempotent and non-destructive, so 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?

Extremely concise: two sentences with no wasted words. The first sentence states the purpose and constraint; the second explains the behavioral effect.

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

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

Given a simple single-parameter tool with no output schema, the description covers ownership enforcement and deactivation behavior. It is complete enough for its 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 provides full coverage (100%) with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' Description does not add additional semantics beyond the schema.

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

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

Description clearly states the action ('Cancel a subscription by id') and the resource (subscription), with ownership constraint. It distinguishes itself 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?

Ownership enforcement is clearly stated ('you can only cancel your own subscriptions'), guiding the agent on permissible usage. However, no explicit when-not-to-use 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?

Beyond annotations (readOnly, idempotent, openWorld), the description adds significant behavioral details: returns verdict types, extracted structured form, actual value with pipeworx:// citation, percent delta, and replaces multiple 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 concise at ~6 sentences, front-loaded with trigger phrases and purpose. Every sentence adds value: usage, scope, returns, efficiency. 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?

Given no output schema, the description fully explains what the tool returns (verdict, structured form, value, citation, delta). It covers purpose, usage, domain, and behavioral aspects, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with a clear 'claim' parameter description. The tool description adds value by explaining the parameter's role in the overall claim verification process and efficiency benefits, justifying a score above the baseline of 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 explicitly states the tool validates natural-language factual claims against authoritative sources, using trigger phrases like 'Is it true that…'. It clearly differentiates from siblings by specifying it is for claim verification with a verdict output, not general querying or research.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits scope to company-financial claims. It provides clear context but does not explicitly list when not to use or name alternative tools, though the domain restriction implicitly guides usage.

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