Photon

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: the default model, that a BYO API key is required for certain models, and the structure of the return value (per-model score, confidence, signals, raw_response plus combined view). 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 concise at four sentences, front-loaded with the core purpose, and every sentence adds value. 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 the tool's moderate complexity (4 parameters, 1 required), no output schema, and good annotations, the description fully covers what is needed: it explains the return format, probing behavior, and parameter dependencies. The agent can correctly select and invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model for the 'models' parameter, that '_apiKey' is only needed for Anthropic, and that 'context' helps disambiguate. This extra context justifies a 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?

The description clearly states what the tool does: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe', 'score') and identifies the resource ('LLMs') and the subject ('business / brand / product / topic'). This distinguishes it from sibling tools, which have different purposes.

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

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

The description provides clear context for when to use this tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when not to use it or mention alternatives among the longer sibling list, which would improve clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds context about routing, structured answers with citation URIs, and tier compatibility. 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 somewhat long but well-structured with priority statement, usage guidance, examples, and clear alternatives. Information is front-loaded and each 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 tool's complexity (routing to 4,396 tools across 1,102 sources), the description is comprehensive. No output schema needed for a Q&A tool. Covers all necessary context 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 has 100% coverage with aliases and examples. Description reinforces by explaining the tool's behavior and providing canonical usage. 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 answers questions about current/historical data across many domains, routes to the correct tool, and distinguishes itself from web search and sibling tools 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 'PREFER OVER WEB SEARCH' and provides clear when-to-use and when-not-to-use guidance, including steps to upgrade to alternatives for specific needs. Includes concrete 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?

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns explicit refusal reasons (e.g., 'not_in_source', 'no_tool_match') and notes the cost of 'one extra LLM call vs ask_pipeworx.' No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose and usage guidelines. It is relatively detailed (4 sentences), but each sentence adds value. Slightly verbose for maximum conciseness, but still efficient.

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

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

Given the complexity (6 parameters, 100% schema coverage, no output schema), the description is complete. It details the return format on success and failure, refusal reasons, and the distinction from ask_pipeworx. No gaps remain for effective tool selection and invocation.

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

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

Schema description coverage is 100%; the schema already documents all parameters and their aliases. The description mentions the question aliases (q, text, input, query, prompt) but does not add significant semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a 'Hallucination-resistant answer mode for high-stakes reads.' It explains the process: picks the right tool, fetches data, extracts answer using only the tool result. It distinguishes from the sibling tool ask_pipeworx by highlighting the extra extraction step and use case for high-stakes scenarios.

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 guides when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Provides specific domains: 'financial verdicts, legal claims, medical lookups, public statements.' Also advises preferring ask_pipeworx for casual lookups, giving a clear alternative.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description goes far beyond by detailing fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, and cancellation rule parsing. 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 and detailed with multiple sections. It is well-structured with headers, but contains more information than necessary for an agent's quick understanding. Front-loaded with purpose, but overall not 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 complexity of the tool (fan-out, resolver, parent event, risk), the description is fully complete. It covers all response shapes, edge cases (low confidence, closed markets, wide spread), and resolution rule risk. No output schema, so the thorough description of outputs is essential and 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 covers all 3 parameters with 100% description coverage. The description adds examples for 'market' (slug, URL, question), explains 'depth' (quick vs thorough), and clarifies 'include_raw' (summary vs full payload). 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 verb 'Research' and the resource 'Polymarket bet', and specifies inputs (slug, URL, question text). It distinguishes from sibling tools like 'polymarket_edges' by focusing on pulling comprehensive Pipeworx 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?

Explicitly mentions use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Provides situational guidance: low-confidence matches short-circuit, closed markets skip fan-out, wide spreads carry notes. Lacks explicit when-not-to-use but covers key 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: for companies pulls latest 10-K financials handling off-calendar fiscal years; for drugs pulls FAERS counts, FDA approvals, trial counts. Results sorted by primary metric. Returns citation URIs. Slightly more detail on sorting and citations would improve transparency.

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

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

Description is moderately concise and front-loaded with example intent phrases. Some repetition ('ALWAYS PREFER' appears both at start and end) could be trimmed. Generally efficient, 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?

