Openaire

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: default free model, optional paid Anthropic probing, per-model response structure, and cost implications ('you pay Anthropic directly'). 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 three sentences with no wasted words. It front-loads the core purpose and then efficiently adds details about models, cost, and return structure. Every sentence 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?

Given no output schema, the description specifies the return format (per-model {score, confidence, signals, raw_response} + combined view). All parameters are fully documented with examples. Annotations cover safety. The description is complete for an agent to understand and invoke the tool correctly.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds meaning beyond schema by explaining default model, free/paid distinction, and context disambiguation use, enriching the agent's understanding of each parameter's purpose.

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 probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It distinguishes from sibling tools by specifying its unique function for AI-marketing audits, brand checks, and competitive monitoring.

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 contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly list when not to use or compare with alternatives like sibling tools. However, the context is sufficient for an agent to infer appropriate scenarios.

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

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

Annotations already cover read-only, open-world, and idempotent behavior, so the description adds value by stating it routes to one of 5,596 tools across 1,465 sources, fills arguments automatically, and returns stable pipeworx:// citation URIs. This exposes routing and output behavior that annotations do not convey, though it does not discuss potential failure modes or cost.

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 front-loaded with the most actionable advice, including when to prefer it, the accepted question types, and concrete examples. It includes alternative alternatives near the end, which is helpful even though a single concluding list could be slightly shorter.

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 single-parameter interface and the absence of an output schema, the description covers the essential context: what kind of questions are accepted, the scope of data sources, and what the return value will include (structured answer plus stable citation URIs). It is sufficiently complete for an agent to select and call the tool safely.

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

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

There is a 100% schema description coverage for all six parameters: the schema already documents the primary 'question' parameter and five aliases. The description adds useful query examples and states that natural-language questions are accepted, but it does not need to add much because all parameter semantics are already well-described in 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 states a specific verb and resource: it routes a natural-language question to an authoritative data source and returns a structured answer. It clearly distinguishes itself from generic web search and sibling tools such as deep_research and entity_profile by citing concrete examples like 'Apple's latest 10-K' and 'current US unemployment rate.'

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 'PREFER OVER WEB SEARCH', then gives trigger phrases such as 'what is', 'look up', 'find', and provides examples. It also gives exclusion guidance: use entity_profile for single facts on stored entities, and deep_research for large multi-faceted research, so an agent has concrete when-to-use and when-not-to-use direction.

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

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

Annotations already cover the safety profile (readOnlyHint: true, idempotentHint: true, destructiveHint: false). On top of that, the description adds genuinely useful behavior beyond the annotations: it discloses live-state variability while candidates are under test, the current 'no candidate active' state with a retirement date, that it is a full working router with no fallback, and the comparison mechanism against the stable router. 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?

Four sentences, each earning its place — identity, live-testing behavior, direct instructions, and the no-fallback clarification. There is minor redundancy between 'same arguments, same response shape' and 'this currently matches ask_pipeworx exactly' rather than fluff, so it stays efficient.

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

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

No output schema exists, but the description covers the return shape via 'same response shape'. The single shared 6-parameter contract is fully documented and the tool's unusual beta semantics are thoroughly explained. Residual gaps like error/pagination behavior, since the exact intent is to be identical to a stable router, are acceptable.

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% — all six parameters are clearly documented aliases of question, so the schema already carries full semantic weight. The description points to the tool's arguments being identical to ask_pipeworx, but adds no format, syntax, or aliasing detail beyond what the schema provides.

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

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

The description identifies the tool as specific: 'Beta version of ask_pipeworx: identical universal router (same 5,596 tools, same arguments, same response shape)' — a unique verb+resource combination. It differentiates itself from its siblings by framing itself as the experimental edge version of the stable router ask_pipeworx.

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?

States an explicit usage directive — 'Use it exactly like ask_pipeworx when you want the newest routing' — and explains results are compared against the stable router. However, it does not name when-not-to-use conditions or point to preferred alternatives (e.g., stable or grounded variants), so exclusionary guidance is absent.

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?

With no output schema, the description fully discloses the return shape: success returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and failure returns explicit refusal reasons like not_in_source, no_tool_match, tool_error, data_truncated and llm_error. It also explains the extraction constraint (only what the tool result contains) and the extra LLM call, all of which is behavior not visible from 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 compact despite covering return format, refusal semantics, when-to-use, alternatives, and cost tradeoffs. Each clause adds distinct information: the routing, the extraction rule, the payload shape, the refusal cases, the high-stakes use cases, and the comparison with ask_pipeworx.

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 read-oriented tool with one natural-language question parameter and significant behavioral nuance, the description fully captures both invocation semantics and answer guarantees. It covers fallback refusal paths and cost implications, so an agent has all the information needed to decide when and why to call this variant.

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

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

