Dryad

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context: the default model is free, Anthropic requires BYO key, and the return structure is per-model {score, confidence, signals, raw_response} plus a combined view. No contradictions with annotations.

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

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

The description is a compact three-sentence paragraph. It front-loads the main action (probe LLMs and score visibility), then provides key details (default model, parameter explanation, use cases). Every sentence contributes value, with no redundancy or filler.

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

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

With no output schema, the description appropriately mentions the return fields. All 4 parameters are covered, and annotations cover safety. The use cases are stated. Minor missing details like rate limits or response size are not critical for this tool type. Overall, it provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond schema by explaining the default model, the optional nature of models parameter, the purpose of _apiKey (BYO key), and how context helps disambiguate. This enriches the agent's understanding of parameter 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 it probes LLMs for knowledge about a specific entity and scores visibility (0-100). It specifies the default model and mentions three distinct use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This provides a specific verb+resource+scope that distinguishes it from sibling tools like entity_profile or 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 explains when to use the tool (for visibility audits) and provides guidance on selecting models (default workers-ai, optional anthropic with _apiKey). It does not explicitly tell the agent when NOT to use it or contrast it with sibling tools, but the use cases are clear enough for a competent agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but description adds further context: it routes to the appropriate tool, fills arguments, and returns structured answers with 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?

Well-structured with clear sections and effective front-loading. Some redundancy with schema examples, but overall efficient for the amount of guidance provided.

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

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

For a complex tool routing to thousands of sources, the description covers purpose, usage, behavior, and alternatives. It mentions return format (structured with citations), which is sufficient despite no output schema.

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

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

Schema coverage is 100% and the description doesn't add detailed parameter semantics beyond the schema, but it provides practical examples of questions that map to the 'question' parameter, which is helpful for the agent. Baseline 3 is elevated slightly by the examples.

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 states the tool routes questions to a large set of authoritative sources for structured data, with specific verbs and resources like 'SEC filings', 'FDA drug data', etc. It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance with examples of question types. Also tells when to step up to sibling tools, making usage boundaries very 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?

Describes multi-step process (selects tool, fetches data, extracts answer using only result), output format with refusal reasons, and costs. Adds significant context beyond annotations.

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

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

Single paragraph with front-loaded purpose, then behavior, usage, and cost. Every sentence adds value; no fluff.

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

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

Despite no output schema, description fully explains return fields and refusal reasons. Covers use cases, cost, and alternatives. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds context on how the question parameter is used in the extraction process and mentions the accepted aliases, slightly enhancing semantics.

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

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

Clearly states 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by highlighting groundedness.

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 (for quoted/cited/acted-on answers) and when not (prefer ask_pipeworx for casual lookups), with examples like financial, legal, 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description greatly expands transparency by detailing resolution logic, fan-out patterns, blocking statuses, tradeability warnings, and resolution-rule risk. It provides extensive behavioral context well beyond what annotations offer, with no contradictions.

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

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

The description is very long (multiple paragraphs) and contains detailed technical information. It is well-structured with sections and headings, but many details (e.g., specific fan-out examples, response shapes) could be in an output schema or separate documentation, making the description somewhat bloated for a tool summary.

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

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

Given the absence of an output schema, the description thoroughly covers all aspects: response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. It addresses edge cases and provides actionable details, making it highly 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds significant meaning: it explains acceptable formats for 'market', the implications of 'depth' (quick vs thorough), and the size impact of 'include_raw'. This enriches the schema definitions, though a baseline of 3 is elevated by the added context.

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

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

The description clearly states the verb 'Research' and the resource 'Polymarket bet', and specifies it pulls Pipeworx data. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a single bet's comprehensive data. The purpose is explicit and unambiguous.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides warnings about low-confidence matches and closed markets, guiding when the tool is appropriate. However, it does not mention explicit alternatives among siblings for 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 declare readOnlyHint, openWorldHint, idempotentHint as true, and the description adds behavioral details such as data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions.

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 is detailed, but every sentence adds value. Slightly lengthy but efficient for a complex tool.

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 mentions return format (paired data + citation URIs) and covers all necessary context for the tool. It distinguishes itself from sibling tools and provides complete guidance for the 2-parameter input.

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 2 parameters. The description adds significant meaning: explains what each type 'company' and 'drug' retrieve, clarifies that values can be tickers/CIKs for companies or drug names, and notes result sorting. This goes well beyond the schema's basic descriptions.

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

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