For a 2-param tool with no output schema and 100% schema coverage, description provides adequate context about data sources, entity types, and sorting behavior. Could mention potential error cases or response format more explicitly, but 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 covers both parameters with good descriptions. Description adds extra meaning: clarifies values for company are tickers/CIKs, for drug are names, and explains what each type returns (financials vs. regulatory/trial data). This extends 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 tool performs side-by-side comparison of 2-5 companies or drugs. Uses specific verbs like 'compare' and gives example queries. Distinguishes from sibling tools like entity_profile which handles single entities, and from 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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use. Gives example natural language triggers and states it replaces 8-15 sequential 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?

Discloses account requirement, paid plan needs for 'thorough' depth, expected latency (15-60s), and output format (findings packet with evidence, confidence, source, citation). Includes guarantee of never inventing data (gaps[]). All consistent with readOnlyHint, openWorldHint, idempotentHint, destructiveHint 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?

Description is front-loaded with critical info (account requirement, alternatives). Every sentence adds value, though slightly long. Well-organized but could be more compact without losing substance.

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

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

Fully compensates for lack of output schema by detailing response structure. Covers all key aspects: prerequisites, fallback tools, scope, behavior, timing, and output guarantees. Complete for a complex research tool.

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

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

Both parameters have schema descriptions (100% coverage). The description adds value by explaining depth values (quick=3, standard=5, thorough=8) and clarifying that question can be broad/multi-part, beyond the schema's generic text.

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 performs 'grounded multi-source research' across 1102 structured data sources, decomposing questions into facets and routing to 4,396 tools in parallel. It clearly distinguishes from siblings like ask_pipeworx and is specific about what it does.

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

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

Provides explicit guidance: use ask_pipeworx if not signed in, for single lookups, or for breaking news; for broad/multi-part structured data questions use deep_research. Includes tier requirements and timing expectations.

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 safety traits (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral detail: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)', and that results are 'ready to call directly, no second schema lookup needed'. 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, well-structured with front-loaded purpose. Each sentence adds value. Minor redundancy in listing domains but still 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?

The description explains the tool's return structure and use case comprehensively. No output schema is present, but the description compensates by detailing what is returned. For a meta-tool, this is 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%, so baseline 3. The description adds context: lists aliases for 'query' parameter and mentions default/max for 'limit', which is not in the schema examples. This helps the agent understand parameter flexibility.

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

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

The description uses a specific verb ('find', 'discover') and resource ('tools'), and explicitly lists supported domains and returns full schemas. It distinguishes from siblings by positioning itself as the first call for exploring available 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?

Explicitly states when to use: 'when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools'. No explicit when-not-to-use but strong positive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavioral detail: returns specific fields (cik, company_name, recent_filings with URIs, fundamentals sorted), notes the patents API sunset in May 2025 with soft-fail behavior, and explains the news fallback chain (GDELT→GNews). 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 dense paragraph. It front-loads typical user queries and then lists outputs and constraints. While efficient and informative, it could be more structured (e.g., bullet points) for quick scanning. No wasted words, but slightly dense.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is highly complete. It covers all major return components (filings, fundamentals, patents, news, LEI) and edge cases (patents sunset, name unsupported). It provides sufficient context for an AI agent to understand the tool's capabilities and limitations.

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 beyond the schema by clarifying that 'value' accepts ticker or zero-padded CIK, and that names are not supported (pointing to resolve_entity). It reinforces that 'type' is limited to 'company.' This adds meaningful context, so a score above baseline (3) is warranted.

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's purpose: producing a cross-source profile of a US public company. It lists specific data domains (filings, fundamentals, patents, news, LEI) and provides example queries. It also distinguishes this tool from sibling tools by stating it should be preferred over chaining individual lookups for holistic views.

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

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

The description explicitly tells when to use this tool (holistic company profile) and when not to (if only a name, use resolve_entity first). It also contrasts with alternatives like 'chaining single-pack SEC/XBRL/news lookups,' providing clear usage 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?

The description confirms the destructive nature (delete) which matches annotations. Adds context about clearing sensitive data and old context, but annotations already provide destructiveHint=true and idempotentHint=true. No contradictions.

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

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

Two efficient sentences with no fluff. The primary verb and resource are front-loaded. 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?