The schema already provides 100% description coverage for the six parameters, including the accepted aliases for the question input. The tool description does not add any parameter-specific meaning beyond 'ask in natural language', which the schema already conveys, so the baseline 3 is appropriate.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' and states the action: it routes to the appropriate tool, fetches data, and extracts an answer only from source content. It distinguishes itself from ask_pipeworx and ask_pipeworx_beta by emphasizing groundedness and refusal behavior.

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

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

It explicitly states when to use this mode: when an answer will be quoted, cited, or acted on, especially in high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also provides the opposite recommendation: prefer ask_pipeworx for casual lookups, and notes the extra LLM call cost.

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

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

The description extensively discloses behaviors beyond annotations, including the resolver contract, parent event extraction, news fallback, safety mechanisms, wide-spread handling, and cancellation rules. This far exceeds the information provided by annotations, giving the agent a complete understanding of tool behavior.

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

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

The description is very detailed and structured with sections, but it is lengthy (multiple paragraphs). While every sentence adds value, it could be more concise without losing essential information. The first sentence is clear, but the density may overwhelm.

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 (3 parameters, no output schema), the description covers response shapes, evidence sources, resolver contract, parent event, news fields, safety, and cancellation rules thoroughly. It addresses edge cases and provides complete guidance 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%, meeting the baseline. The description adds meaningful context for each parameter: market accepts slug/URL/text, depth has enum with defaults, include_raw explains data sizes and use cases. This enriches understanding beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific use cases and input examples. However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edges, leaving some ambiguity about when to use this tool over 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?

The description provides explicit use cases (e.g., 'should I bet on X') but lacks guidance on when not to use this tool or mention of alternative tools. The user must infer usage boundaries from 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 declare safety (readOnlyHint, idempotentHint), description adds data sources, sorting behavior, and citation URIs. No contradiction; useful context beyond annotations.

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

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

Front-loaded with examples, efficient use of space, each sentence adds value. Minor redundancy (repeats '2–5') but overall well-structured and concise.

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

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

Covers purpose, usage, data sources, sorting, and output format. Lacks explicit response structure, but sufficient given no output schema and good annotations.

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

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

Schema covers parameters, description adds meaning by explaining data retrieval differences per type and providing concrete examples for values, enhancing agent understanding.

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

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

Description clearly states verb 'compare' and resource 'entities', specifies scope (2–5 companies/drugs), and distinguishes from sequential single-entity lookups, leveraging sibling context.

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

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

Explicitly prefers this tool over sequential lookups with example query patterns. Lacks exclusion criteria for when to use alternatives like entity_profile, but strong guidance within its scope.

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

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

The description discloses far more than the annotations: it explains the facet decomposition, parallel routing, gaps[] for unanswered facets, contradictions[] on standard/thorough, fetchable citation_uri, semantic excerpting rather than head-truncation, and expected latency. This goes well beyond the schema and annotations and sets accurate expectations for a read-only tool.

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

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

The description is long but appropriately dense, and every block adds decision or behavior information: auth, scope, alternatives, output packet, latency, and citation behavior. It front-loads the most critical constraints — account required and NOT open-web — before the detailed behavioral explanation.

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 two-parameter research tool with no output schema, the description is remarkably complete: it names the required auth scenario, when to pick a sibling, the returned fields, citation semantics, gaps/contradictions behavior, result size and latency. An agent can decide to call it and interpret the response without additional inference.

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

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

The schema already documents depth quickly and thoroughly, but the description adds practical meaning: quick standard/thorough behavior, paid inter additionally chases leads and recovers gaps, contradictions[] appear under standard/thorough, and broad/multi-part questions are valid because decomposition is a core behavior. This is value beyond the schema, not repetition.

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 identifies what the tool does: grounded multi-source research over structured data sources in one call, explicitly described as 'NOT open-web search.' It also carves out a distinct role relative to ask_pipeworx, so an agent can tell them apart without needing to inspect schemas.

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?

It gives concrete when-to-use and when-not-to-use guidance: use deep_research for broad/multi-part structured-data questions, and use ask_pipeworx for single lookups, breaking/colloquial current-news topics, and free-tier users who are not signed in. It also names account and paid-plan prerequisites, so the agent can route correctly before calling.

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, idempotentHint true, and destructiveHint false, which the description aligns with by describing a read-only discovery operation. The description adds behavioral context: returns top-N tools with full schemas and examples, ready to call, and no second lookup needed. No contradictions.

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

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