The description clearly defines the tool as a side-by-side comparison of 2-5 companies or drugs, with example queries like 'Compare X and Y' and specific data sources for each entity type. It distinguishes itself effectively from sibling tools like entity_profile and search tools.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains that it replaces 8-15 sequential lookups, providing clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context: expected response times (15-90s), depth levels with details (gap recovery, contradictions, semantic excerpting), citation format, and output structure. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with critical info (account requirement, alternative tool). Every sentence adds value, describing behavior, parameters, and outcomes. Some redundancy exists but is outweighed by the complexity of the tool.

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

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

No output schema, but the description fully explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. Sufficient for an AI agent to understand the tool's capability 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?

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: explains depth levels in detail (quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 with iterative hop and contradictions) and clarifies that the question should be broad/multi-part.

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: grounded multi-source research across 1293 structured data sources, decomposing questions into facets and routing to 4927 tools in parallel. It distinguishes itself from siblings like ask_pipeworx, which is for single lookups or 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 says when to use (broad/multi-part questions over structured data) and when not to use (breaking news, single lookup, which should use ask_pipeworx). Also mentions account requirements and paid tier for thorough depth.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: returns '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.' No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose and action. While the list of domains is somewhat lengthy, it is informative and justifies the tool's scope. No superfluous sentences; each adds value.

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

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

Given no output schema, the description explains return content thoroughly. Parameter coverage is complete via schema. The description covers when to use, what to expect, and examples, making it self-sufficient for an AI agent.

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

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

Schema coverage is 100% with each parameter described. The description adds that 'query' accepts natural language and lists aliases (task, q, description, search) which are already in schema. This provides slight additional clarity but does not significantly augment schema information.

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

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

The description uses a specific verb ('Find') and resource ('tools'), immediately clarifying the tool's function. It distinguishes itself from sibling tools like 'search_datasets' by focusing on tool discovery rather than data retrieval. The explicit list of domains (SEC filings, FDA drugs, etc.) further clarifies 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 includes clear guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This indicates primary use case. While it doesn't explicitly state when not to use, the context implies this is for browsing, not direct query answering.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context: it fans out across multiple data sources, includes a note on patent API sunset (soft-fail), and lists returned 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 information-dense and starts with examples, but is somewhat verbose. Every sentence adds value, but it 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 covers the main return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and key caveats (patent sunset, name not supported). It mentions filing count limit (up to 5) and sorting, though some details like news count are omitted.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this with concrete examples ('AAPL', '0000320193') and reiterates the name constraint, adding marginal value beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples of user queries. It differentiates from siblings by explicitly preferring it over chaining single-pack lookups and mentioning resolve_entity for name inputs.

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 gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input constraints (only ticker or CIK, not names) and directs to use resolve_entity if only a name is available.

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 destructiveHint=true. The description adds 'clear sensitive data' context reinforcing the destructive nature. No contradiction. Slightly above baseline because it explains why you'd delete, not just that it deletes.

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

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

Two sentences with no filler. First sentence defines function, second provides usage guidance. Every word earns its place.

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 is simple (one parameter, no output schema). The description covers purpose, usage, and pairing with related tools. No gaps given the tool's complexity.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' is clear. The tool description doesn't add further meaning beyond that. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also references pairing with remember and recall for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds that it fetches external pages and extracts content, which is beyond annotations. No contradictions.

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

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

Two concise paragraphs. First paragraph describes functionality and output format. Second paragraph lists use cases. No unnecessary words, information is front-loaded.

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

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

With 2 parameters, no output schema, and rich annotations, the description fully covers what the tool does, its output format, and use cases. It is complete for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100%, and description adds context: explains url as 'Full URL of the site to summarize' with an example, and max_links with default (25) and max (50). This adds value beyond the schema definitions.

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

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

Description clearly states the tool generates a production-ready llms.txt file for a given URL. It specifies the verb 'generate', the resource 'llms.txt file', and details the process (fetches page, extracts data, emits markdown). It is distinct from sibling tools like ai_visibility_check or 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?