For a single-parameter, no-output-schema tool with clear annotations, the description is complete. It covers the action, when to use, and related tools.

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

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

Schema covers 100% of parameters with a clear description for 'key'. The tool description adds no additional detail 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?

Clearly states the action ('delete a previously stored memory') and resource ('memory by key'). Distinguishes itself from siblings by referencing 'remember' and 'recall' as paired 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?

Explicitly lists scenarios for use: stale context, task complete, clearing sensitive data. Also implies when not to use by mentioning the pair 'remember and recall' for storage/retrieval.

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 specific steps: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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 front-loaded with the primary action and is concise. Every sentence adds value, though it could be slightly more structured (e.g., bullet points).

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

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

For a tool with no output schema, the description adequately explains the output format ('single text blob ready to drop at site-root/llms.txt'). Combined with annotations and sibling context, it provides sufficient completeness for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides a concrete example for the 'url' parameter but adds no additional meaning for 'max_links' beyond what the schema offers.

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

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

The description clearly states the verb 'Generate' and the resource 'production-ready llms.txt file for any URL'. It specifies the output format and distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating the file itself.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It provides clear context but does not include when not to use or alternatives.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, etc. The description adds context: returns specific fields, scoped to caller's subscriptions, and ability to include inactive ones. No mention of pagination or limits, but sufficient for a list tool.

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, no wasted words. Every sentence provides essential 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 simple parameter and rich annotations, the description is complete enough. It lists return fields despite no output schema. Lacks only potential details like pagination.

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 parameter description. The description does not add extra semantic meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'subscriptions', and specifies the return fields. It distinguishes from sibling tools like subscribe and unsubscribe, though not explicitly contrasted.

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 use cases: review before adding more subscriptions or find an id to cancel. It gives clear context for when to use the tool, though it doesn't mention when not to use it.

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

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

Annotations are all false, providing minimal safety info. The description compensates by disclosing rate limits (5/day), that it's free and doesn't count towards quota, and that the team reads digests daily. This adds valuable behavioral context beyond annotations.

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

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

The description is moderately long but well-structured, with each sentence serving a purpose: describing use cases, formatting tips, and constraints. It could be slightly more concise, but the information density is high enough to justify the length.

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

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

Given the tool's simplicity and lack of output schema, the description fully covers what the tool does, when to use it, how to structure the message, and important constraints (rate limit, quota). No critical information is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, but the description enhances understanding by explaining type enum values and stressing not to paste end-user prompts. It also clarifies the purpose of the context object, adding semantic value beyond the schema's brief 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 sends feedback about bugs, features, data gaps, or praise to the Pipeworx team. It uses specific verbs ('Tell') and identifies the resource ('Pipeworx team'), distinguishing it from sibling tools that perform different functions.

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 when to use this tool: for wrong data (bug), missing tools (feature/data_gap), or positive experiences (praise). It also advises against pasting end-user prompts and mentions rate limits. However, it does not explicitly state when not to use it or compare to alternatives in the 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral details: self-aggregating, no PII, derivation method, and caching duration. No contradiction with annotations.

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

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

The description is well-structured: a concise first sentence captures the essence, followed by a clear returns list, three bulleted use cases, and technical details. Every sentence adds value, no fluff.

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

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

Given no output schema, the description adequately explains return values (top tools, packs, volume) and data structure (pack, tool, count). Caching behavior is also noted, making the tool fully understandable for a read-only query.

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. The description enhances meaning by explaining window behavior (shorter vs longer windows) and linking it to use cases, adding value beyond the schema description.

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

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

The description clearly states the tool returns trending tools/packs/call volumes over a time window, using specific verbs like 'returns' and 'discovering'. It distinctly differentiates from sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on aggregated trend data rather than querying or searching.

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 concrete use cases (discovering hot data sources, confirming canonical choice, checking alignment). While it doesn't name alternative tools for when not to use it, the context effectively implies its appropriate scope.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details internal logic (Jaccard similarity anchor, partition filter, fill check against live CLOB depth), data sources, and trade advisories. 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?