The description is front-loaded with purpose and usage, and is reasonably concise. It lists many domain examples, which add length but also context. The structure is logical: purpose, when to use, what it returns, and a call to action.

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 6 parameters (1 required), no output schema, and read-only annotations, the description covers when to use, what the tool returns (top-N tools with schemas and examples), and that results are directly callable. It does not mention pagination or rate limits, but these are not critical for the tool's purpose.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant new meaning beyond the schema, except for providing examples and explaining that query accepts aliases (which are already in the schema). It states the query should be a 'natural language description,' which is helpful but not novel.

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 identifies the tool as a tool discovery function using verbs like 'find', 'browse', 'search', 'look up', and explicitly lists many domains (SEC filings, financials, FDA drugs, etc.). It distinguishes from sibling tools by stating it returns tool schemas, not data, and should be called first to see the option set.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context, though it does not explicitly mention when not to use 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?

Beyond annotations (readOnly, idempotent, etc.), description details data sources, return fields, and important behaviors like the USPTO PatentsView API sunset May 2025 and GDELT→GNews fallback, adding significant value.

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

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

Description is a single, dense paragraph but front-loads purpose with examples. Every sentence adds value, though slightly longer than ideal. Could benefit from bullet points for readability.

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

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

Despite no output schema, description thoroughly explains return structure (cik, filings, fundamentals, patents, news, LEI) and even includes URIs and field specifics, making it complete for agent usage.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples and reiterates constraints (e.g., only ticker/CIK, names not supported). Does not introduce new semantics beyond the schema.

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

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

Description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call,' supported by numerous example queries. It distinguishes itself from sibling tools like compare_entities and resolve_entity by specifying its 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 states to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed, and advises using resolve_entity first if only a name is available, providing clear when-to-use and when-to-avoid guidance.

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

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

Annotations already declare destructiveHint=true (mutation) and idempotentHint=true. Description adds context about clearing sensitive data and pairs well, but does not contradict annotations. Adds moderate value beyond structured fields.

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 zero waste: first sentence states purpose, second provides usage guidance. Front-loaded and efficient.

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

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

For a simple tool with one required parameter and comprehensive annotations, the description is complete. It covers purpose, usage timing, and related tools, leaving no gaps.

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

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

Schema coverage is 100% and includes a description for the 'key' parameter. Description does not add additional parameter semantics beyond what the schema provides, meeting baseline.

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

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

Description clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific. It distinguishes from sibling tools 'remember' and 'recall' by being the deletion counterpart.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also directs to pair with 'remember' and 'recall,' providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like fetching page, extracting title/description/key links, and outputting markdown, which is consistent and 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 informative and front-loaded with the main action, but slightly verbose. It could be more concise while retaining key points.

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

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

Given the annotations and schema, the description is sufficiently complete for a simple read-only tool. It explains input, action, and output format without needing an 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 description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for parameters (url, max_links), though it mentions defaults and limits already in schema.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check which focuses on visibility analysis.

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

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

The description provides explicit use cases (client indexing, own project drafting, competitor auditing) but does not mention when not to use or alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about what the tool returns (budget breakdown, partner list, outputs), which is beyond the annotations. No contradictions.

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

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

The description is one sentence, around 20 words, and efficiently conveys the purpose and usage context. It is front-loaded with the core action and identifier, with no 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 the tool has one parameter, comprehensive annotations, and an output schema, the description adds enough context about what additional details are provided. It is complete for this simple fetch operation.

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% for the single parameter 'id', with description 'OpenAIRE id'. The description does not add additional semantic detail beyond what the schema provides, so a 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 the action ('Fetch'), the resource ('funded research project'), and the identifier ('by OpenAIRE ID'). It also distinguishes from siblings by mentioning 'use after search_projects', which differentiates it from other tools.

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

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

The description explicitly says 'use after search_projects for full project details', providing clear context on when to use this tool. It does not explicitly state when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read. The description adds that it returns the full record and requires an OpenAIRE ID, which is valuable 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?

A single sentence that conveys all necessary information without verbosity. It could be split for readability, but it remains clear and efficient.

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

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

For a simple tool with one parameter, an output schema, and rich annotations, the description is fully adequate. It explains the purpose, usage sequence, and what to expect (full record).

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 'id' is well-described with an example. The description does not add new semantic details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly specifies the verb 'Fetch', the resource 'single research product', and lists the product types (publication/dataset/software). It also distinguishes itself from sibling search tools by stating it is used after search to get the full record.

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 after search_publications / search_datasets / search_software to get the full record', providing clear context for when to invoke this tool versus searching. It does not list negative cases but adequately guides the 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 provide readOnly, idempotent, non-destructive hints. Description adds return fields but no new behavioral context beyond what annotations convey.

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 and return fields, 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 list tool with strong annotations, the description adequately covers return fields and usage context. No output schema but sufficient for task.

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 describes the boolean parameter. Description mentions 'active subscriptions' implying default behavior, but adds little beyond schema's parameter 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?

Clearly states it lists the caller's active subscriptions, specifies return fields (id, type, etc.), and distinguishes from sibling tools like subscribe/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?

