Retractions

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

Annotations already indicate readOnly, idempotent, benign behavior. Description adds cost implications (free vs BYO key), output structure (per-model fields + combined view), and the scoring mechanism. No contradictions. Lacks details on rate limits or potential delays, but enough for safe usage.

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

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

Three sentences: first defines purpose and output, second explains model choices and key usage, third states return structure. Front-loaded with key information; 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 no output schema, description adequately describes return format per-model and combined view. Could mention example or clarify 'signals' but sufficient for typical use. Sibling tools are covered partially by the different 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 coverage is 100%, baseline 3. Description adds value by explaining default model behavior, BYO key necessity for Anthropic, and the purpose of the context parameter for disambiguation. This goes beyond bare schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility per model. It specifies the verb ('probe'), resource ('LLMs'), and output (score 0-100). Differentiates from siblings like 'scan_competitor_ai_presence' by focusing on any business/brand/product/topic, not 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?

Provides clear context for when to use: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and how to use Anthropic with BYO key. However, it does not explicitly state when not to use or suggest sibling alternatives, which would strengthen 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 cover safety (readOnly, idempotent, not destructive). Description adds value by mentioning it routes to 4862 tools and returns structured answers with citation URIs.

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

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

Description is thorough and front-loaded with priority statement, though slightly lengthy. Every sentence adds value, but could be 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?

Despite complexity (no output schema), description covers behavior, usage guidance, sibling differentiation, and return format (citations). Complete for agent to decide.

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

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

Schema coverage is 100% with all parameters described. The description does not add parameter-level details beyond the schema, so baseline score of 3 is appropriate.

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

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

Description clearly states it answers factual questions using structured data from verified sources, distinguishing from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides when to use, and specifies when to step up to grounded or deep_research with 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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds concrete behavioral details: extra LLM call cost, return format with evidence and refusal reasons, and guarantee of fact-based answers. 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 the key purpose at the start, but slightly verbose. Every sentence adds value, though some could be condensed. Front-loading 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?

Despite no output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. Covers behavior, use cases, and cost, making it complete.

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

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

Schema coverage is 100% with aliases documented. The description adds value by explaining that 'question' accepts natural language and that all aliases are accepted, but the schema already covers this. Slight extra context justifies above baseline.

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

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

The description explicitly states it is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results with refusal reasons. It clearly distinguishes from the sibling ask_pipeworx by noting cost and use case.

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

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

Provides explicit when-to-use (high-stakes reads, quoatable/citable answers) and when-to-avoid (prefer ask_pipeworx for casual lookups). Includes specific examples like financial verdicts, legal claims, and medical lookups.

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

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

The description goes far beyond the annotations, detailing fan-out behavior, response shapes, resolver contract, safety mechanisms (e.g., low-confidence short-circuit), and handling of closed markets. Discloses nuances like cancellation rules and tradeability notes, providing full behavioral transparency.

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

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

The description is lengthy but well-structured with clear sections (classifiers, fan-out examples, response fields, safety). It front-loads the core purpose and usage. Could be slightly more concise, but the detail supports agent understanding.

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

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

With no output schema, the description fully specifies response structure (market, analysis, evidence), resolver contract, parent event extraction, news fields, error states, and tradeability. Covers all relevant scenarios 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?

Schema coverage is 100%, and the description adds significant value: explains that market accepts slug, URL, or question text; depth enum values and default; include_raw with rationale for when to use true/false. Examples in schema further clarify usage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It uses specific verbs and resource, and the usage examples ('should I bet on X') distinguish it from sibling tools like 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?

Explicit use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), giving clear context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, which would strengthen the 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the agent knows it's safe and idempotent. The description adds value by clarifying that 'not retracted' means no record, not definitive proof, which is important 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 two sentences plus a note, no wasted words. All key information (action, sources, return format, caveat) is front-loaded and efficiently presented.

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 check tool with no output schema, the description adequately explains the return format (retracted:true/false with evidence). The caveat about coverage completes the picture, making it sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100% with a clear example for the DOI parameter. The description does not add additional semantic details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool checks retraction status of a paper by DOI, naming the data sources (Crossref/Retraction Watch) and specifying keyless access. It distinguishes itself from the sibling 'search_retractions' by being a single-lookup tool rather than a search.

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

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