Well-structured with front-loaded requirement and mode separation. Each sentence serves a purpose—no fluff. While lengthy, the complexity of the tool justifies the length, and it remains easy to digest.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array, partition_check, fill check). Covers algorithm, parameters, limitations, and links to sibling tool. Complete for an arbitrage detection 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 already provides parameter descriptions (100% coverage), but the description adds substantial value: explains the difference between modes, gives concrete examples of valid inputs (slugs, URLs, seed questions), and clarifies mutual exclusivity.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique fill checks and alternative usage.

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 on when to use each parameter: event for a specific market, topic for cross-event scanning. Warns that calling with no args fails. Provides examples and references sibling tool for custom sizing, offering clear when-not-to-use advice.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc., and the description adds extensive behavioral context beyond annotations: caching (KV-level 1h), model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculations, diagnostics for empty segments, and 24h market move warnings. 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 lengthy but every sentence adds value—model details, edge metrics, knobs, diagnostics. It is front-loaded with core purpose. Some structure (e.g., bullet points) could improve readability, but content density is appropriate 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 the complexity (9 parameters, no output schema, nested return structure with segments and diagnostics), the description thoroughly covers return format, edge metrics, filter knobs, caching, and data sources. It compensates for the lack of output schema by describing the response structure in detail.

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 meaning for several parameters (e.g., min_partition_leg_kelly explains parent-level Kelly, slippage_pp discusses Polymarket fees). This enriches understanding beyond schema descriptions.

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

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

The description clearly states the verb 'scan' and 'return opportunities' with the resource 'Polymarket markets', and it specifies the unique value: 'where Pipeworx data disagrees with market price'. It explicitly mentions the use case 'what should I bet on today'.

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 context for use ('agents discover opportunities without paging hundreds of markets') and the intended purpose. However, it does not explicitly mention when not to use this tool or provide comparisons to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity.

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

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

Annotations already indicate non-destructive, idempotent read-only behavior. The description adds rich behavioral context: response structure (tracked, expired, snapshot_dates), computation methods (trend, decay_pp_per_day), and limitations (history depth, intraday not available). 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 purpose first, then response details, then limits. While thorough, some sentences could be shortened without losing meaning. Still efficient for the information provided.

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

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

Despite no output schema, the description fully describes the return structure, fields, and caveats. It covers edge cases (expired opportunities, missing snapshot dates) and provides actionable insight (median lifespan as competition clock). 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%, so parameters are documented. The description adds value by explaining how 'days' and 'window' affect the analysis (e.g., window selects snapshot family, days sets lookback). It reinforces defaults and boundaries.

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: providing edge persistence and decay telemetry. It distinguishes from its sibling 'polymarket_edges' by focusing on time-series analysis and trend detection, not just snapshot 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?

Explicitly explains when to use (e.g., differentiating between fresh and old edges) and includes limits (60-day TTL, daily closes). Could be improved by naming alternatives directly, but guidance 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and for baskets warns about thin_legs and forced_directional_risk. It does not contradict annotations and provides useful behavioral disclosure beyond the structured metadata.

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

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

The description is fairly long but well-structured: opening sentence defines purpose, then specifications for each mode, then usage guidance. Every sentence adds value, though the final paragraph could be slightly tightened. It is front-loaded with essential info and organized logically.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It details all return fields for both single-market and basket modes, explains edge cases (thin legs, partial fills, forced directional risk), and provides usage thresholds. This fully equips an agent to invoke the tool correctly.

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

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

Schema coverage is 100% for 4 parameters. The description adds extra meaning: it explains the interpretation of `size_usd` in both modes (max spend vs target proceeds, settlement notional), the auto-detection of `side` in basket mode, and the requirement for either `market` or `event` but not both. 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 defines the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explains what each returns, effectively differentiating it from sibling tools like polymarket_arbitrage and polymarket_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 explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills create directional risk), providing clear guidance on when not to use it and what happens if skipped.

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, openWorldHint, and non-destructive. The description goes far beyond by detailing compatibility warnings (e.g., bet shape non-equivalence, temporal misalignment), skipped cross types, and the meaning of 'matched_pairs:0'—all crucial for understanding tool behavior. 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 front-loaded with the core purpose and modes. It is structured with logical sections (modes, response format, safety fields). While detailed and slightly lengthy, every sentence contributes necessary information. Could be slightly more streamlined 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?