Explicitly says 'use this to review what you're monitoring before adding more or to find an id to cancel', providing context for when to use it, though it does not name alternative tools explicitly.

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?

With all annotations set to false, the description carries full responsibility for behavioral disclosure. It goes beyond the schema by revealing rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the token lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed'). No annotation contradiction is present.

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 structured into clear logical segments: purpose, when-to-use, exclusions, token flow, and rate limit. Though longer than average, every sentence adds value and addresses a distinct aspect (usage, boundaries, mechanics, cost). No fluff or repetition exists; the length is justified by 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?

Given the tool's moderate complexity (4 optional params, nested object, token-based follow-up) and the absence of an output schema, the description adequately explains the return behavior ('returns a claim_token', 'read whether it was fixed and what changed') and the practical workflow. It also covers edge cases like account-less filing and exclusions for non-Pipeworx tools. The description is fully self-sufficient for an agent to invoke the tool correctly.

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

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

The schema covers 100% of parameters with descriptions, earning a baseline of 3. The description adds extra semantic context beyond the schema, especially for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'). This added guidance meaningfully helps the agent use the parameters correctly.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings by explicitly limiting usage to 'tools served by this Pipeworx connection' and excluding tools from other MCP servers, which none of the sibling descriptions mention. The verb 'tell' plus the resource 'Pipeworx team' makes the action concrete and differentiated.

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

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

The description provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use rule: 'if the tool came from a different MCP server in your client... file it with that server instead.' This is textbook usage guidance with exclusions and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradictions.

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

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

Three sentences, each serving a purpose: what it does, use cases, and behavioral notes. Front-loaded with main result. No unnecessary words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what is returned (tools, packs, call volume), data source, and caching. No gaps.

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

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

Schema coverage is 100% with one parameter 'window' documented via enum and description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, distinguishing it from siblings like discover_tools. It uses specific verb 'Returns' and defines the resource (trending data).

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case). It does not provide when-not-to-use or alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: monotonicity checks, partition-sum logic, semantic anchor for similarity, partition filter for placeholders, and fill check against live CLOB depth. No contradictions.

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

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

The description is fairly long but front-loads the core purpose and then systematically covers each mode. Every sentence adds value, but some sections (e.g., fill check) could be slightly more concise. Still efficient for the complexity.

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

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

Given the tool's complexity (no output schema), the description covers input parameters, behavioral nuances, return value structure, edge cases (cross-event mode, partition filters), and fallback/usage guidance. It is thorough and leaves minimal gaps.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema. It explains each parameter's purpose, provides example values, and details the behavior of each mode, including how event and topic parameters are processed.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for a specific event, and topic for cross-event scans. This specificity differentiates it from sibling tools like polymarket_edges and polymarket_edge_tracker.

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

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

The description explicitly tells when to use each mode, including recommending event mode for specific markets and topic mode for cross-event patterns. It also warns when not to trade via the fill check section and directs to 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 declare readOnly, idempotent, openWorld, and non-destructive. The description adds extensive behavioral details: caching (1h at KV level), internal model families, edge computation (edge_pp_net, kelly), and response structure with diagnostics. No contradictions; the description significantly enhances transparency beyond annotations.

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

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

The description is very dense and contains extensive detail, which is justified by the tool's complexity. However, it could be more structured (e.g., using sections) to aid readability. It is not overly verbose but could be more concise in presenting the three segments and knobs.

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

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

Given no output schema, the description thoroughly explains the return structure (by_segment with three groups, Fed candidates, diagnostics). It covers edge cases like Fed bets, caching, and filter skips. The tool has 9 parameters and complex internals, and the description provides comprehensive context for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add much parameter guidance beyond what the schema provides; it briefly mentions category_filter segments but otherwise relies on schema descriptions. The description adds minimal marginal value for parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today.' It details three distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from generic market scanners. The purpose is specific and actionable.

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

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

The description implies usage for discovering betting opportunities without paging, but it does not explicitly state when not to use this tool or provide alternatives like polymarket_arbitrage or polymarket_edge_tracker. It lacks explicit exclusion criteria, leaving the agent to infer usage context.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds substantial behavioral details: it reads from daily snapshots, returns time-series, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot_dates with gaps explained. Limitations about history depth and intraday data are disclosed. 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, starting with the core question, then detailing response fields, and ending with limitations. It is about 100 words, which is concise given the complexity. Every sentence adds value, though some repetition with schema descriptions could be trimmed. Front-loaded with the key purpose.

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

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

For a tool with no output schema, the description provides comprehensive coverage: it explains all three response arrays (tracked, expired, snapshot_dates) with field meanings, edge cases (signed edge_pp_net, negative = SELL YES, median lifespan as competition clock), and limitations (60-day TTL, no intraday). The tool is complex, but the description makes it clear what to expect.

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

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

