Materials

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds beyond: explains cost implications (free vs. BYO key), that Anthropic calls are direct pass-through, and return structure (score, confidence, signals, raw_response). 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?

Single paragraph with clear front-loading of main action, then details, then use cases. Every sentence adds value; could be slightly more structured with bullets but compact and informative.

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

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

Despite no output schema, description explains return shape (per-model object with score, confidence, signals, raw_response + combined view). All 4 parameters are covered in schema and description. Sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions for all 4 params. Description adds context beyond schema: default model, when _apiKey is needed, return format per model. Baseline 3, plus extra context merits 4.

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

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

Description uses specific verb 'probe' and resource 'LLMs', clearly states scoring visibility 0-100 per model. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general visibility rather than just competitors.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and key requirement for Anthropic. Could mention alternatives like 'scan_competitor_ai_presence' but still 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds value by describing routing behavior, citation URIs, and that it works on every tier.

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 key directive 'PREFER OVER WEB SEARCH' and usage guidelines, but it is somewhat wordy with many examples and details that could be streamlined.

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 (many sibling tools, no output schema, rich annotations), the description covers purpose, when to use, examples, and behavioral details sufficiently for agent selection.

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 documentation coverage is 100% with clear aliases. Description adds example questions but does not significantly extend parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool is for factual questions about real-world data, with specific domains listed (SEC filings, FDA, etc.) and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly tells when to prefer this tool over web search and when to step up to grounded or deep_research. Provides concrete examples of queries and guidance on default usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: costs one extra LLM call, returns structured output with refusal reasons (e.g., not_in_source, no_tool_match). No contradiction.

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

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

Description is dense but well-organized, front-loading purpose and key behavior. Every sentence adds value, though length could be marginally trimmed 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?

Given the tool's complexity (routing among 4552 tools across 1160 sources) and no output schema, the description fully explains the return format, refusal reasons, and trade-offs (extra LLM call). No gaps for an agent to understand usage.

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

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

Schema coverage is 100%, so parameters are already documented. Description does not add significant semantic details beyond stating it accepts natural language questions. 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from sibling 'ask_pipeworx' by emphasizing groundedness and extraction-only behavior.

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 advises use when answers will be quoted, cited, or acted on, and the agent must not invent facts (e.g., financial verdicts, legal claims). Also states preference for 'ask_pipeworx' for casual lookups, providing clear when-to-use and when-not-to.

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 many behaviors beyond annotations: market resolution, classifier, fan-out examples, response shapes, error handling (low-confidence, closed markets, wide spreads, cancellation rules), safety mechanisms, and network fallbacks. 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 extensive but well-structured with clear sections. Every sentence provides useful information. While not concise, its organization compensates for 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?

The description covers all critical aspects: purpose, inputs, classifiers, fan-out logic, response shapes, error states, safety, and cancellation risk. Despite no output schema, it thoroughly explains 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%, but description adds significant value: explains depth parameter (quick vs thorough), market parameter formats, and include_raw with size estimates and use cases. This goes beyond the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant data, with specific use cases like 'should I bet on X'. It distinguishes from siblings like polymarket_edges by offering comprehensive research with fan-out and evidence packets.

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 when to use ('should I bet', 'what does data say'), but does not explicitly state when not to use or alternatives. However, the context is very clear for an AI agent.

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

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

Adds significant context beyond annotations: explains data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

Dense but efficient; front-loads trigger phrases, then explains each type concisely with 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?

Covers all essential aspects: data sources, handling of fiscal years, sorting, citations, and performance benefit. Adequate despite missing output schema.

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

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

Adds meaning beyond schema: explains what each entity type pulls (revenue, net income for company; adverse-event counts for drug) and gives example formats for values.

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

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

The description clearly states it performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific trigger phrases and distinction 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 lookups and provides trigger phrases, but doesn't mention when not to use or alternatives like entity_profile for single entities.

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

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

Descripton goes beyond annotations by detailing the research process (decomposes into facets, parallel tools), output format (findings packet with evidence, confidence, source, citations, gaps[]), and response time (15-60s). No contradiction with annotations.

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

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