Given no output schema, the description fully explains the response structure (leg-by-leg prices, top spreads in percentage points) and all safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers parameter combinations, limitations, and what results mean, making the tool completely understandable.

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 decent descriptions. The description adds significant value: lists all 10 macro shortcuts for 'topic', explains interaction between parameters (topic vs explicit overrides), and provides concrete examples. This exceeds the baseline 3 for full schema coverage.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying the verb 'spread between' and resources (Kalshi and Polymarket). It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison. Two modes (topic shortcuts and explicit pairings) add specificity.

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 two usage modes (topic shortcuts for common macro events, explicit ticker/slug for custom pairs) and warns that most pre-mapped topics currently return compatibility warnings, implying limitations. It does not explicitly mention when not to use this tool or directly reference alternative sibling tools, 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 already declare readOnlyHint and idempotentHint. Description adds scope details (anonymous IP, BYO key hash, or account ID), enhancing transparency 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?

Three clear, front-loaded sentences. Each sentence adds essential information: function, use cases, scope/pairing. No redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains behavior, including the listing behavior and scoping. 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?

The schema covers the 'key' parameter with a description. The tool description adds the crucial detail that omitting it lists all keys, adding value beyond the schema.

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

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

The description clearly states it retrieves a value saved via 'remember' or lists all keys when omitted. It differentiates from sibling tools 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 states when to use: look up context stored earlier. Also advises pairing with 'remember' and 'forget' and mentions scope 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the response content (source, citation_uri, raw payload), the effect of mark_read, and that polling is acceptable. 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?

Every sentence adds value. The description is front-loaded with purpose, then details filtering, mark_read behavior, polling, and alternative access. 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?

Despite no output schema, the description explains the response fields. It covers all parameters and typical use cases. Agent can confidently use this tool without ambiguity.

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 goes further by explaining how parameters are used in practice: e.g., filter by type with example 'sec_8k', ISO timestamp for since, and mark_read for read tracking.

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 returned fields and filtering options. It distinguishes itself from sibling tools by focusing on alerts/feed 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?

Provides guidance on filtering by type and since, and explains mark_read behavior. Mentions polling works and notes an alternative HTTP endpoint, but does not explicitly compare to sibling tools or state when not 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it fans out to multiple sources, has a fallback from GDELT to GNews on rate limits/5xx, and notes that USPTO soft-fails due to API sunset. It also describes the return structure (grouped changes, total_changes count, citation URIs). Minor omission: no mention of potential rate limits on the tool itself.

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 efficiently conveys purpose, usage, sources, fallbacks, and output structure. Every sentence adds value, but it could be broken into shorter sentences or bullet points for easier scanning. Still, it's well-structured and front-loaded with key example queries.

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

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

Given the tool's complexity (multiple data sources, fallback logic, output structure) and the absence of an output schema, the description provides a good overview of inputs, behavior, and output. It explains the return format (grouped changes, total_changes, URIs) but does not detail error handling or empty results. Overall sufficiently complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by elaborating on the since parameter (ISO date or relative shorthand with examples and recommended values) and clarifying that value accepts ticker or CIK. This goes beyond the schema's basic 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 what the tool does: provides a change feed for a company over a window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It gives example queries ('what's new with X', 'latest on Y') and explicitly distinguishes itself from sibling tool entity_profile by specifying when to use each.

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

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

The description provides explicit guidance on when to use this tool (for recent changes over a window) and when to use entity_profile instead (for static profile regardless of window). It also explains the since parameter format with examples and typical monitoring values, and describes the fallback behavior for news sources.

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 behavioral context beyond annotations: scoped by identifier, persistence details (authenticated = persistent, anonymous = 24 hours). This complements the idempotentHint=true annotation 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?

Single paragraph with clear flow: purpose, when to use, behavior, persistence, pairing. Every sentence adds unique value. No wordiness.

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 key-value tool with no output schema, description fully covers purpose, usage, persistence, scope, and related tools (recall, forget). 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 100% of parameters with descriptions. The description adds value with naming conventions (e.g., 'subject_property', 'target_ticker') which aids agent in forming good keys, moving beyond schema 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 specific verb 'Save data' and identifies resource 'data the agent will need to reuse later'. It clearly distinguishes the tool from siblings by mentioning 'recall' and 'forget' and providing concrete examples like 'resolved ticker', 'target address', 'user preference'.

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

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

Explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' Context about persistence for authenticated vs anonymous sessions is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that the tool cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This is useful behavioral context beyond annotations.

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

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

The description is front-loaded with common query examples and a clear directive. Every sentence adds value, with no redundancy. It efficiently covers purpose, usage, and outputs in a compact paragraph.

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 entity types, multiple return fields) and lack of output schema, the description comprehensively covers what each call returns, including citation URIs. It also notes internal cascading behavior, making the tool's full context clear.

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 3. The description adds meaning by explaining the 'type' enum and 'value' parameter with examples (e.g., tickers, CIKs, drug names) and detailing what each type returns (ticker+CIK for company, RxCUI for drug). This 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 explicitly states the tool resolves user-spoken names to canonical identifiers for 'company' and 'drug' types. It clearly distinguishes from siblings like 'compare_entities' and 'entity_profile' by focusing on ID lookup. The verb 'resolve' and resource 'entity' are specific.

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

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