Description lists explicit use cases: getting a client's site indexed by AI, drafting llms.txt for own project, or auditing competitor's AI visibility. It does not explicitly mention when not to use or compare with alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: requires DOI, returns specific metadata fields, and is keyless. 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 sentences, front-loaded with purpose, no wasted 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?

Given simple tool (1 param, no output schema, rich annotations), description covers purpose, return fields, and keyless access. Could mention error handling or rate limits, but not essential for a read-only fetch.

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

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

Schema covers 100% of parameters with description. Description adds examples of DOI format (with and without prefix), which provides practical guidance beyond the schema's description.

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

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

Description uses specific verb 'Fetch' and resource 'single Dryad dataset by its DOI', clearly distinguishing from sibling tools like 'search_datasets' which would be for searching multiple datasets.

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

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

Description implies usage context (fetching a dataset by DOI) and mentions 'Keyless' indicating no authorization needed. However, it does not explicitly state when not to use or provide alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about returned fields, which is useful but not critical 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 concise, front-loads the action and return fields, and provides usage guidance in two compact sentences with no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers return fields and usage context, 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?

Parameter schema coverage is 100%, so the description does not need to elaborate further. It adds no extra meaning beyond the schema.

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

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

The description clearly states the action ('List the caller's active subscriptions') and specifies the returned fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit guidance on when to use the tool ('review what you're monitoring before adding more or to find an id to cancel'), but lacks explicit exclusion cases.

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

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

Discloses rate limiting (5 per identifier per day), that it is free and does not count against tool-call quota, and how feedback affects the roadmap. Annotations are all false, so the description carries the full burden and does so completely.

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

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

The description is concise and front-loaded with the main purpose, followed by usage conditions and constraints. Every sentence adds value, and there is 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 three parameters (one enum, one nested object), the description fully covers purpose, usage, constraints (rate limit, quota), and parameter guidance. No output schema is needed because the feedback submission likely returns a simple success status.

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 practical guidance: explains the 'type' enum with examples, suggests using specific tool/pack slugs for context, and specifies typical message length (1-2 sentences, 2000 chars max). This goes beyond the schema.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resources, and is distinct from sibling tools like 'ask_pipeworx' or 'discover_tools'.

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

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

Explicitly states when to use the tool (e.g., when a tool returns wrong data, when a desired tool is missing, or for praise) and provides context about not pasting user prompts. It also mentions the team digests feedback daily.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds data source (CF analytics engine), PII disclaimer, and caching behavior (5min-1h), which 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?

Front-loaded with core functionality, then use cases, then technical details. Every sentence adds value with no fluff.

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

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

With no output schema, the description explains return content (top tools, packs, call volume) but doesn't specify exact format. Context is sufficient for a simple tool with one parameter.

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 enum and description. Description adds usage guidance on window semantics (short vs long implications), enhancing understanding beyond schema.

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

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

The description clearly states it returns top tools, top packs, and call volume over a recent window. Specific verb 'returns' and resource differentiated from siblings like 'discover_tools' by focusing on trending usage.

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

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

Lists three explicit use cases and explains window choices (short for hot, long for steady). Does not explicitly state when not to use, but context is clear from sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds extensive behavioral context: scanning top ~200 markets, Jaccard similarity filtering, placeholder fraction filter, fill_check against CLOB depth. No contradictions with annotations.

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

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

Description is comprehensive and well-structured with clear sections for each mode. While slightly long, every sentence provides valuable information. Could benefit from bullet points for readability, but it appropriately front-loads the main usage pattern.

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

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

Despite no output schema, description fully explains output structure: opportunities[] with fields, partition_check, fill_check details (realizable_edge_pp). Covers edge cases like thin legs and placeholders. Provides all necessary context for an AI agent to use the tool effectively.

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

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

Schema description coverage is 100% (both parameters documented). Description adds significant value: explains event slug format, topic seed question example, and context for each mode. Goes beyond schema with examples and behavior details.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations + partition-sum checks. It distinguishes three modes (no args, event, topic) with specific examples, and contrasts with sibling tools by explaining uniqueness.

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

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

Explicitly provides when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes recommendations and mentions limitations (skipped_low_similarity, partition filter) and references sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral context: explains the three segments, caching (1h at KV level), diagnostics output, and warnings like when market movement exceeds edge. No contradiction with annotations.

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

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