The description is long but well-organized with clear sections. Each sentence adds value, though minor redundancy (e.g., mention of ask_pipeworx twice) could be trimmed. Still highly efficient for the complexity.

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

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

Given 2 params with 100% schema coverage, no output schema but detailed return format in description, and full behavioral context, the description is complete. It covers purpose, usage, behavior, parameters, and results with 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 coverage is 100%, and the description adds context for both parameters: explains depth values (quick=3, standard=5, thorough=8 facets) and that questions can be broad/multi-part. Fully compensates.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and distinguishes it from siblings like ask_pipeworx (single lookup) and other tools, ensuring the agent understands its unique purpose.

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

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

Provides explicit guidance on when to use (broad/multi-part questions over structured data) and when not to (breaking/current news, prefer ask_pipeworx). Also notes account requirements and that ask_pipeworx is an alternative for unsigned users.

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, idempotentHint=true. The description adds value by explaining the output: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies the tool's behavior and output format beyond what annotations provide.

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

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

The description is concise with five sentences, each serving a distinct purpose: purpose, usage context, domain list, return format, and strategic advice. No redundant or filler content. It is front-loaded with the core purpose.

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

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

Given the 6 parameters (though many aliases) and no output schema, the description fully explains what the tool returns: top-N tools with full schemas and examples, ready to call. It also covers the required single parameter and optional limit. The description is self-contained and provides enough context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with each parameter described. The description does not add new meaning to parameters beyond restating that 'query' is a natural language description. It provides example queries but no new parameter semantics. 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 explicitly states 'Find tools by describing the data or task' and gives concrete examples like 'look up FDA drug approvals'. It clearly distinguishes this tool from its siblings (specific tools for specific tasks) by positioning it as a discovery mechanism to browse available options.

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

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

The description says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use this tool versus directly invoking specific tools.

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

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

Description details what the tool returns (CIK, filings, fundamentals, patents, news, LEI), notes that patents soft-fail until reactivated, and confirms name inputs are not supported. Annotations already provide readOnly/idempotent hints, and description adds context without contradiction.

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

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

Description is dense but well-structured: starts with example queries, then details sources and return fields. A bit long but every sentence is informative; the front-loading of examples is effective.

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

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

Covers all major aspects: data sources, return fields, limitations (patents soft-fail, name unsupported), and preference over alternatives. Missing explicit mention of response format or error handling, but adequate given annotations.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. The description adds extra value by explaining the type enum value 'company' and emphasizing that value must be ticker or CIK, not names, which goes beyond schema definitions.

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

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

The description clearly states it returns a comprehensive cross-source profile for US public companies, with multiple example queries. It distinguishes from sibling tools like resolve_entity and compare_entities by specifying it's the preferred tool for holistic company overviews.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name is provided, providing clear when-to-use and when-not-to-use guidance.

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

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

The description aligns with annotations (destructiveHint=true, readOnlyHint=false) and adds useful context about clearing sensitive data and pairing, though the permanence of deletion is implicit from destructiveHint.

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 that are front-loaded and efficient, with 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 fully covers purpose, usage, and pairing with siblings.

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

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

With 100% schema coverage, the description does not add extra meaning beyond the schema's 'Memory key to delete' for the single parameter 'key'.

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

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

The description clearly states the action 'Delete a previously stored memory by key' and distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with siblings, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations and explains the internal process.

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

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

The description is 3-4 sentences, front-loaded with the core purpose. Every sentence adds value: purpose, process, and use cases. No redundant or filler text. Highly concise and well-structured.

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

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

Given the tool's low complexity (2 params, no output schema) and rich annotations, the description is complete. It explains the input parameters (URL and max_links), the process (fetch, extract, emit), and the output format (single text blob ready to drop at site-root/llms.txt). No gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions 'extracts title/description/key links' and 'emits the standard llms.txt markdown format', but these are general behaviors, not parameter-specific enhancements. Thus 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: 'Generate a production-ready llms.txt file for any URL'. It specifies the resource (llms.txt file) and action (generate), and distinguishes from siblings like scan_competitor_ai_presence by focusing on generating the file rather than scanning.

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 context on when to use the tool, though it does not mention when not to use it or name alternatives among siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about returned fields and the optional parameter include_inactive, complementing the annotations without contradiction.

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

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