Schema coverage is 100% for two parameters, and the schema descriptions are already clear (lookback defaults and clamp, window family options). The description repeats this information without adding new parameter-level details. Although the response structure description indirectly helps, it doesn't enhance parameter semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: telemetry on edge persistence and decay from daily snapshots. It contrasts fresh vs. old edges, and the response structure details what is returned. The name and title align with the described functionality, and it distinguishes itself from related tools like polymarket_edges (which likely provides current edges) by focusing on historical tracking.

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

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

The description explains when to use the tool (to check edge history and decay) and contrasts a fresh vs. 3-week-old edge. It mentions limitations (60-day TTL, daily closes only) that guide appropriate use. However, it does not explicitly mention alternatives or scenarios where other tools might be more suitable, e.g., using polymarket_edges for current edges. Sibling tools include polymarket_edges, so the context is implied but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, consistent with a read-only risk check. The description adds rich behavioral detail: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and warns about thin books and partial fills. 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 bolded mode headers (SINGLE-MARKET, BASKET) and bullet-style listing of return fields. It front-loads the core purpose. However, it is somewhat lengthy and dense; some sentences could be streamlined for efficiency. Still, given the tool's complexity, the structure is effective.

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

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

With no output schema, the description fully explains return values for both modes, covering fields, their meanings, and implications (e.g., forced_directional_risk). It also addresses edge cases (thin books, partial fills, directional exposure risk). The tool's 4 parameters and complex behavior are comprehensively described.

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

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

Schema description coverage is 100%, baseline 3. The description adds meaning beyond the schema: explains that size_usd for basket is 'settlement notional — shares per leg', side defaults are auto-detected based on partition sum, and clarifies mutual exclusivity of market and event parameters. This extra context justifies a score of 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market and basket) and lists specific return fields, making its function unambiguous and differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage 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 not capturable, partial fills convert arb to directional), and mentions alternatives implicitly by naming the sibling tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes far beyond by detailing compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment field, skipped_cross_type/subtype counters, and the real meaning of spreads versus 'pre-mapped'. 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 relatively long but every sentence carries useful information. It front-loads the core purpose and then details modes and safety fields. Could be slightly more structured, but conciseness is adequate given the complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields). It covers edge cases (compatibility warnings, temporal misalignment, skipped comparisons) that are critical for a cross-venue spread tool, making it fully contextual.

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

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

Schema coverage is 100% with good property descriptions. The description adds value by enumerating the 10 topic shortcuts and explaining how explicit tickers override the mapped side. This extra context enriches the schema beyond the basic descriptions.

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', specifying the verb (compute spread), resource (questions on two venues), and distinguishes it from siblings like polymarket_arbitrage. The two modes (topic shortcuts vs explicit tickers) are explicitly outlined.

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

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

The description provides clear context for when to use each mode (topic for pre-mapped shortcuts, explicit tickers for custom pairings) and warns that most pre-mapped topics return compatibility_warning, indicating they are not tradeable. However, it lacks explicit guidance on when not to use the tool or alternatives beyond the implied sibling 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, idempotentHint, destructiveHint. Description adds 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)', providing isolation 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?

Four sentence description is concise, front-loaded with main action, and provides examples and scope without unnecessary words.

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

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

For a simple retrieval tool with one optional param and annotations covering safety, the description sufficiently explains purpose, use cases, and scope. No output schema needed.

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

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

Input schema already provides 100% coverage with a clear description for the single optional parameter. Description reinforces the schema's meaning but does not add new detail 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', providing a specific verb+resource. It distinguishes from siblings (remember, forget) by including pairing guidance.

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 to look up context the agent stored earlier' and gives concrete examples (ticker, address, notes). It also mentions scope (identifier-based) and pairing with remember/forget, but does not explicitly state when not to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds critical behavior: setting mark_read:true flags returned events as read so subsequent calls only show newer ones. This adds value beyond the annotations without contradiction.

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

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

Every sentence serves a purpose. The description is well-structured, starting with the core function, then return details, filtering options, important behavior (mark_read), and alternative access. No filler.

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

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

Despite no output schema, the description clearly states return fields. It covers all 5 optional parameters, explains key behavior (mark_read), and even mentions a direct URL for scripts/dashboards. The tool is simple enough that this description is complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds semantic context by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and the purpose of filters (e.g., type as 'sec_8k').

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying return fields (source, citation_uri, raw payload). It is specific enough to distinguish from siblings like 'list_subscriptions' but does not explicitly contrast with any sibling tool.

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

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

Provides guidance on filtering by type and since, and setting mark_read. Mentions polling is acceptable and notes an alternative direct GET endpoint for scripts/dashboards. However, does not explicitly say when not to use this tool or compare to siblings.

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

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