The description explains what the tool does but does not explicitly state when to use it vs. alternatives like 'search_retractions'. The note about coverage dependency is helpful context but not a clear when-to-use guideline.

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

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

Beyond annotations indicating read-only, idempotent, and non-destructive behavior, the description adds detailed behavioral context: for companies it pulls latest 10-K data with correct fiscal year handling; for drugs it pulls FAERS counts; results are sorted by primary metric; returns paired data with citation URIs.

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

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

The description is well-structured and front-loaded with example queries, but it is somewhat lengthy. Every sentence adds value, but a slight trim could improve conciseness.

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

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

Given no output schema, the description adequately explains return values (paired data + citation URIs). It covers both entity types and provides sufficient context for the agent to understand the tool's capabilities and output.

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

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

The input schema covers 100% of parameters with descriptions, and the description enriches each parameter: for 'type' it specifies what data is pulled for each enum value; for 'values' it provides examples and constraints (min/max items).

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 specifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example queries and distinguishes itself from sequential single-pack lookups, making it easy for the agent to understand and select.

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 'ALWAYS PREFER over sequential single-pack lookups' and explains the context for each type. It also mentions replacing 8-15 sequential lookups, providing strong guidance on when to use this tool versus alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds rich behavioral details: decomposes questions, routes to tools in parallel, returns findings with confidence/source/citations, gap reporting, hop field, contradiction scan. 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 long but well-structured: begins with prerequisite, then core functionality, then sibling comparison, then depth details, then output format. Every sentence adds value, though slightly verbose. Front-loaded with critical info.

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

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

Given no output schema, the description fully explains the return value: 'findings packet: verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation per finding, with explicit gaps[]'. Also covers hop field, contradictions for thorough, edge cases for non-catalog topics. Completes the picture.

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 schema. It explains the depth enum with detailed behavior for each level ('quick=3... standard=5... thorough=8...'). Question parameter described as natural language, broad/multi-part fine.

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 1272 STRUCTURED data sources' and returns a findings packet. It uses specific verbs ('decomposes', 'routes', 'returns') and distinguishes from siblings (ask_pipeworx for single lookup, current news).

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: 'Best for broad/multi-part questions over structured data'. Provides explicit alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirement and paid plan for depth:'thorough'.

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 and destructiveHint=false, so safety is clear. The description adds value by specifying that it '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 explains the output format and readiness for invocation, which is not captured in 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 a single paragraph with a clear front-loaded purpose statement and usage guidance. Every sentence adds value, though slightly longer than necessary. No redundancy or fluff.

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

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

For a discovery tool with 6 parameters (only 1 required) and no output schema, the description fully explains what the tool returns ('top-N most relevant tools...') and how to use it. It addresses the need for tool exploration without external references. 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 100% with all 6 parameters described, including examples for 'query' and aliases. The description does not add new semantic information beyond what the schema already provides. Baseline rating 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?

Clearly states the tool discovers tools based on natural language queries. Distinguishes itself from sibling tools by positioning as a first-call to explore the toolset, not to get a single answer. The verb 'find/discover' and resource 'tools' are specific and distinct.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides concrete examples of domains and tasks. Tells when to use versus when not needed.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, not destructive), the description adds rich behavioral context: it fans out across multiple sources, mentions fallbacks (GDELT→GNews), soft-fails for patents, and describes return fields. 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 front-loaded with example queries and a clear purpose statement. It is verbose due to tool complexity but each sentence contributes value (usage, data sources, limitations). Slightly trimmed could improve, but structure is logical.

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

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

Given the complexity (multiple data sources, fallbacks, soft-fail) and no output schema, the description thoroughly explains return structure (cik, filings with URIs, fundamentals, patents, news, LEI). It covers limitations (patents soft-fail, name resolution needed) and provides actionable guidance for the agent.

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

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

Schema covers 100% with descriptions for both parameters. The description adds value by specifying exact formats: 'Pass ticker "AAPL" or zero-padded CIK "0000320193"' and clarifying names are unsupported, with a link to resolve_entity. This exceeds baseline but schema already provides basic 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 explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources (SEC, XBRL, USPTO, etc.). It distinguishes itself from chaining individual lookups by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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 provides clear use cases with example queries ('Tell me about X', 'research Acme'), and explicitly advises when not to use: if you only have a name, use resolve_entity first. This differentiates from the sibling tool resolve_entity.

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 destructiveHint=true and readOnlyHint=false. The description confirms the destructive nature by stating 'Delete a previously stored memory' and specifies the mechanism (by key), adding value beyond annotations.

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

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