The description is two concise sentences that efficiently convey purpose, return data, and usage guidance without any filler.

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

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

For a simple listing tool with one optional parameter, the description covers purpose, return fields, usage guidance, and safety (via annotations). No gaps are apparent.

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

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

Schema coverage is 100% for the single parameter include_inactive. The description does not elaborate on the parameter's meaning beyond what the schema provides, so it stays at baseline.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the return fields, making its purpose unambiguous and distinguishable from sibling tools like subscribe and unsubscribe.

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

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

The description explains when to use the tool ('review what you're monitoring before adding more or to find an id to cancel'), providing practical guidance on use cases.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds context about the large scale (millions of entries) and return fields (id, formula, elements, site count, link), going beyond annotations.

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

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

Well-structured with purpose first, then usage guidelines, then parameters. Although a bit long, every sentence provides distinct value. Could be slightly tighter 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?

Despite no output schema, the description fully explains the return structure. Coverage of parameter usage and search behavior is thorough, making the tool easy to use correctly.

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

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

With 100% schema coverage, the description adds meaning by explaining how filter parameters work (e.g., 'elements' requires all elements, 'formula' is normalized). Provides operational context not present in 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 searches computed (DFT) crystal structures across specific OPTIMADE databases, and distinguishes itself by mentioning alternatives for experimental and stability data.

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

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

Provides explicit guidance on when to prefer this tool over web search, and when to use other tools (crystallography pack for experimental structures, materials_stability for stability data).

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral context by detailing the return fields (composition, formation energy, hull stability, band gap, etc.) and explaining the 'stable_only' option. 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 (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage preference, parameter explanation, and return values. No redundant information.

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

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

Despite having no output schema, the description fully explains the return structure (composition, formation energy, hull stability, band gap, space group, prototype). It covers all parameters and their effects. The tool is well-documented for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how to specify the element system (e.g., 'Fe, O') and the optional restriction to stable phases. It also clarifies the meaning of hull stability (≤0 = stable).

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

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

The description uses specific verbs ('compute') and resources ('thermodynamic stability and formation energy'), and provides example queries like 'is compound stable'. It clearly distinguishes itself from web search and sibling tools like materials_search by stating its preference for stability queries.

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 (prefer over web search for stability/formation energy queries) and gives example input patterns. It lacks explicit guidance on when not to use it or alternatives among siblings, aside from the web search comparison.

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

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

Beyond annotations, the description reveals that the tool is rate-limited (5 per identifier per day), free, and doesn't count against quota. It also explains that feedback is read daily and influences the roadmap. No annotation 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 concise, front-loaded with the core purpose, followed by usage guidelines and behavioral notes. Every sentence serves a purpose, 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?

The description covers all necessary aspects: when to use, what to provide, limitations (rate limits, no quota), and outcome (team reads daily, influences roadmap). It is complete for a simple feedback tool with no output schema.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra guidance: avoid pasting end-user prompts and describe issues in terms of Pipeworx tools/packs. It also elaborates on the meaning of each type, providing additional context beyond the enum 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: sending feedback to Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs ('Tell') and resources ('Pipeworx team'), and distinguishes it from sibling tools (e.g., research or discovery tools) by its feedback role.

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

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

The description explicitly specifies when to use the tool (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). It provides clear context for appropriate use, though it does not mention alternative tools for non-feedback tasks.

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 (readOnlyHint, idempotentHint) are supported by 'self-aggregating signal', 'derived from CF analytics-engine', 'no PII', 'cached 5min-1h'. 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?

Three concise paragraphs: result summary, use cases, technical notes. Front-loaded with key output. 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 (1 optional param, no output schema), description covers purpose, use cases, data provenance, caching, param guidance. Return format implied in text.

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

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

Schema already covers window param with enum and description. Description adds value: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' Enhances beyond schema.

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

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

Description clearly states it returns top tools, packs, and call volume over windows (24h/7d/30d). Uses specific verbs and resources, and differentiates from siblings by focusing on aggregate trending data.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, checking alignment). No exclusion criteria needed given tool's simple nature.

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?

Details behavioral traits beyond annotations: semantic anchor with Jaccard threshold, partition filter for placeholders, fill check against CLOB depth, and response structure. No contradictions with annotations (readOnly, idempotent, non-destructive).

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 section headers and front-loaded purpose, but slightly verbose. Every sentence adds value, though could be tightened without losing clarity.

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 covers response fields, all operational modes, and references related tools. It provides enough detail for an AI to use the tool correctly without additional context.

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

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

Schema coverage is 100% with descriptions for both parameters, but the tool description adds significant context: event param explains slug usage and checks performed; topic param explains cross-event scanning and patterns it catches. The no-argument mode is also explained.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges or polymarket_fill_risk by focusing specifically on arbitrage detection.

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 three usage modes: no args for trending scan, event for single-event partition check, and topic for cross-event scan. Also provides when-not-to-use guidance (e.g., 'do not trade it' when realizable edge ≤0) and references alternative tool for custom sizing.

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 provides extensive behavioral details beyond the annotations: it explains the three response segments, edge calculation (including slippage, Kelly, market move warning), cache duration (1h), and diagnostic output for empty segments. 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 very detailed but well-structured: starts with purpose, then segments, then edge details, then knobs, then response structure. It is slightly verbose with technical specifics but remains actionable and front-loaded.

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 documents the response top-level (by_segment, fed_candidates, _diagnostics) and the fields within each opportunity (edge_pp_net, kelly_fraction, liquidity, etc.). It is complete enough for an agent to understand the tool's behavior and outputs without external information.

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

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

With 100% schema coverage, every parameter already has a description. The tool description adds significant value by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly act as 'tradeable-edge knobs' and clarifying why min_kelly does not filter partition arbs.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically identifying three model families. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on a unified edge scan.

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

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

The description says it's built for 'what should I bet on today' and notes Fed bets are surfaced but excluded from ranking. However, it does not explicitly state when not to use this tool or compare to alternatives like polymarket_arbitrage or polymarket_kalshi_spread, leaving the selection guidance implicit.

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

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

Annotations indicate read-only, idempotent, not destructive. Description adds behavioral details: snapshots written on cache-miss causing data gaps, decay computed from daily closes with default slippage, and the meaning of negative edge_pp_net. 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?

Description is detailed but efficient, front-loaded with core purpose and structured by output arrays. Each sentence adds value, though the length could be slightly trimmed without losing meaning.

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

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

No output schema, so description fully explains return values: tracked elements with time-series and trend indicators, expired items with lifespan, and snapshot dates with gaps explained. Limits and definitions are covered. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds minor context: 'snapshot family' for window and clamp range for days, but largely repeats schema info. Baseline 3 is appropriate as description adds modest value beyond schema.

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

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

Description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis rather than single snapshots. The output structure (tracked, expired, snapshot_dates) is explicitly defined.

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

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

Description provides clear context on when to use: to differentiate between fresh and old edges, implying this is for assessing trade viability over time. It mentions limits (60-day TTL, decay from daily closes not intraday, gaps from cache-misses). However, it doesn't explicitly state when not to use or suggest alternative tools.

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

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

Annotations indicate readOnly, openWorld, and idempotent hints, with no destructiveness. The description adds detailed behavioral information: walking the ladder, returning specific fields like slippage_pp, shares_filled, and a verdict, and explaining basket mode behavior including forced directional risk and thin_legs. No contradictions with annotations; description enriches understanding beyond structured data.

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

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

The description is information-dense and front-loaded with the main purpose. It organizes content by mode (single-market vs. basket) and uses all-caps for key warnings. However, it is somewhat lengthy; minor trimming could improve conciseness without losing clarity. Still, every sentence earns its place given the tool's complexity.

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

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

Despite no output schema, the description fully lists return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains their meaning. It covers both modes, gives usage boundaries (size clamp 10–1,000,000), and warns about critical risks (partial basket fills, forced directional risk). The description is sufficiently complete for agent decision-making.

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

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

Schema coverage is 100%, providing baseline. The description adds value by explaining default values (size_usd default 1000, side default for basket as auto), interpretation differences between modes (max spend vs. target proceeds), and the auto-detection logic for basket side based on partition sum. This context meaningfully supplements 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 starts with a clear action: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two operation modes (single-market and basket) and distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges. The purpose is unambiguous and well-defined.

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

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

The description explicitly advises when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale, such as theoretical overround being uncapturable on thin books and the risk of partial basket fills converting arb into directional positions. This provides excellent contextual guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses behavioral traits like the two modes, the response structure with leg-by-leg prices and top spreads, and safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It also warns that most pre-mapped topics currently return compatibility warnings. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections: purpose, two modes, response, safety fields. It is front-loaded with the main purpose. However, some parts are verbose (e.g., detailed explanation of safety fields could be more concise). It earns its place but could be tighter.

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 (3 parameters, no output schema, many siblings), the description is very complete. It explains the response structure implicitly, covers edge cases (incompatible bet shapes, temporal misalignment), and provides enough for an agent to use correctly. The absence of an output schema is compensated by the detailed textual description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the two modes (topic vs. explicit) and how the parameters interact (topic auto-fetches, explicit overrides). It also lists the 10 pre-mapped shortcuts. While it doesn't add new parameter details, it provides critical usage context.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb ('cross-venue spread') and resource, and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit when-to-use (comparing same question across venues), two modes (topic shortcuts and explicit tickers), and detailed safety fields that warn when spreads are not meaningful, such as compatibility_warning for non-equivalent bet shapes or temporal misalignment. It does not explicitly contrast with alternatives but 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 indicate readOnly, idempotent, and non-destructive. The description adds context about scoping to identifiers (IP, key hash, account ID), which is beyond the annotations. No contradiction.

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

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

The description is concise (three sentences) with no wasted words. It front-loads the primary action and then adds usage context, making it easy to parse.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers behavior, scoping, and relationship to sibling tools, leaving no 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?

With 100% schema coverage, baseline is 3. The description adds value by explaining the effect of omitting the key argument (list all keys) and providing examples, which enriches the schema's meaning.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs (retrieve, list) and resources (value, keys). It distinguishes from siblings (remember, forget) by explicitly mentioning them.

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

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

The description explains when to use the tool (to look up stored context) and pairs it with remember and forget. It does not explicitly state when not to use, but the guidance 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, signaling safe, idempotent reads. The description adds value by detailing the mark_read side effect ('Flag the returned events read so the next call only shows newer ones') and the general behavior of returning alerts with specific fields. 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 (4 sentences) and front-loaded with the core purpose. Each sentence serves a distinct role: defining the tool, describing return fields, explaining filtering, and noting polling and an alternative endpoint. No wasted words, and the structure makes it easy to scan.

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

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

Given the absence of an output schema, the description adequately covers what the tool returns (source, citation_uri, raw event payload) and how to use it (filtering, mark_read, polling). It also provides an alternative access method for external scripts. For a tool with 5 optional parameters, it addresses the main usage scenarios comprehensively.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter understanding by giving an example for type ('sec_8k'), specifying the format for since (ISO timestamp), and explaining the mark_read and unread_only behavior in context. This provides practical usage hints 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 the verb ('Pull fired events from your subscription feed') and the resource ('the most recent alerts'). It also specifies what each alert contains and offers filtering options (type, since). This distinguishes it from sibling tools like list_subscriptions or recall, which deal with subscriptions or general memory rather than event feeds.

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

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

The description provides clear context for when to use the tool (pulling alerts from the subscription feed) and mentions an alternative access method (GET endpoint for scripts/dashboards). It explains filtering and the mark_read flag to control future calls. However, it does not explicitly compare to other sibling tools or state when not to use it, which would strengthen the guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: fan-out to multiple sources, GDELT→GNews fallback on rate-limit/5xx, PatentsView API sunset soft-fail, `since` format details, and return structure (grouped changes, total count, citation URIs). No contradiction.

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

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

Description is slightly long but well-structured: starts with query patterns, then explains sources, fallback, and output. Every sentence adds useful information; no filler. Could be tightened but 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?

No output schema exists, but description fully specifies return shape ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). Covers all sources, fallback logic, and parameter constraints. Complete for complexity.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds value beyond schema by clarifying `since` relative shorthand examples ('7d', '30d', '3m', '1y') and stating that `value` accepts ticker or zero-padded CIK, though schema already mentions this. The added 'typical monitoring' note improves usability.

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 concrete query examples ('What's new with X', 'latest on Y') and explicitly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It lists specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling tool entity_profile.

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

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

Description provides explicit guidance: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also explains typical `since` values ('Use "30d" or "1m" for typical monitoring.') and gives example queries.

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

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

Annotations already idempotentHint=true and destructiveHint=false. Description adds key-value scope by identifier, persistence differences between authenticated and anonymous sessions (24h), which is valuable context beyond annotations. No contradiction.

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

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

Four concise sentences, each adding value. No fluff, logically structured from purpose to usage to retention behavior.

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 sibling tools and no output schema, the description fully covers what an agent needs: purpose, usage context, storage behavior, and lifecycle. 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 has 100% coverage with descriptions for both key and value. Description adds example patterns but no additional semantic depth beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, with specific examples of what to store (resolved ticker, address, preference). It distinguishes from sibling tools recall and forget by naming them.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. Also provides guidance on pairing with recall and forget for retrieval and deletion.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that each call cascades through multiple lookup endpoints, replacing 2-3 manual lookups. No contradictions.

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

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

Front-loaded with example queries and clear structure listing supported types. Some redundancy in listing return fields for both types, but overall efficient.

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

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

No output schema, but description thoroughly explains what is returned for each type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). Complete for the tool's purpose.

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

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