Description adds significant behavioral context beyond annotations: it fans out to multiple sources, details fallback logic, notes soft-failure for USPTO due to API sunset, and describes the return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense and front-loaded with example queries; every sentence adds value. Slightly more structured formatting could improve readability, but overall it is concise for the amount of information conveyed.

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

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

Given no output schema, the description adequately explains the return structure (changes grouped by source, total_changes, citation URIs). It covers multiple sources, fallback behavior, and soft-failure. It also references sibling tool entity_profile for alternative use cases, making it complete.

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

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

Schema description coverage is 100%, and the description adds extra meaning: explains valid formats for 'since' (ISO date or relative shorthand), suggests default values, clarifies 'type' only supports 'company', and explains 'value' can be ticker or CIK. This adds value beyond the schema.

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

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

The description clearly states the tool returns a change feed for a company from multiple sources (SEC, GDELT/GNews, USPTO) in a single parallel call. It distinguishes from the sibling tool entity_profile, which is for static profiles, thereby providing strong purpose clarity.

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?

Includes explicit example queries, specifies when to use (change feed for a company within a window), and advises against using it for static profiles by directing to entity_profile. It also suggests typical monitoring windows like '30d' or '1m' and explains fallback behavior with GDELT/GNews.

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 idempotent, non-destructive write. Description adds scoping by identifier and retention details (persistent vs 24h). No contradictions. Missing mention of overwrite behavior, but idempotentHint covers it.

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

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

Four sentences with front-loaded purpose, no fluff. 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?

With 2 required params, 100% schema coverage, and clear annotations, the description is nearly complete. No output schema is acceptable for a write tool. Slight gap: no mention of return value or confirmation.

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 describes both parameters with 100% coverage. Description adds naming conventions (e.g., 'subject_property') but doesn't add significant new meaning beyond schema.

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

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

Description uses specific verb 'save' and resource 'data' with clear examples (ticker, address, preference). Distinguishes from sibling tools `recall` and `forget`.

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

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

Explicitly states when to use ('discover something worth carrying forward') and provides pairing instructions with recall and forget. Also describes behavior for authenticated vs anonymous users.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive nature. The description adds significant behavioral context: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicit labeling of identifier sources, and the inclusion of an 'unresolved' field for failed lookups. These details go well 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 real-world query examples, then organizes details by entity type. Every sentence provides necessary information (behaviors, fallbacks, return fields). Despite length, there is no redundancy or fluff; it is as concise as possible given the complexity.

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

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

With only 2 parameters and no output schema, the description fully compensates by explaining what the output contains (identifiers, labels, unresolved field), how inputs are interpreted, error handling (graceful degradation), and source attribution. It leaves no significant gaps for an agent to guess.

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 substantial meaning: for company type, it explains the cross-source identity spine (CIK, ticker, LEI, FIGI) and how different inputs (ticker, CIK, ISIN, name) are resolved. For drug type, it specifies RxCUI, ingredient, brand, and citation. This enriches the terse schema descriptions considerably.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific example queries and lists supported entity types (company, drug), distinguishing it from sibling tools like entity_profile that likely require pre-resolved IDs.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' establishing a clear precedence over other tools. It also notes that using resolve_entity 'replaces 2-3 manual lookups,' indicating its comprehensive nature. No alternative tool is suggested for the same purpose, so the guidance is unambiguous.

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

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

The description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false) and does not contradict them.

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

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

The description is two sentences, each serving a distinct purpose: the first states the action, the second provides use case and output details. No wasted words.

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

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

Given no output schema, the description adequately explains the return value (ranked list with score, confidence, signal density). It also explains the tool's internal use of ai_visibility_check, which helps the agent understand the tool's composition. All parameters are covered by the input schema with descriptions.

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 mentions that 'entities' should have 2-8 items and the first is treated as subject, which adds some value beyond the schema. However, it does not elaborate on the other parameters beyond what the schema provides.

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

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

The description uses a specific verb 'Compare' and clearly identifies the resource 'AI visibility across multiple entities'. It distinguishes itself from sibling tools like ai_visibility_check by emphasizing side-by-side comparison and ranking.

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 the use case: 'competitive AI-marketing audits' and provides an illustrative quote. It does not explicitly state when not to use it or list alternatives, but 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 relatively long but well-structured: it starts with the composite nature, then usage guidance, then ecosystem scope, and ends with failure behavior and return fields. Every sentence adds value; 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?

Without an output schema, the description fully explains the return value structure, including specific fields like is_latest, license, advisory_count, bundle sizes, and alternative versions. It also covers failure behavior, making it complete for the tool's complexity (two params, composite logic).

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 both parameters have descriptions. The description adds nuance: scoped packages accepted for 'package', and 'version' defaults to latest when omitted. This adds value beyond the schema, though the schema is already strong.

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

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