The description is two sentences, front-loaded with the action, and contains no unnecessary words. 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 simple one-parameter destructive tool, the description fully covers action, parameter, usage context, and sibling relationships. No output schema is needed, and the information is 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 a clear parameter description ('Memory key to delete'). The description adds no additional semantic depth beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the verb 'Delete' and resource 'previously stored memory' by key. It also distinguishes itself from siblings by explicitly pairing with 'remember' and 'recall', making its role clear.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, though does not explicitly state 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?

The description adds behavioral detail beyond the annotations: it fetches the page, extracts title/description/key links, and emits standard markdown. This informs the agent about network activity and output format. The annotations already indicate read-only, idempotent, non-destructive behavior, so the description complements 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 brief and front-loaded: it states the core action first, then the process, then the output format, and finally use cases. Every sentence adds value with no redundancy.

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

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

For a simple tool with two well-documented parameters and no output schema, the description covers the output format, use cases, and behavior. It could mention error handling or invalid URLs, but overall it is 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?

The input schema already provides complete descriptions for both parameters (100% coverage). The tool description echoes some of this (e.g., default and max for max_links) but does not add new meaning beyond the schema. 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 'generate' and the resource 'llms.txt file for any URL'. It also lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitors) which distinguishes it from related sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence'.

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 ('Useful for: ...') which gives clear context for when to use this tool. However, it does not explicitly state when NOT to use it or mention alternatives among sibling tools, which would increase clarity further.

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, which cover the safety and idempotency profile. The description adds that it returns specific fields and mentions the optional parameter, but this is largely redundant with the schema. No contradictions, but limited added 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?

Two sentences: first states purpose and return fields, second gives usage guidance. No redundant words, front-loaded with key information. Excellent conciseness.

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

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

Given the tool's simplicity (one optional param, no output schema, strong annotations), the description covers purpose, return values, and usage. It is fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the single parameter include_inactive, with its own description. The tool description reiterates 'active subscriptions' but does not add new meaning beyond the 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 verb (List), resource (subscriptions), and scope (caller's active). It also enumerates the return fields, making the tool's function unambiguous. The title 'List Subscriptions' reinforces this, and siblings like subscribe and unsubscribe confirm it's distinct.

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 the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and distinguishes it from other tools, leaving no 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?

The description adds behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. This aligns with annotations (readOnlyHint=false indicating a write operation) and provides important usage constraints.

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

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

The description is compact and front-loaded with purpose, then usage guidelines, then behavioral info. Every sentence adds unique value with no redundancy.

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

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

Given the tool's simplicity (3 params, nested object, no output schema), the description is complete: it covers when to use, how to format feedback, rate limits, and quota impact. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the enum values for type and advising on message formatting ('Be specific... 1-2 sentences typical, 2000 chars max'). 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 is for sending feedback about broken/missing things or praise. It uses specific verbs ('Tell', 'Describe') and distinguishes itself from sibling tools by being a feedback mechanism rather than a research or analysis tool.

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

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

The description explicitly lists when to use (bug, feature, data_gap, praise) and what not to do (don't paste the end-user's prompt). It also implies that other tools are for different purposes, providing clear context for tool selection.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds important behavioral details: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and aggregate nature. 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 concise sentences plus a bullet list. Core purpose is front-loaded. Every sentence adds value with no redundancy.

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

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

Given the simple tool (one optional param, no output schema), the description covers return values, use cases, data source, and caching. No missing aspects for effective use.

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

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

Schema coverage is 100%, but the description adds extra nuance: shorter windows surface current trends, longer windows show steady-state demand. This goes beyond the enum 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 the tool returns top tools, top packs, and total call volume over a window, with specific verbs and resource. It distinguishes itself from sibling tools by focusing on trending data rather than specific queries or actions.

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?