The description is long but well-structured with bold headings for segments and diagnostic details. It front-loads the purpose and scope. While every sentence adds value, it could be slightly more concise without losing essential details. The length is justified given the tool's complexity.

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

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

No output schema exists, so the description must adequately explain return values. It does: details the top-level fields (by_segment, fed_candidates, _diagnostics), explains why segments may be empty, and covers all parameter effects. Caching behavior is also disclosed. This is comprehensive for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions. The description adds extra context beyond the schema, e.g., for min_liquidity it explains 'Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven.' This provides practical usage guidance that enriches the parameter meaning.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear use case ('what should I bet on today'). It distinguishes itself from siblings by specifying the tool's unique focus on edge detection from disagreement, though it doesn't explicitly name alternatives.

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

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

Provides explicit guidance on when to use: for discovering opportunities without paging hundreds of markets. Includes usage knobs like tradeable-edge filters, and indicates when to adjust parameters (e.g., slippage for thin partitions). Also mentions that Fed bets are excluded from ranking, guiding the agent on what to expect.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds value by detailing data source (daily snapshots), computation (edge_pp_net from daily closes), snapshot gaps, and TTL bounds. It does not contradict annotations.

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

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

The description is verbose, containing extensive details about response format and edge cases. While front-loaded with purpose, it could be more concise by using structured output or summarizing response fields.

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 (tracked, expired, snapshot_dates), behavioral nuances (decay from daily closes not intraday), and limitations (60-day TTL, gaps). It compensates well for missing structured 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% for both parameters. The description reiterates default values and clamp ranges for 'days' and default window family for 'window', but adds no new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering specific questions about edge age and trend. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical tracking rather than current edges.

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

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

The description gives clear context on when to use (edge lifecycle assessment) and provides a concrete example of why a wide edge age matters. However, it does not explicitly mention when not to use or name alternative tools beyond the implied contrast with polymarket_edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: it explains that in single-market mode it 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict' and in basket mode returns 'theoretical_sum vs realizable_sum, capture_ratio, profit_usd at executed size, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk'. It also warns about partial fills and unhedged directional risk. This goes well beyond annotation info.

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

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

The description is front-loaded with the core purpose, then uses clear section headers (SINGLE-MARKET, BASKET) and bullet-like lists of return fields. Every sentence adds value, though it is somewhat lengthy. Could be slightly more condensed, but structure is effective for a complex tool.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains both modes, parameter defaults, return values, and critical risk notes (unhedged directional positions). It covers all necessary information for correct invocation.

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

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

Schema description coverage is 100%, so baseline 3. The description adds meaning beyond the schema: it explains that `market` is for single-market mode and `event` for basket mode, that `side` defaults to auto based on partition sum for basket, and that `size_usd` is interpreted as settlement notional for basket (shares per leg). This enriches the parameters with usage context.

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

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

The description states: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly differentiates from siblings polymarket_arbitrage and polymarket_edges by specifying when to use this tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'). The verb 'check' and resource 'edge' are specific and non-tautological.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why: 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode)'. This gives clear context on when to use and the risks of not using it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond by explaining safety fields (compatibility_warning, temporal_alignment, skipped counters), the meaning of various conditions (shape mismatch, temporal gap), and the reality that most pre-mapped topics are not tradeable. 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 relatively long but every sentence adds value: mode explanation, response structure, safety fields, and caveats. It is front-loaded with a concise one-line summary. Could potentially be slightly more concise (e.g., some repetition about compatibility warnings), but structure and clarity are strong.

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 3 parameters, no output schema, and rich annotations, the description covers all aspects: input modes with examples, response format (leg-by-leg prices, spread array, safety fields), and important caveats (temporal alignment, shape mismatch, warning conditions). It is fully complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description adds higher-level context: topic is a pre-mapped shortcut with explicit enumerated values, while the other two parameters are overrides that work together. This goes beyond the schema's property descriptions by explaining the mode logic and interaction, justifying a 4.

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

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