Schema has 100% coverage, but description enriches the 'value' parameter with specific examples and formats (e.g., ticker, CIK, name) and describes return fields per type.

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

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

Description clearly states the tool resolves a name to a canonical identifier, using specific verbs and examples. It distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicitly says to use this tool first when needing an ID from a name, but does not mention when to avoid it or use alternatives. Provides detailed supported types, which is strong 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. The description adds valuable behavioral context: how it works internally ('Probes each entity with ai_visibility_check, ranks by score'), and the special treatment of the first entity. 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?

Two efficient sentences: the first states the core action, the second provides context and output. No fluff, front-loaded with purpose.

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

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

Despite no output schema, the description explains what is returned: 'Returns ranked list with score, confidence, signal density per entity.' All 4 parameters are covered, and the tool's complexity is adequately addressed.

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% but the description adds extra semantics: notes that the first entity is treated as the subject for narrative, and explains the context parameter's purpose (disambiguating common names). This adds meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and distinguishes from sibling ai_visibility_check which likely probes a single entity.

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' and poses a concrete question. It implies when-not by contrasting with single-entity probing (ai_visibility_check sibling). However, it does not explicitly state when to avoid using 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that bundlephobia's first measurement on a new version can take 5-30 seconds and that sources_failed will list timeouts, with the rest returning successfully.

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 purpose and follows a clear logical structure. It is slightly verbose but every sentence adds value. A minor reduction in length could improve conciseness.

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

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