The description clearly states the verb 'scan' and the resource 'dependency' (npm package). It says 'Composite should I add this npm package check' and specifies the fan-out to deps.dev and bundlephobia, distinguishing it from sibling tools that likely focus on broader or different topics.

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

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

Explicit usage guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also states limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent when to use this tool and when alternatives apply.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the aggregated sources and purpose, which complements the annotations without contradiction.

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

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

Two sentences plus example queries, front-loaded with purpose and examples. Efficient and 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?

With an output schema available, the description is complete for a search tool. It explains the scope and use case sufficiently.

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 60%; description adds value through examples that illustrate usage of from_year and to_year, though it does not provide detailed descriptions for these parameters.

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 'Find research datasets' with example queries and specifies the sources (OpenAIRE, Zenodo, Dryad, Figshare, B2SHARE). It distinguishes from sibling tools like search_publications and search_software.

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 example queries and states 'Use for finding open research data to reuse / cite.' While it implies when to use, it doesn't explicitly list alternatives or when not to use, 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 indicate read-only, idempotent, non-destructive. The description adds context about the returned fields and the matching logic (title/abstract/keywords), which is helpful 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 and front-loaded with example queries. It efficiently conveys the tool's purpose and scope, though it could be slightly tighter.

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

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

Given high schema coverage and the presence of an output schema, the description is complete enough for an agent to understand the tool's purpose and usage. It covers the main aspects without needing further detail.

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

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

Schema description coverage is 100%. The description includes example queries that demonstrate parameter combinations, adding semantic value beyond the schema descriptions alone.

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

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

The description clearly states the tool searches funded research projects across multiple funders (EU, NIH, NSF). It provides example queries and a list of returned fields, distinguishing it from sibling search tools like search_datasets or search_publications.

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 explicit use cases ('funding-landscape analysis, grant precedent research') and example queries, but does not explicitly mention when to avoid this tool or compare to alternatives like get_project.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable context: uses OpenAIRE, covers specific funders (EC, NIH, NSF, Wellcome Trust). 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?

Single well-structured sentence, front-loaded with action. Slightly dense but concise; examples integrated naturally.

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 search tool with output schema, description covers key aspects: purpose, source, filters. Could mention result ordering or pagination, but not essential given schema.

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

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

Schema coverage is 100% with detailed descriptions. Description reinforces parameter usage through examples but does not add novel semantics beyond the schema.

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

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

Description clearly states it searches scholarly publications via OpenAIRE, with filters for funder, country, year, and open-access. Examples and specific verb 'search' differentiate it from sibling tools like search_datasets or search_software.

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 example queries and context for use (e.g., 'search EU / open-access research'). Implicitly guides when to use via mention of funder/policy context, but lacks explicit 'when not to use' or alternative references.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the behavioral profile. The description adds that the source is OpenAIRE and that software is citable, which provides useful context but does not exceed the information already available.

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

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

The description is two sentences, directly stating the purpose and usage. No redundant or unnecessary information; every sentence is valuable.

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 presence of an output schema and full parameter coverage, the description adequately frames the domain (OpenAIRE, citable scientific software). It could elaborate on result structure, but the output schema likely covers that. Overall, sufficiently complete for a search tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description provides an example query ('bioinformatics alignment tool') and briefly notes that query matches title/abstract/keywords, which is already in the schema. Thus, minimal additional semantic value.

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 for research software in OpenAIRE, using verbs like 'find' and 'search'. It specifies the resource type (research software registrations) and distinguishes from sibling search tools that focus on datasets, projects, or publications.

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 for finding citable scientific software tied to published research,' providing clear context. However, it does not compare with alternatives like search_datasets or search_publications, nor does it state when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: embedding model (BGE-base-en), window size (500-char overlapping), character limit (200K chars with truncation flag), and return details (offsets, similarity scores). No contradiction with annotations.

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

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

The description is front-loaded with the main purpose and structured logically. It is moderately concise for the amount of information conveyed; a few sentences could potentially be trimmed, but it remains effective.

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

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

The description fully covers the tool's complexity: it explains return format (passages with offsets and scores), limitations (truncation), and integration with sibling. No output schema exists, so the description adequately describes outputs and behavior.

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

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

Schema coverage is 100%, but the description adds context beyond the schema: e.g., 'text' is described as a document to search inside, 'query' as natural-language, and 'limit' as top-N passages. This adds meaning but the schema already provides basic descriptions, so value-add is moderate.

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

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

The description uses specific verbs ('Semantic search INSIDE a fetched record') and provides concrete examples (SEC 10-K, article) that clearly define the tool's purpose. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining how they pair together.

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

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