Three explicit use cases are provided, giving clear context for when to use the tool. However, it does not mention when not to use or compare to alternatives, which could be improved.

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 non-destructive. The description adds substantial behavioral details: scanning top ~200 markets, child market walking, date/threshold ordering checks, partition_sum validation, similarity filtering, placeholder filtering, and fill check logic. This goes well 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 comprehensive and well-structured, front-loading the main purpose and modes. While lengthy, every sentence adds value. A minor reduction for not being more concise, 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 is provided, but the description thoroughly explains the response structure: opportunities array with gap_pp, suggested_trade, reasoning, monitoring context; partition_check object; and fill_check details. Given the tool's complexity, this is a complete and self-contained 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% with descriptions. The tool description adds significant context: event mode requires a Polymarket event slug, topic mode expects a seed question, and provides concrete examples. This enriches parameter semantics 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: trending scan (no args), event mode, and topic mode, making the purpose specific and differentiated 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 provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. It explains the context for each but does not explicitly state when not to use the tool, so it's slightly less than a 5.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) are complemented by extensive behavioral details: caching (1h KV keyed on knobs), Fed bet exclusion, model formulas (e.g., FRED log-returns, GDELT), output structure (by_segment, diagnostics), and risk warnings (24h move alert). 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 well-structured with clear sections (model families, response components, diagnostics). Front-loaded with core purpose. Could be more concise without losing detail, but the complexity justifies 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 9 parameters and no output schema, the description thoroughly documents output structure (by_segment segments, diagnostics), model behavior, caching, and edge-case handling (Fed bets). It provides sufficient information for an agent to invoke the tool and interpret results.

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

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

Schema coverage is 100%, and the description adds significant context beyond schema: explains tradeable-edge knobs (min_liquidity, max_spread_pp), usage of min_partition_leg_kelly for partitions, slippage_pp rationalization, and how min_kelly applies only to single-leg opportunities. Each parameter's role in filtering is clarified.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It specifies the verb (scan/return) and resource (Polymarket markets/opportunities), and distinguishes from siblings like polymarket_arbitrage by detailing three model families.

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 (daily betting discovery), notes that Fed bets are excluded from ranking due to unreliable data, and provides guidance on tradeable-edge knobs. It implicitly differentiates from siblings through model family descriptions but lacks explicit when-not-to-use references.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds rich detail: returns tracked opportunities with time-series, first_seen, trend, decay; expired opportunities with lifespan_days; snapshot_dates; explains gaps due to cache-miss; and notes history bounded by 60-day TTL and decay computed from daily closes. 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: opens with purpose, then details response fields (tracked, expired, snapshot_dates) in a readable format, followed by LIMITS. It is slightly verbose but effectively front-loaded and organized. 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?

Given the complexity (multiple arrays, time-series, derived metrics) and the absence of an output schema, the description thoroughly explains the return structure: tracked (with time-series, first_seen, trend, decay), expired (with lifespan_days), and snapshot_dates. It also covers limitations (60-day TTL, decay from daily closes). This is complete for an agent to understand 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%, so baseline is 3. The description adds context for parameters ('days (lookback, default 14, max 30)', 'window (snapshot family, default 1wk)') but does not add significant meaning beyond the schema's own descriptions (e.g., 'Lookback in days (default 14, clamp 2-30)' and 'Which polymarket_edges window family to read snapshots for: 24hr | 1wk | 1mo (default 1wk)'). Thus, it meets but does not exceed 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 states the tool's purpose: 'Edge persistence and decay telemetry... answers how long has this edge existed and is it shrinking?' It uses specific verbs (track, answer) and distinguishes from siblings like polymarket_edges (current snapshot vs historical) and polymarket_arbitrage.

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

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

The description implies when to use (e.g., differentiating a fresh wide edge from a 3-week-old edge) but does not explicitly state when not to use this tool or name alternatives. It mentions LIMITS, which helps understand applicability, but lacks explicit exclusionary 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 indicate readOnlyHint=true, destructiveHint=false, etc. The description adds significant behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk and unhedged positions. 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 lengthy but well-structured with clear sections for modes, defaults, and return fields. Every sentence adds essential information; there is no fluff. The use of all-caps for key terms aids readability. Slight density prevents a 5 but remains 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?