Without an output schema, the description fully details the return shape (summary block, per-advisory details, links, alternative versions), partial failure behavior, and ecosystem scope. It leaves no critical information missing.

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

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

Schema coverage is 100% with both parameters described. The description confirms that scoped packages are accepted and version defaults to latest, but adds little beyond what the schema says. 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 it is a composite check for deciding whether to add an npm package, mentioning specific data sources (deps.dev, bundlephobia) and distinguishing from siblings by explicitly noting this is for npm only, with alternatives 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 says to use when an agent asks about safety, popularity, size, or cost of adding a package. Also provides guidance that for other ecosystems (PyPI, Maven, etc.) one should use deps.dev:version directly, and notes graceful degradation on timeout.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K with truncation flag), and output details (offsets, similarity scores). 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 about four sentences, front-loaded with purpose and usage. All sentences add value, though 'saves context' slightly overlaps with 'use when record is too big'. Overall efficient and well-structured.

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

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

Despite no output schema, the description explains return format (passages with offsets and similarity scores), technical details, and pairing suggestions. Annotations cover safety. No gaps remain for agent decision-making.

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

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

Schema coverage is 100%, but description adds examples for query (e.g., 'supply-chain risk'), default and range for limit, and clarifies text max length (~200K chars). Adds meaningful context 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded and providing usage context.

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 advises using this tool when a record is too large for the prompt, explains it saves context, and suggests pairing with ask_pipeworx_grounded for grounded answers. Provides clear when-to-use guidance and an 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 indicate idempotentHint=true, but the description clarifies that a subscription is created (idempotent might mean same params yield same result?). It adds behavioral details: returns subscription ID, requires account, feed always on, email/SMS/webhook delivery specifics, and webhook auto-disable after 10 consecutive failing runs. 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 and front-loaded with the main purpose. Each sentence adds value without redundancy. It balances detail with readability, making it efficient for an AI agent to understand and use.

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 (multiple subscription types, delivery channels, prerequisites, and limitations), the description is exceptionally complete. It covers account requirements, type-specific parameters, delivery options with constraints, and behavioral details like webhook signing and auto-disable. No output schema exists, but the return value (subscription ID) is mentioned.

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 significant meaning beyond the schema. It explains each enum value with examples, details the params object for each subscription type with concrete JSON examples, and describes the delivery object with email, SMS, and webhook including verification and limitations.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and providing specific subscription types and parameters.

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 (to create a subscription) and when not to (requires a Pipeworx OAuth account; anonymous and BYO cannot persist). It also provides guidance on different subscription types and delivery channels, including constraints like SMS rate limits and webhook auto-disable.

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

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