The description provides a clear when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also lists supported types and their outputs. However, it does not explicitly mention when not to use or name alternatives, though the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. Description adds that it returns nearest place name but doesn't detail other behaviors like result limits, language support, or radius effects. Adequate but not rich.

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, front-loaded with key information. No extraneous content; every word is relevant.

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

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

Simple operation with output schema likely covering return values. However, optional parameters and their effects are unexplained, making the description minimally complete for the given 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 low (17% with only radius described). Description does not explain any parameters beyond the implied lat/lon. No guidance on lang, layer, limit, or radius semantics. Fails to compensate for schema gaps.

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

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

Description clearly states it is a reverse geocode operation converting coordinates to nearest place name. Specific verb-resource pairing distinguishes it from sibling tools, many of which are unrelated to geocoding.

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?

Implied usage: use when you have coordinates and need a place name. No explicit guidance on when not to use or alternatives. With many sibling tools, exclusion criteria would improve clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral details: it 'Probes each entity', returns a 'ranked list with score, confidence, signal density per entity', and implies no side effects. This goes beyond annotations but could elaborate on rate limits or error handling.

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 (three sentences) and front-loaded with the core purpose. Every sentence adds 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 complexity (4 parameters, no output schema), the description is fairly complete. It explains the process, input semantics, and output format. Minor gaps: no mention of error handling or rate limits, but acceptable for this level of detail.

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 significant value: it explains that the first entity in 'entities' is treated as the 'subject' for narrative, and clarifies the roles of 'models', '_apiKey', and 'context'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the process (probing each entity with ai_visibility_check, ranking by score) and differentiates from the sibling ai_visibility_check by focusing on comparison across multiple 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 provides usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies that this tool is for comparing multiple entities rather than checking a single one, but does not explicitly state when not to use it or mention 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context: fans out across services, degrades gracefully on partial failures, and bundlephobia can take 5-30s on first measurement. 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 detailed but each sentence adds value. Front-loaded with core purpose. Could be slightly shorter but remains clear and well-organized.

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

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

Given no output schema, the description thoroughly explains return format (summary block, per-advisory, links, alternative versions) and key fields (is_latest, license, advisory_count, etc.). Fully prepares the agent for what to expect.

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 parameters documented). Description adds meaning beyond schema: explains default version behavior (latest when omitted) and format for scoped packages, providing practical usage guidance.

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

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

The description clearly states it's a composite check for evaluating an npm package, covering license, advisories, version history, and bundle size. It specifies the ecosystem (NPM) and distinguishes from siblings by mentioning alternative tools for other ecosystems.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Provides clear exclusions: NPM only; for others, use deps.dev:version. Also mentions partial failures and timing quirks.

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=false. The description adds behavioral insight about being 'strong on partial/autocomplete-style queries', which complements the annotations. 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 short sentences front-load the primary purpose and key strength. Every word is informative, with no filler.

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

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

With 100% schema coverage, annotations, and an output schema, the description is adequate. It conveys the core function and a notable use case. Could briefly mention typical usage with parameters like lat/lon bias, but schema already handles that.

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 coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, 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's purpose: 'Forward geocode — place name → coordinates' and highlights a key strength ('strong on partial / autocomplete-style queries'). This distinguishes it from sibling tools like 'reverse' (reverse geocode).

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

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