With no output schema, the description fully explains the return structure for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). This is complete for an agent to understand tool output.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds value beyond schema: it explains the meaning of size_usd in basket mode ('settlement notional — shares per leg'), side defaults ('auto from partition sum'), and clarifies that size_usd is 'max spend on buys, target proceeds on sells' for single-market. 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket) and specifies the required input ('REQUIRES one of `market` or `event`'). This differentiates it from sibling tools like polymarket_arbitrage (which finds opportunities) and polymarket_edges (which identifies 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 the 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 (partial basket fills convert an arb into an unhedged directional position) and implies when not needed (smaller trades).

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), the description explains response structure, safety fields, temporal alignment, and leg-matching logic, fully disclosing behavior.

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

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

Well-structured with sections and bullet points, but slightly lengthy. Could be more concise 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?

Given no output schema, the description thoroughly covers response fields (legs, spreads, compatibility, temporal alignment) and edge cases, making it complete for a complex tool.

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

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

Input schema already has 100% coverage with descriptions. The tool description adds context on mode selection and override behavior, but schema already documents parameters well.

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

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

The description clearly states it calculates cross-venue spreads between Polymarket and Kalshi, detailing two modes (topic shortcuts and explicit pairing). It distinguishes itself from sibling tools by being the only spread tool.

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

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

Explicitly describes when to use (comparing spreads across venues) and when not (compatibility_warning cases). Warns that most pre-mapped topics are not tradeable, guiding proper 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?

Adds scope info (by identifier) and pairing with remember/forget, beyond annotations which already indicate readonly/idempotent.

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

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

Three concise sentences with front-loaded action and usage. 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?

Fully explains retrieval vs listing modes, scoping, and pairing with siblings. Sufficient for a simple query 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 covers key param fully, but description adds real-world examples and clarifies listing behavior on omission.

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 two specific actions: retrieving a value by key and listing all keys. Distinct from siblings like 'remember' and 'forget'.

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

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

Explicitly describes when to use: look up stored context (ticker, address, notes). Missing explicit 'when not to use', but context is clear.

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

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

The description discloses behavioral traits such as the effect of mark_read parameter and the structure of returned alerts. However, there is a potential contradiction: the annotation readOnlyHint: true, but the tool allows marking events as read, which is a write operation. The description does not resolve this inconsistency.

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 five sentences, each adding distinct information: purpose, return fields, filtering options, mark_read behavior, and alternative access. No fluff or redundancy.

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

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