Description adds rich detail beyond annotations: explains that calling with no arguments gives full spread, or with topic focus, and describes the return structure (category-bucketed examples with tool+argument shape), providing comprehensive behavioral insight.

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

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

The description is well-structured, front-loaded with common queries, and each sentence adds value; slightly verbose but efficient for its informative role.

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

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

Even without an output schema, the description fully explains what is returned and covers all necessary context for agent understanding and effective use.

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

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

Schema coverage is 100% with a clear description; the description reinforces the parameter's purpose and values but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions with tool call shapes, distinguishing it from siblings like 'discover_tools' and 'ask_pipeworx' by specifying when to use it first.

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 advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', and mentions optional topic filtering, but does not explicitly exclude use cases.

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

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

Annotations already indicate non-destructive (destructiveHint: false) and idempotent (idempotentHint: true) behavior. The description adds valuable context about ownership enforcement and that rows are deactivated not deleted, complementing the annotations without contradiction.

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

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

The description is extremely concise at two sentences, front-loading the core action 'Cancel a subscription by id'. Every phrase adds value: ownership enforcement, deactivation vs deletion, and reference to recent_alerts.

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

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

For a tool with one parameter and no output schema, the description fully covers behavior (cancel, deactivate), constraints (ownership), and effect on historical data (available via recent_alerts). It provides enough context for correct invocation.

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

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

