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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, the description adds meaningful behavioral context: it automatically routes to sub-tools, fills arguments, returns structured answers with stable citation URIs, is a single fast call, and already handles live news via news-feeds packs. No contradiction with annotations was found.

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

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

The description is dense but front-loaded with the most important selection guidance: prefer over web search for factual data, then explains routing behavior, gives trigger phrases and examples, and ends with escalation alternatives. Some redundancy exists in the long list of trigger phrases and examples, and the final sentence is somewhat run-on, but overall every section 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?

For a routing tool with no output schema, the description is remarkably complete: it states the return format (structured answer with pipeworx:// citations), the data domains covered, example queries, when to use alternatives, and how this tool relates to web search. An agent has enough context to select and invoke it correctly.

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

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

Schema coverage is 100%, and all six parameters are documented aliases for the same natural-language question parameter. The description reinforces what kind of questions to ask through examples and trigger phrases, but it does not add much parameter-specific semantics beyond the schema. The baseline of 3 applies because the schema already carries the parameter documentation burden.

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

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

The description clearly states what the tool does: routes factual questions to the appropriate tool among 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also differentiates itself from related siblings by calling itself the default entry point and naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual/current/historical questions, with trigger phrases and domain examples. It also provides when-not-to-use guidance by naming ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. This is strong routing 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds meaningful behavior beyond that: routing may change live when a candidate is under test, no candidate is currently active so behavior matches stable, it exists for evaluation, and it 'falls back to nothing' so the agent knows it is a full router rather than a stub.

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?

Approximately 90 words, front-loaded with the core definition and parity statement. Every sentence earns its place, especially the 'falls back to nothing' clarification that prevents a potentially costly misunderstanding that this is a partial or stub tool. Slightly dense but 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 tool with one required parameter, no output schema, and strong annotations, the description covers identity, current state (no active candidate), usage condition, evaluation purpose, and relationship to the stable sibling. The only minor gap is an explicit when-not-to-use condition pointing to the stable or grounded routers.

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% — question plus all five aliases are documented in the input schema itself, so the baseline 3 applies. The description adds no parameter detail, but none is required given complete schema coverage and a single required field.

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 exactly what the tool is: a beta of ask_pipeworx, acting as the same universal router over 5,798 tools with identical arguments and response shape, differing only in candidate routing improvements. This clearly differentiates it from the stable ask_pipeworx sibling while confirming full functionality.

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?

Gives an explicit when-to-use instruction: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router to decide merges. It does not, however, state when to prefer the stable ask_pipeworx or the grounded variant instead.

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

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

Beyond the readOnly/idempotent annotations, the description discloses refusal behavior, refusal_reason enum values, evidence quoting, source/fetched_at fields, and the extra LLM call cost. It clearly warns against inventing facts and explains the exact success and refusal shapes.

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 dense sentences deliver high-value information: purpose, routing behavior, return shape, refusal reasons, use cases, and cost tradeoff. The first sentence is somewhat long but every clause contributes; minor tightening is possible.

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

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

For a complex tool with no output schema, the description fully compensates by specifying return fields, refusal variants, source grounding, and comparison to the sibling tool. An agent has enough context to decide whether to call it and 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% and the single semantic parameter is fully documented with aliases, so the description does not need to add parameter-level detail. The description adds contextual meaning around how the question is routed, but not parameter 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?

The description states a specific verb/resource: a grounded, hallucination-resistant answer mode that extracts answers only from tool results. It explicitly contrasts itself with ask_pipeworx and lists concrete outputs, making its purpose and differentiation unmistakable.

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 explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of one extra LLM call.

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?

Beyond the readOnly/idempotent annotations, the description discloses account and paid-tier requirements, latency (15-60s, up to ~90s for thorough), gap-recovery and contradiction[] behavior per depth, hop fields, citation_uri resolvability semantics, and non-head-truncating excerpting. 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?

Long but dense — every sentence conveys a distinct constraint or behavior, and it is front-loaded with the account gate and the primary alternative. Minor redundancy exists ('use ask_pipeworx instead' appears twice for different conditions), so it is not a perfect 5.

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 carries the return-value burden: findings packet fields (verbatim evidence, confidence, source, fetched_at, citation), gaps[] behavior for unanswered facets, contradictions[] for standard/thorough, and fetchable citation guarantee. Prerequisites, exclusions, and timing are all covered.

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 depth enum description already documents quick/standard/thorough facet counts, paid status, and hop behavior. The description adds marginal value: latency expectations and the account-gating context. Baseline 3 is correct since the schema carries the semantic load.

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?

States a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It explicitly distinguishes itself from open-web search and from ask_pipeworx (single lookups), so an agent can position it against siblings without opening 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?

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), and a named alternative with a routing condition ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). No inference required.

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 the annotations (readOnlyHint, idempotentHint, etc.), the description discloses multiple behavioral nuances: it fans out across multiple sources in parallel, soft-fails when the USPTO PatentsView API sunsets, returns resolved:false for private companies with an explicit notes line, and uses sources_used/sources_failed to indicate which sources returned data. It even clarifies that a company with only small-molecule drugs showing zero fda_products is expected behavior, not a bug. This goes well beyond the annotation hints.

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 efficiently organized: it opens with usage examples, states the core function, then systematically enumerates every output field with clarifications. No sentence is redundant; each either defines a behavior, cites a source, or preempts a common misreading. Given the tool's breadth, the length is proportionate and 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?