The description implies the tool is good for autocomplete queries but does not explicitly state when to use it versus alternatives (e.g., 'reverse' or 'resolve_entity'). No when-not-to-use guidance is given.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K chars with truncation), and output features (character offsets, similarity scores). 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 concise yet comprehensive. It front-loads the key action ('Semantic search INSIDE a fetched record') and uses bold for emphasis. Each sentence adds unique information, and the structure is logical: purpose, usage context, pairing, technical details, caps.

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 clearly states what is returned: 'top-N passages with character offsets and similarity scores.' It also covers edge cases like truncation. For a tool of moderate complexity, this is complete and sufficient for an agent to understand the return format.

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 specifying the default for 'limit' (5) and providing example queries for 'query'. It also clarifies the max character length for 'text'. This exceeds the baseline.

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

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

The description clearly defines the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search', the resource 'text inside a record', and the context of use. This distinguishes it from siblings like 'search' (external search) and 'ask_pipeworx_grounded' (grounded Q&A).

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: 'Use when the record is too big to cram into the prompt.' It also explains the pairing with ask_pipeworx_grounded. However, it does not explicitly list alternative tools for different scenarios, so it misses a perfect score.

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 context about account requirements, phone verification, SMS caps, and webhook signing beyond annotations. Annotations indicate idempotentHint=true, but the description does not clarify idempotency behavior (e.g., whether repeated calls create duplicates). No contradiction with annotations.

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

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

The description is dense but well-organized, front-loading the purpose and return value, then progressing to context and details. Could benefit from bullet points or clearer section breaks for readability.

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

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

Covers core aspects: types with parameters, delivery channels with constraints, and account requirements. Lacks information on error handling, rate limits (except SMS cap), and idempotency behavior, but overall sufficient 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%, and the description adds detailed explanations for each subscription type and the delivery object, including constraints and examples that go beyond the schema descriptions.

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

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

The description clearly states the verb 'Create' and resource 'subscription', and lists specific subscription types, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous+BYO cannot persist subscriptions. It provides concrete examples for each type, but does not explicitly mention alternatives or exclusions beyond the OAuth requirement.

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 that it returns dynamic examples from a live catalog, and that it can be called with or without a topic. 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 a bit long but well-structured, front-loaded with example question phrases, then explains functionality. Every sentence adds value, though could be slightly more concise.

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

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

For a simple tool with 1 optional parameter and good annotations, the description covers purpose, usage, parameter semantics, and return type (example questions). No output schema needed as return is well described.

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 3. Description adds meaning: explains topic as optional focus area with listed values, and that omitting gives cross-category spread, beyond what the schema's brief description 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 is for onboarding, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by being about suggestions, not answers.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear guidance on when to use vs 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?

Description discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This goes beyond annotations (destructiveHint: false) by explaining the exact behavioral consequence.

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, each adding essential information: first states the action and resource, second provides ownership and behavioral details. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and behavioral effect (deactivation vs deletion). It is fully complete.

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

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

The single parameter 'id' is fully described in the schema with type and description. The description adds no new information about the parameter, only referencing 'id' without elaboration. Baseline score of 3 is appropriate given 100% schema coverage.

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

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

Description starts with 'Cancel a subscription by id', which is a clear verb+resource pair. It explicitly distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancellation action.

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 ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear when-to-use and when-not-to-use guidance, though it could mention alternatives for unsubscribing others if 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds context: uses SEC EDGAR + XBRL, returns multiple fields with delta, and replaces multiple sequential calls. 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 well-structured and front-loaded with trigger phrases. Each sentence adds value: usage trigger, scope, technical detail, efficiency. 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 there is no output schema and one parameter, the description covers the return format, source, and efficiency. It lacks explicit error handling or limitations for unsupported claim types, but is otherwise complete.

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

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

The only parameter 'claim' is described in the schema with a basic description. The tool description greatly expands on this with natural language examples, explanation of how the claim is processed, and what types of claims are supported.

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 natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims) and the output (verdict, structured form, citation), distinguishing it from sibling tools like search or deep_research.

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

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

The description explicitly says to use whenever checking factual correctness. It hints at scope limitations by mentioning 'v1 supports company-financial claims', but does not explicitly list alternatives for other claim types or state 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.