The schema covers 100% of parameters with a clear description of 'id' as a UUID from subscribe. The tool description reiterates 'by id' but does not add new semantic information beyond what the schema already provides.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning deactivation vs deletion and referencing 'recent_alerts' for historical events.

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

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

The description explicitly mentions ownership enforcement ('only cancel your own subscriptions') and explains the effect of deactivation with a reference to 'recent_alerts' for historical data. It implies when to use (own subscriptions) and provides an alternative for viewing deactivated events, though it could more directly 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.

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the return structure (verdict options, structured form, actual value, citation, percent delta) and explains it consolidates several steps. 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 concise (~150 words) with front-loaded purpose and examples. Every sentence adds value: usage cues, scope, return details, efficiency benefit. 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?

Given simple input (one required parameter) and rich annotations, the description covers return values, limitations, and use case. No output schema needed as description provides sufficient detail. Complete for an agent to use correctly.

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

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

Only one parameter (claim) with schema description providing examples. Description echoes those examples but adds no new semantic detail. Schema coverage is 100%, 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 tool's purpose: natural-language claim verification against authoritative sources, with specific examples of user queries. It also delineates the scope (company-financial claims for public US companies) and the data sources (SEC EDGAR + XBRL), making it distinct from sibling tools.

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

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

The description advises use when the agent needs to fact-check a user statement and notes it replaces multiple sequential calls. It implicitly limits use to current v1 capabilities (financial claims), but does not explicitly list alternative tools for other claim types.

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