The description immediately states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' which is a specific verb+resource combination. It also distinguishes from siblings like 'polymarket_arbitrage' by focusing on cross-venue spreads and warning that many pre-mapped topics are not tradeable.

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 clearly explains two modes (topic shortcuts vs explicit tickers) and provides examples. It warns that many topics return compatibility warnings, implying when the tool may not be useful. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or bet_research, though context from sibling names implies differentiation.

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. Description adds scoping detail ('Scoped to your identifier...'), which is useful context beyond annotations. No contradiction.

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

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

Three sentences, front-loaded with core action, 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 read-only tool with one optional parameter and no output schema, the description covers all needed context: behavior with and without key, scoping, and relationship to sibling tools.

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

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

Schema coverage is 100% with a clear description for the parameter. Description adds context about retrieving a value vs listing keys, and pairs with other tools, enhancing understanding beyond the schema.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list) and resource (saved values), and distinguishes itself from sibling tools remember and forget.

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

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

Explicitly says when to use: 'to look up context the agent stored earlier' and implies when not to use by referencing alternatives: 'Pair with remember to save, forget to delete.' Also mentions scoping to identifier.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: returns specific fields, mark_read flags events as read, and polling is supported. No contradictions; adds 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?

Four well-structured sentences, front-loaded with the main purpose, then specific details about fields and parameters. No unnecessary words; each sentence serves a purpose.

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

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

With 5 optional parameters and no output schema, the description covers all essential aspects: what is returned, how to filter, the effect of mark_read, and alternative access. It provides complete context for using the tool effectively.

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

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

Schema coverage is 100% with descriptions, but the tool description provides additional context: example filter values ('sec_8k'), clarifies ISO timestamp for since, and explains the effect of mark_read. This extra information enhances understanding beyond schema.

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

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