The description explicitly states when to use ('when the record is too big to cram into the prompt') and pairs the tool with ask_pipeworx_grounded for grounding. However, it does not explicitly state when not to use or list alternatives beyond the mentioned sibling.

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

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

The description discloses OAuth requirement, delivery channels, and caps (10/day SMS). However, it does not discuss idempotency, despite the idempotentHint annotation. The annotation says idempotentHint true, but 'create' suggests non-idempotent behavior, creating potential contradiction. Also, missing side effects like cost or duplicate subscriptions.

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 purpose. It is concise yet informative, with no redundant sentences. Slightly dense but each part is meaningful.

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 (3 params, nested objects, 5 types), the description covers most aspects but lacks detail on return value structure and error conditions. For example, it doesn't specify what happens if subscription already exists or if invalid parameters are provided.

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 detailed examples for each subscription type and delivery option, going beyond the schema. It clarifies the params structure for each type and explains delivery fields like webhook signing. Without output schema, it mentions returns subscription ID, adding value.

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 and returns a new subscription ID. It specifies the verb 'Create' and resource 'subscription', and distinguishes from siblings like list_subscriptions (listing) and unsubscribe (removal).

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 context on when to use: it requires a Pipeworx OAuth account and lists supported types with examples. It does not explicitly state when not to use, but sibling tools indicate alternatives for listing and unsubscribing. The prerequisites are 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds detailed behavioral context: it returns 'category-bucketed example questions... each with the exact tool + argument shape that answers it' and describes the effect of omitting or providing the topic parameter. 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 somewhat long but front-loaded with common user queries and structured in a logical flow (purpose, output, usage, when-to-use). Every sentence adds value, though it could be trimmed slightly without losing clarity.

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

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

Given the simplicity of the tool (single optional param, no output schema, rich annotations), the description fully compensates. It explains the return format (category-bucketed with tool+argument shape) and provides a complete onboarding context. Nothing essential is missing.

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

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

Schema coverage is 100% with a clear description for the single optional parameter. The description adds value beyond the schema by listing example values ('finance', 'pharma', 'betting') and explaining the behavior difference between providing vs omitting the topic. Slightly redundant but helpful.

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

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

The description clearly states the tool is the onboarding entry point for learning what Pipeworx can do, listing equivalent user queries ('what can I ask Pipeworx?', 'getting started', etc.) and specifying that it returns category-bucketed example questions. It distinguishes itself from sibling tools by mentioning meta-tools it teaches how to call.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on arguments: call with no arguments for full spread or pass a topic to focus. Effectively guides an AI agent on initial interaction.

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

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

Annotations already indicate non-readonly (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable context: the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts', complementing 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?

Two concise sentences with no extra words. Purpose stated first, behavioral details follow. Efficient and well-structured.

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

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

For a single-parameter tool with no output schema, the description covers key behavioral aspects (ownership, deactivation vs. deletion, historical data availability) adequately. No gaps evident.

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

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

Only one parameter 'id' with 100% schema coverage; schema description already states it's a subscription uuid. Description adds no further semantics, but baseline 3 is appropriate as schema suffices.

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 verb 'Cancel' and the resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. Includes ownership enforcement, adding specificity.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), providing clear when-to-use context. Does not explicitly mention alternatives or when-not-to-use, but the sibling list and tool name make it implicit.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses critical behavioral nuances: the distinction between could_not_verify and unsupported, the failure semantics of verification_error, the structured vs grounded routing, and the 'not evidence for or against the claim' caveat. This is substantive behavioral disclosure that annotations alone do not provide.

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

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

The description is long but deliberately structured: opening with natural-language triggers, then the main use, then routing behavior, return values, and a prominent caller warning. Every sentence earns its place; the formatting makes it easy to scan, and the important caveat about could_not_verify is explicitly highlighted.

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 distinct verification paths, multiple verdict values, failure semantics, and no output schema), the description covers all essential operational aspects: what inputs are expected, what outputs are returned, how routing works, and special meanings of specific verdicts. It is sufficiently complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% for the two parameters, and the description adds meaningful context to tolerance_pct: it explains how it overrides claim-wording tolerance, gives a concrete use case (1–2 for hallucination detection), and states the default cap of 5. This goes beyond the schema's basic field descriptions, though the schema already carries the baseline 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 uses a specific verb ('verify', 'fact check') and a specific resource ('natural-language claim verification against authoritative sources'), clearly distinguishing it from sibling general-purpose Q&A tools like ask_pipeworx. It also enumerates example invocations and states the core purpose of checking whether something a user said is factually correct.

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 it contrasts the financial-claim fast path from the general grounded pipeline. It does not explicitly name alternative tools or enumerate when not to use it, but it does indicate it replaces 4–6 sequential calls, which provides clear usage context.

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