Given the tool has 5 optional parameters and no output schema, the description covers the key aspects: what is returned (source, citation_uri, payload), filtering, and polling behavior. It also mentions an alternative REST endpoint. Slightly lacking explanation of the unread_only parameter and limit, but schema covers them.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the use of type, since, and mark_read in context, and provides an example for type filtering. This enhances understanding 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 starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull fired events). It distinguishes from sibling tools by focusing on retrieving events rather than managing subscriptions or other actions.

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 guidance by noting that polls work fine for this tool and that the same feed is available via a REST endpoint for scripts and dashboards. It explains filtering options but does not explicitly contrast with sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: fans out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior (GDELT preferred, GNews on rate-limit/5xx), soft-fail for USPTO due to API sunset, and return structure (changes grouped by source, total_changes, citation URIs). 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 fairly long but every sentence adds value: examples, fan-out explanation, parameter guidance, differentiation from sibling. It is front-loaded with query examples. While not excessively concise, it avoids fluff and is 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 complexity (multi-source aggregation, fallbacks, soft-fail, structured return) and lack of output schema, the description is thorough. It covers sources, fallback logic, parameter semantics, and return format, making it complete for an agent to understand and use 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%, but the description adds significant meaning: explains that `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. Also clarifies that `type` is currently limited to 'company'. This goes well beyond the schema.

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

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

The description clearly states the tool is for retrieving recent changes ("What's new with X") for a company over a time window. It distinguishes itself from entity_profile, which provides static profiles. The verb and resource are specific: 'change feed for a company'.

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 usage examples covering various phrasings and contexts. Also clearly specifies when to use an alternative tool: 'Use entity_profile instead when you want the static profile'. This gives the agent clear guidance on tool selection.

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

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

The description adds significant behavioral context beyond annotations: scoping by identifier, persistence details (authenticated persistent, anonymous 24-hour retention), and pairing with recall/forget. Annotations already provide idempotency and non-destructive hints, and the description aligns with these 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 concise at 4 sentences, front-loaded with the main purpose, and includes all necessary details without extraneous information.

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

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

For a simple key-value store tool with two parameters, no output schema, and comprehensive annotations, the description covers usage context, parameter hints, scope, persistence, and sibling tool relationships completely.

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 reiterates the key-value pair concept and provides example keys in the schema, but adds no additional semantic meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Save data' and the resource 'the agent will need to reuse later', specifying cross-session persistence. It distinguishes itself from sibling tools like recall and forget, establishing a 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?

The description provides clear context for when to use this tool: 'when you discover something worth carrying forward'. It mentions pairing with recall and forget, but does not explicitly state when NOT to use it or alternatives beyond 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 indicate safe, read-only, idempotent behavior. The description adds valuable context: internal cascading across multiple lookup endpoints, replacement of 2-3 manual steps, and specific return fields (ticker, CIK, company name, citation URIs for company; RxCUI, ingredient, brand for drug).

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 an opening query pattern, then detailed breakdown by type. It is informative without being overly long; every sentence contributes useful information.

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

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

For a tool with simple inputs and no output schema, the description comprehensively explains purpose, usage, supported types, inputs, and expected outputs (including citation URIs). It is fully self-contained and leaves 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?

Schema has 100% coverage with descriptions for both parameters. The description enhances this by providing concrete examples (AAPL, 0000320193, ozempic) and clarifying acceptable input forms for each entity type, adding value 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 resolves user-spoken names to canonical identifiers, with specific examples like ticker, CIK, or drug IDs. It distinguishes itself from sibling tools by positioning it as the first tool to use when a name needs conversion to 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?

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It provides detailed context for each supported type, including acceptable inputs and outputs, but does not explicitly state when not to use the tool or name 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, and signal density. 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 two sentences plus a contextual example, highly concise and front-loaded. Every sentence adds value, with no redundant or irrelevant information.

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

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

Despite no output schema, the description sufficiently explains return values (ranked list with score, confidence, signal density) and the internal process. It covers the tool's functionality completely.

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 that the first entity in the array is treated as the 'subject' for narrative, enhancing 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 it compares AI visibility across multiple entities, probes with ai_visibility_check, and ranks by score. It distinguishes itself from the sibling tool ai_visibility_check by focusing on multiple entities and providing a ranked 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 explains its purpose for competitive AI-marketing audits with an example ('does Claude know about us as well as our competitors?'), but does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entity comparisons.

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

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

Adds behavioral context beyond annotations: describes partial failures gracefully (bundlephobia first measurement timeout 5-30s, sources_failed list). Annotations already cover readOnly, idempotent, etc. 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 relatively long but each sentence adds value. Front-loads the core purpose. Could be slightly more structured but is effective and not wasteful.

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

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

Given no output schema, description thoroughly enumerates return fields and covers failure behavior. Ecosystem limitation noted. Lacks authentication/rate limit info, but annotations and context suffice.

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 has 100% coverage with descriptions. Description adds value by listing output fields and confirming scoped packages are accepted, enhancing understanding of parameter implications.

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

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

The description clearly defines the tool as a composite check for npm packages, using deps.dev and bundlephobia to assess safety, popularity, and size. It distinguishes from sibling tools by specifying the npm ecosystem and the one-call nature.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and when not (other ecosystems like PyPI/Maven fall under different tool). Provides alternatives for non-npm packages.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns specific fields (DOI, title, journal, date) and the data source, which is valuable context beyond annotations.

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

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

Two concise sentences, no wasted words. Every part adds value.

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

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

Lacks output schema, but description explains return fields. However, the missing subject filter inconsistency creates a completeness gap.

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, but the description adds no new meaning and falsely claims a 'subject' filter exists. This contradicts the schema and reduces trust in parameter semantics.

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

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

The description clearly states it searches retracted literature by keyword, specifies the data source (Crossref update-type:retraction) and scope (~73k works), and lists return fields. This distinguishes it from siblings like check_retraction.

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

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

The description mentions optional filtering by subject and publication year range, but the subject filter is not present in the input schema. This inconsistency could mislead an agent into attempting a non-existent parameter, reducing clarity on 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?

The description adds significant value beyond annotations: mentions BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and that return includes character offsets and 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?

Six sentences, front-loaded with purpose, well-structured with technical details and pairing info. No wasted words.

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

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

Despite no output schema, the description clearly explains return values (passages, offsets, scores), technical details (embeddings, windows, cap), and integration with sibling tools. Fully adequate for an agent to understand usage and behavior.

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

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

Schema coverage is 100%, but the description reinforces defaults (limit=5) and provides query examples, adding context 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 it performs semantic search inside a fetched record (specific verb+resource) and distinguishes itself from sibling tools by mentioning it pairs with ask_pipeworx_grounded for grounding.

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

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

Explicitly says when to use: when the record is too big to cram into the prompt. Mentions pairing with ask_pipeworx_grounded as an alternative approach, though does not explicitly 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?

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true. The description adds significant context: requires OAuth, delivery channel constraints (phone verification, 10/day SMS cap, webhook secret one-time return, auto-disable after 10 failures). This goes 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 well-structured: main purpose first, then requirements, then supported types with examples, then delivery channels. Every sentence adds value 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 (3 params, nested objects, no output schema), the description covers all necessary aspects: what it returns, prerequisites, type-specific parameters, delivery options with constraints, and failure behavior.

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

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

Schema coverage is 100%, yet the description adds concrete examples for each type (e.g., items:['5.02'] for sec_8k) and clarifies constraints (e.g., webhook secret returned once). This adds valuable 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 starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description explains the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It provides context for when to use this tool (proactive monitoring) but does not explicitly list when-not or 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 already provide readOnly, openWorld, idempotent, and non-destructive hints. Description adds behavior beyond annotations by explaining the return format (category-bucketed examples with tool+argument shape) and the effect of the topic parameter. No contradictions.

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

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

Description is front-loaded with trigger phrases and structured effectively. It is slightly long but every sentence adds value. Could be trimmed slightly, but overall 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, description sufficiently explains return format (category-bucketed examples with tool shapes). Covers purpose, parameters, usage, and context. No missing information for an onboarding tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples of topic values (e.g., 'finance', 'pharma') and explains that omitting topic gives full spread, which is helpful but not essential beyond the schema's enum list.

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 explicitly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs and resources, and distinguishes itself from siblings like ask_pipeworx and discover_tools by being the first-use tool.

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

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

Clear guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains when to pass a topic vs no arguments and mentions alternatives (meta-tools). Explicit when-to-use and 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?

Adds valuable behavioral context beyond annotations: explains that the row is deactivated not deleted, and that historical events remain available via recent_alerts. This aligns with idempotentHint=true and destructiveHint=false annotations, with no contradictions.

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

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

Two-sentence description is concise and front-loaded: first sentence states the core action, second adds constraints and side effects. No unnecessary words.

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

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

The tool has only one parameter and no output schema; the description covers the main action, ownership constraint, and side effects (deactivation, historical data retention). 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?

Only parameter 'id' is described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add additional context about the parameter beyond what is in the schema; schema coverage is 100%.

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 'Cancel a subscription by id' which is a specific verb-resource combination. It distinguishes from sibling tools like 'subscribe' (creates subscription) and 'list_subscriptions' (lists existing subscriptions).

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear usage constraint. Does not explicitly state when not to use or mention alternatives, but the constraint is sufficient for 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 provide safe read-only, idempotent, and non-destructive hints. The description adds beyond this by explaining the tool returns a verdict (with possible values), extracted structured form, actual value with citation, and percent delta. It also discloses that it replaces multiple sequential calls, implying efficiency.

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 natural-language phrases to help the agent recognize when to use the tool. It is somewhat lengthy but every sentence adds information. It could be slightly more concise, but the structure 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?

Given the tool has a single parameter, rich annotations, and no output schema, the description provides all necessary context: purpose, input, output format (verdict types, structured form, citation, delta), and scope (company-financial claims). It is complete for an AI agent to use correctly.

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

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

There is only one parameter (claim) with 100% schema description coverage. The description adds value by giving examples of natural-language claims and explaining that the claim is a factual statement. This provides more context than 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: verifying natural-language factual claims against authoritative sources, specifically company-financial claims. It provides a specific verb ('verify') and resource ('claims'), and distinguishes from siblings by mentioning it replaces 4-6 sequential calls.

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: 'whenever the agent needs to check whether something a user said is factually correct.' It provides example query types and specifies the scope (company-financial claims for US public companies). It lacks explicit 'when not to use' or alternative tools but offers strong guidance.

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