The description clearly states the action ('pull fired events from your subscription feed'), specifies the resource ('subscription feed'), and lists key fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions and subscribe.

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 guidance on filtering by type and since, setting mark_read for behavior, and notes that polling works. Mentions an alternative access method (direct URL) for scripts. Does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds operational details: fans out to multiple sources, fallback logic, USPTO soft-fail until reactivated, and return structure (changes grouped by source, total_changes, 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 front-loaded with example queries, well-structured into purpose, sources, parameters, and alternatives. 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?

Despite no output schema, the description fully explains the return shape (changes grouped by source, total_changes, citation URIs). It covers multiple sources, fallback, date formats, and alternative tool. Complete for an agent to use correctly.

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

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

Schema has 100% coverage of parameter descriptions. The description adds usage context beyond schema, e.g., typical monitoring period '30d' or '1m', relative shorthand examples, and ticker/CIK flexibility. Not a full 5 because schema already does significant work.

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 serves 'What's new' queries for a company within a time window, lists specific sources (SEC, GDELT/GNews, USPTO), and distinguishes from the sibling entity_profile by noting it provides dynamic change feed vs static profile.

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

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

Explicitly gives when-to-use examples ('what's new with X'), explains fallback behavior (GDELT preferred, GNews on rate limit/5xx), and directs to use entity_profile for static profiles. 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?

Annotations declare idempotentHint=true, consistent with overwriting same key. Description adds crucial context: key-value scoped by identifier, persistence for authenticated users vs 24h for anonymous. 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?

Single focused paragraph with clear front-loading of purpose. Every sentence adds value: purpose, usage, scope, persistence, pairing. No redundant or irrelevant content.

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 with 2 parameters, the description fully covers purpose, usage, persistence behavior, and relationship with sibling tools. No output schema needed. Complete guidance for an agent to use correctly.

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

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

Schema already fully describes both parameters (key, value) with 100% coverage. Description adds example key names (e.g., 'subject_property') and clarifies value can be any text, but does not significantly extend beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states purpose: 'Save data the agent will need to reuse later' and distinguishes from sibling tools recall and forget by mentioning pairing with them. Gives concrete examples of what to store (ticker, address, preference).

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides examples. Mentions persistence behavior and pairing with recall/forget. Could be more explicit about when not to use, but adequate for this tool.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining internal cascading through multiple lookup endpoints and the specific return values (ticker, CIK, company_name, RxCUI, etc.), which goes beyond the annotations.

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

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

The description is a compact paragraph that efficiently conveys all necessary information. It is front-loaded with user-facing questions, followed by guidance and details. It is concise without being overly terse, though some structuring could improve readability.

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

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

Despite lacking an output schema, the description provides complete context: when to use, parameter details, and return values including citation URIs. It covers both entity types thoroughly and explains the tool's complex internal behavior, making it fully self-sufficient for an AI agent.

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

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

Schema coverage is 100%, but the description adds meaning by explaining accepted input formats for each type, such as 'ticker (AAPL), CIK (0000320193), or name' for company, and giving explicit examples like 'ozempic' and 'metformin' for drug. It also details the return structure for each type.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical identifier. It provides specific examples like 'What's the ticker for...' and 'find the CIK for...', and distinguishes it as the first tool to use when needing an ID, differentiating it from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use the tool. It lists supported entity types and input formats, though it does not explicitly exclude alternatives or describe when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by explaining the internal behavior: it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It also describes output fields (score, confidence, 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 concise with four sentences, each earning its place: first states the core action, second explains the mechanism, third gives a use case example, fourth specifies the output format. It is front-loaded and wastes no 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 no output schema, so the description must explain return values, which it does ('ranked list with score, confidence, signal density per entity'). It also covers parameter semantics (entities required, first as subject) and the overall workflow. Given the moderate complexity (4 parameters, 1 required), the description is sufficiently complete for an agent to invoke correctly.

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

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

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it notes that the first entity is treated as the subject, but that is already implied by the parameter order. The schema descriptions are adequate on their own.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using probes from ai_visibility_check and returning a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more generic, not AI-specific). The verb 'compare' and resource 'AI visibility' are specific and unambiguous.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query. It implies that ai_visibility_check is the underlying mechanism, suggesting single-entity checks could use that sibling, but it does not explicitly state when not to use this tool or list alternative tools. The context is clear enough to guide appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds critical details: fans out to multiple sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeout sources. No contradiction.

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

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

Description is dense and front-loaded with purpose, but slightly wordy. However, every sentence adds necessary detail, so it earns its 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 complexity (multiple sources, partial failures, timeouts) and no output schema, the description thoroughly explains return fields (summary block, advisories, links, alternative versions) and error handling. Very 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%, description adds extra context: version defaults to latest, scoped packages accepted. This exceeds baseline expectations.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings by specifying the exact use case and ecosystem scope.

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

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

Explicitly provides use cases ('is X safe/popular/small', 'what does adding lodash cost'), and caveats for other ecosystems (PyPI, Maven, etc. should use deps.dev directly). This guides correct 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, covering safety. The description adds value by stating 'Keyless' (no authentication required) and detailing the return fields (DOI, title, authors, truncated abstract, etc.), which is critical since there is no output schema. 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 four sentences, each serving a purpose: introducing Dryad, explaining search scope, listing return fields, and stating keyless access. It is front-loaded with the main action 'Search Dryad' and contains no redundant or 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?

Given no output schema, the description compensates by listing the return fields. It covers the repository context, searchable fields, and authentication. It does not mention ordering or result count limits beyond the page/limit parameters, which are in the schema. For a straightforward search tool, this is adequate but not exhaustive.

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 meaning by specifying that the query searches titles, abstracts, authors, and keywords, and mentions 'Keyless' which does not relate to parameters but provides context. The parameter descriptions in the schema are already clear, so the description offers marginal but useful extra detail.

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 Dryad, a specific repository of research datasets. It distinguishes from siblings like get_dataset, which retrieves a single dataset, and search_within, which likely narrows search within datasets. The verb 'Search' combined with the resource 'Dryad' and the detailed scope of full-text query over titles, abstracts, authors, and keywords provides a precise 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: it is for searching Dryad datasets via text query. It does not explicitly state when not to use it or suggest alternatives like get_dataset for specific DOIs, but the sibling tool list and the description's specificity make the intended usage evident. The mention of 'Keyless' also indicates no authentication barrier.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: truncation at 200K chars with a flag, embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), output details (passages with offsets and scores). 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 well-structured and front-loaded with the core action. Every sentence adds value: what, when, how, pairing, technical details. There is no fluff or repetition.

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 (semantic search, embeddings, offset verification, truncation) and lack of output schema, the description covers all necessary aspects: input, output format, limits, technical implementation, and pairing guidance. No critical information is missing.

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

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

Schema coverage is 100% (all parameters described). The description adds meaningful extra context: explains text is 'the document text' with max 200K chars, query is natural-language with examples, limit has default 5 and range 1-20, and describes the output structure (top-N passages with offsets and scores). This goes beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using a specific verb ('search') and resource ('text inside a record'). It provides examples (e.g., SEC 10-K body) and distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with using the whole document.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. It implies when not to use (small documents) but does not explicitly state alternatives; however, the context is clear enough for an agent.

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

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

The description contradicts the idempotentHint=true annotation by stating 'Create... Returns the new subscription id', implying each call creates a new subscription, which is not idempotent. This is a serious inconsistency. Additionally, it provides useful behavioral details like rate limits and webhook auto-disable, which adds context beyond annotations.

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

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

The description is front-loaded with the core purpose and then details types and delivery options. While long, it is well-structured and each sentence contributes meaningful information without redundancy.

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

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

The description thoroughly covers prerequisites, supported types with parameter details, delivery channels with constraints, and return value. It addresses all relevant aspects given the tool's complexity and lack of output schema.

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

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

Schema coverage is 100%, but the description adds significant value by providing concrete examples and clarifying required fields for each subscription type and delivery channel constraints, going beyond the schema's brief descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription, specifies the verb 'Create', the resource 'proactive monitoring subscription', and indicates it returns a subscription ID. It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by describing what it does uniquely.

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 on when to use the tool, including prerequisites (Pipeworx OAuth account) and exclusive constraints (anonymous + BYO cannot persist). It lists supported subscription types with examples, but doesn't explicitly mention when not to use it or alternative tools for monitoring.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it returns example questions drawn from a live catalog, and it serves as an onboarding entry point. 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 well-structured with front-loaded use cases. Every sentence serves a purpose, but it is somewhat verbose. It could be slightly more concise, but overall it efficiently conveys the needed information.

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

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

Given the tool has one optional parameter, no output schema, and many siblings, the description is complete: it explains what it returns, how to use it, and when to use it. It could detail the output structure more, but the information provided is sufficient 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?

The parameter 'topic' has schema coverage of 100% with a description. The description further elaborates by listing the allowed values (finance, pharma, etc.) and explaining the behavior when omitted ('for a cross-category spread'), adding significant 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 natural language queries that clearly state the tool's purpose as an onboarding entry point. It specifies that it returns category-bucketed example questions with exact tool and argument shapes, and explicitly distinguishes it from siblings by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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 usage guidance: call with no arguments for full spread or pass a topic to focus. It explicitly states the tool should be used first when the agent doesn't know what Pipeworx can do. However, it does not explicitly mention when not to use it or compare with specific alternatives, though the context implies 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 significant value beyond annotations: it clarifies that the subscription is deactivated (not deleted) and that historical events remain available. This complements the idempotentHint=true and destructiveHint=false annotations without contradiction.

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

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

Three sentences with no wasted words. The primary action is front-loaded, followed by constraints and side effects.

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 tool with annotations and no output schema, the description covers purpose, constraint, and effect. It could mention what happens if the id is invalid, but overall it is adequate.

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

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

Schema coverage is 100% and already describes the 'id' parameter as a subscription uuid. The description adds no new parameter-level detail beyond referencing it by id.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the effect (deactivation not deletion) and the ownership constraint.

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

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

Ownership enforcement is explicitly stated, telling agents they can only cancel their own subscriptions. However, no explicit alternative tool is provided, though it's implied by the sibling list.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds detailed behavioral context: the return verdicts (confirmed, refuted, etc.), extracted structured form, actual value with citation, and percent delta. 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 structured and front-loaded with trigger examples, then scope, then outputs. It is reasonably concise given the amount of information conveyed; each sentence adds value.

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

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

Given the lack of an output schema, the description explains the return verdicts and structure. It covers the domain, data source, and examples. Some limitations (e.g., non-US companies) are implied but not exhaustive, but overall it is 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?

The single parameter 'claim' has a schema description with examples, and the tool description adds meaning by specifying the supported claim types (company-financial) and the data source. Schema coverage is 100%, so the description adds extra context beyond the minimal.

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 about company financials using SEC EDGAR+XBRL. It provides specific verb+resource and distinguishes from siblings by noting it replaces multiple 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims for public US companies). It does not explicitly list when not to use or alternatives among siblings, but the context is clear.

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