For a tool with no output schema and a wide-ranging behavior, the description covers everything an agent needs: accepted inputs, resolution behavior, all major return fields, the meaning of empty sections, source fallbacks, and known limitations (patents sunset). It explicitly states that sources_used/sources_failed indicate real data absence versus bugs. Nothing an agent needs to call this tool correctly 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 description coverage is 100%—both `type` and `value` are fully documented in the schema, including the interchangeability of 'company' and 'ticker' and the accepted value shapes. The description adds concrete examples ('AAPL', '0000320193', 'Moderna') and notes that names resolve via SEC EDGAR's company-name match, which is also in the schema. Since the schema already carries the semantic weight, the description's marginal addition is not enough to push above the baseline of 3.

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

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

The description opens with concrete user-intent examples and immediately states the core function: a full cross-source profile of a US public company in one parallel call. It explicitly contrasts itself with chaining single-pack lookups, making its distinct purpose unmistakable. The list of data sources (SEC, XBRL, patents, contracts, etc.) further pins down scope, leaving no ambiguity about what the tool does.

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

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

Provides explicit direction: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies input formats (ticker, CIK, name), how private companies are handled, and that empty sections are expected—giving agents clear decision rules on when to invoke this tool versus alternatives.

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

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

Annotations 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?

Beyond the readOnly/idempotent annotations, the description discloses the matching mechanism (token-overlap, not shared resolution source), the gross-fee limitation, the meaning of safety codes, and the fact that both compatibility_warning and compatibility_codes can be non-empty even with matched pairs. It is exceptionally transparent about the tool's failure modes and interpretive caveats.

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 it is front-loaded with the core purpose and uses clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS) that make scanning easy. Every sentence adds a caveat or detail relevant to correct interpretation, so the length is justified for 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?

With no output schema, the description carries the full burden of explaining the response: leg-by-leg prices, top_spreads_pp, compatibility fields, fees_note, temporal alignment, and skipped counters. It even warns that pre-mapped topics often aren't tradeable, providing a complete operational picture.

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

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

Schema coverage is 100%, but the description adds meaning by explaining that explicit ticker/slug parameters override the topic-mapped side and that both modes run the same matcher. It also enriches the topic parameter with the full shortcut list and examples, going beyond bare schema entries.

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 opening sentence defines the tool precisely: it calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. This is a specific resource and scope, and it is unambiguous against single-venue siblings like polymarket_edges or polymarket_arbitrage.

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

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

The description provides clear context for both invocation modes (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics often return compatibility warnings. However, it does not explicitly name alternative tools or exclusion conditions for when NOT to use this tool, leaving the when-to-use guidance implicit.

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

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

Annotations 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses real behavioral traits: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates instead of asserting ambiguous matches, and explicitly lists unresolved identifiers.

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 long, but nearly every sentence carries functional guidance—examples, supported types, failure modes, and lookup behavior. It is front-loaded with a clear purpose statement, though some parentheticals are lengthy and could be tightened.

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 lookup tool with no output schema, the description is remarkably complete: it specifies identifiers returned per type, source provenance, unresolved behavior, ambiguity handling, ISIN-to-LEI mapping, and graceful degradation. An agent has enough context to select and invoke this tool correctly.

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

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

Schema coverage is 100%, and the description adds substantial param semantics: detailed value examples for both type enum values, clarification that only the entity name should be passed, and a specific warning that trailing security-class words break FIGI matching. This goes well beyond the schema descriptions.

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

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

The description states a specific verb and resource: resolving user-spoken entity names to canonical/official identifiers. It explicitly enumerates supported entity types, acceptable input forms, and returns, making it easy to distinguish from siblings like entity_profile or compare_entities.

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

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

The description opens with concrete user-phrase examples and a direct instruction: 'Use FIRST whenever you have a name but need an ID.' It also explains when ambiguity occurs, what is returned in that case, and how enrichment degrades, providing clear contextual selection guidance.

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

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

The description 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.