Datagov Uk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds key behavioral details: default model is free, Anthropic requires BYO key and direct payment, and returns per-model score/confidence/signals/raw_response plus combined view. 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: first defines core action, second provides default and optional key detail, third lists return format and use cases. No wasted words, front-loaded with essential 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 4 parameters and no output schema, the description explains return structure and use cases well. Could have mentioned pagination or rate limits, but not necessary for typical use.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description adds meaningful context beyond schema: default model, free tier, API key requirement for Anthropic, and how context helps disambiguate.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It distinguishes itself from siblings like compare_entities or entity_profile by focusing on multi-model visibility scoring.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and implicitly indicates when to use it, but does not explicitly contrast with alternative tools or 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 mark the tool as read-only, open-world, and idempotent. The description adds meaningful behavior: it routes to 5,798 tools across 1,517 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and handles live news routing. No contradiction with annotations exists.

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 critical prefer-over-web-search directive and uses concrete examples well. It is somewhat long and the final routing paragraph becomes repetitive and slightly garbled, so it does not earn a perfect conciseness score.

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 orchestrator tool with no output schema, it covers scope, input form, output form, and alternative routing sufficiently. It does not address failure modes, ambiguity handling, or rate limits, which prevents a top score.

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 as aliases for a single natural-language question. The description reinforces the intended input form with examples, but it does not add meaningful semantic detail beyond what the schema already provides.

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

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

The description states a specific verb and resource: routes natural-language questions about factual data to a large set of verified tools and returns structured, cited answers. It clearly covers scope and distinguishes itself from web search and sibling tools such as 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?

It explicitly instructs agents to prefer this over web search for current or historical factual questions, lists trigger phrases and concrete examples, and names sibling alternatives with the conditions under which to use them. This leaves little ambiguity about when to select this tool.

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

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

Annotations already mark it read-only and idempotent, and the description adds important context: it is a full working router with no fallback, candidate improvements are enabled live during tests, and currently no candidate is active so behavior matches ask_pipeworx exactly. This discloses experimental variability beyond the static annotation hints and shows 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?

Five sentences carry dense, relevant information: beta status, identical functionality, current test state, usage guidance, and fallback behavior. It is slightly longer than the minimal version, but every clause contributes value and the key 'beta/identical' framing is front-loaded.

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

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

The description covers what the tool is, its relationship to ask_pipeworx, the current no-candidate state, and confirms it operates as a full router despite the beta label. With no output schema, referencing 'same response shape' as ask_pipeworx is a reasonable anchor for agents already familiar with the stable tool, though it assumes that familiarity.

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

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

The input schema has 100% coverage: every property is described as an alias for the required 'question' parameter, and the question description lists all accepted aliases. The tool description adds no parameter-level detail, so the baseline of 3 applies since the schema already does the heavy lifting.

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 this is the beta version of ask_pipeworx, an identical universal router with the same tools and arguments, and explicitly distinguishes it by enabling candidate routing improvements during tests. It names the stable sibling ask_pipeworx, giving an agent a precise way to tell them apart.

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 it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. This provides a clear when-to-use condition and contrasts it with the stable alternative, making the selection logic transparent.

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 the exact success response shape, the refusal codes, the grounding behavior, and the extra cost relative to ask_pipeworx. It thoroughly explains what happens when data doesn't directly answer, which is highly transparent.

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

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

The description is information-dense with no filler. It front-loads the core purpose, then provides return shapes, refusal cases, usage guidance, and cost trade-offs, with each sentence adding distinct 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 no output schema, the description fully covers return values and refusal behavior. It also covers routing, grounding, use cases, and the cost comparison with ask_pipeworx, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the input schema already fully documents the question parameter and its aliases. The description adds context about when to ask high-stakes questions but does not add parameter-level semantics; baseline 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads, using a specific verb and resource. It explicitly differentiates from ask_pipeworx by emphasizing evidence-only extraction and refusal behavior, so an agent can distinguish it from siblings.

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 guidance: use when answers will be quoted, cited, or acted on and when the agent must not invent facts, with concrete examples like financial verdicts and legal claims. It also tells the agent to prefer ask_pipeworx for casual lookups because of the extra LLM call cost.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it details the resolution process (classifier, fan-out, response shapes), safety mechanisms (low-confidence short-circuit, closed market handling), resolution-rule risk, and news fallback fields. No contradiction with annotations.

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

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

The description is very long and covers many details, but it front-loads the main purpose and examples. Some sections (e.g., fan-out examples, resolver contract) are necessary for completeness but could be more concise. Overall, it is informative but not optimally structured for quick scanning.

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

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

The tool has 3 parameters and no output schema, so the description carries full burden. It thoroughly explains the response shape, resolver contract, parent event extractor, news fields, safety warnings, and resolution-rule risk. It covers edge cases (closed markets, wide spreads, 429 retries) and provides actionable guidance on inspecting results. Very complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the 'market' parameter accepts slugs, URLs, or question text; clarifying 'depth' defaults and behavior; and describing 'include_raw' default and use cases. It also provides examples that illustrate usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes from sibling tools by its focus on single-bet research with data fan-out.

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

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

The description explicitly states when to use the tool with three clear use cases and provides guidance on inspecting fields like 'market_match_confidence' before trusting analysis. It does not explicitly exclude alternatives but gives extensive context on safe usage, such as handling low-confidence matches and closed markets.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds rich behavioral context: source (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and return of citation URIs. No contradictions.

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

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

Description is a single coherent paragraph with example queries front-loaded. Every sentence adds value—usage, data sources, efficiency claim—though could be slightly tighter. Structure is effective for quick scanning.

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 (2 params, multiple entity types, no output schema), the description covers purpose, inputs, behavior, and expected output (paired data + citation URIs). It answers likely agent questions about when and how to invoke.

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

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

Schema coverage is 100%. Description enhances parameter meaning: explains 'type' enum with data sources (e.g., company pulls revenue/net income), and 'values' describes expected formats (tickers/CIKs for company, names for drug) and constraints (2-5 items). Adds real context beyond schema.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one call, with specific verb phrases like 'compare', 'rank', 'head to head'. It distinguishes itself from sibling tools like entity_profile by emphasizing parallel lookup efficiency.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also differentiates between company and drug types with specific data sources, though no explicit when-not-to-use beyond the preference.

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 and idempotentHint, so the description adds value by noting that resources are files (not queryable datastore tables). No contradiction.

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

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

The description is two concise sentences, front-loading the core purpose and adding a key detail about resources. 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 the low complexity (1 param, no output schema) and rich annotations, the description adequately covers the tool's behavior and return value. Could mention response format but not necessary.

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

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

With 100% schema description coverage, the baseline is 3. The description does not add additional meaning beyond what is in the schema for the 'id' parameter.

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 'full dataset record by id or slug (CKAN package_show), including its resources,' and explains what each resource provides. This distinguishes it from siblings like 'search_datasets'.

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

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

The description does not explicitly specify when to use this tool versus alternatives or provide when-not-to-use guidance. However, the purpose is clear, so an agent can infer usage 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?

The description goes far beyond the readOnly/openWorld/idempotent annotations: it discloses account requirements, paid-tier constraints, parallel tool routing, output packet structure, gap reporting, contradiction scanning, hop semantics, citation URI fetchability, semantic excerpting, and expected latency. This is unusually transparent for a tool definition and contains no contradiction with the annotations.

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

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

The description is long but information-dense, and the most actionable gatekeeping information (account required, alternative tool) is front-loaded. There is some redundancy with the depth parameter documentation, and the structure is slightly sprawling, but the length is justified by the number of nontrivial behavioral caveats an agent must know before calling this tool.

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

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

With no output schema, the description carries the full burden of explaining what the agent will receive — and it does: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers latency, auth, depth differences, citation resolvability, and response semantics. Nothing critical 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%, so the schema already documents both parameters and the depth enum thoroughly. The description adds a few behavioral details, such as 'thorough' needing a paid plan and the gap-recovery/lead-chasing differences by depth, but these mostly restate or slightly extend the schema. Since the schema carries the parameter burden, baseline 3 is appropriate.

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

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

The description clearly identifies what the tool does: it is 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in 'ONE call' and explicitly says 'this is NOT open-web search.' It also distinguishes itself from siblings by directing single-lookup use to ask_pipeworx, making the tool's scope and boundary immediately apparent.

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 is explicit about when to use the tool: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also provides auth guidance: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and notes the paid requirement for the 'thorough' depth. This is strong when/when-not/alternative guidance.

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

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

Beyond annotations (readOnly, idempotent), description adds behavioral details: returns top-N tools with full schemas and examples, each result ready to call without a second lookup.

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: first defines purpose, second elaborates on output and usage. Front-loaded and efficient with no wasted words.

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

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

Given no output schema, the description fully explains return format (names, descriptions, schemas with examples) and usage context (call first). No gaps for this 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 coverage is 100% with descriptions for all 6 parameters. The description adds no new parameter information beyond what schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes itself from siblings by being the tool discovery entry point.

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 'Call this FIRST when you have many tools available and want to see the option set', providing a clear directive on when to use the 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing exactly which sources it fans out to, how sources_used/sources_failed signal real no-data situations, that USPTO data soft-fails after sunset, and that empty FDA products are expected rather than errors. This is rich behavioral context that an agent needs to interpret results correctly.

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 information-dense; nearly every sentence adds operational value, from source enumeration to expected-empty semantics. It is front-loaded with usage examples and purpose, though the dense parenthetical style makes it slightly less scannable than a more structured breakdown.

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 large multi-source surface, the description is remarkably complete: it lists all return sections, explains empty-section semantics, names each source, describes input variations, and handles edge cases like private companies and USPTO sunset. An agent has enough context to call it appropriately and interpret results.

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

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

Schema coverage is 100%, so the baseline is already 3. The description adds meaningful details such as 'type' values being interchangeable, value accepting ticker/CIK/name, name resolution via SEC EDGAR, and the resolved:false + notes behavior for private companies, which goes beyond the schema without carrying the full 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 opens with concrete example queries and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call', giving a specific verb, resource, and scope. It clearly differentiates from single-pack SEC/XBRL/news lookups and is far from a tautology.

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 to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when a user asks for a holistic view, and it covers accepted input forms and private-company behavior. It does not name or rule out sibling tools like deep_research or compare_entities, so the guidance is clear but not exhaustive.

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

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

The description adds context beyond annotations by explaining deletion rationale (stale context, clear sensitive data). It aligns with destructiveHint: true and idempotentHint: true, with 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?

Two sentences efficiently deliver the action, use case, and related tools. 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?

For a simple tool with one required parameter and no output schema, the description covers action, usage context, and safety hints completely.

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

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

Schema coverage is 100% with a single parameter. The tool description does not add extra meaning beyond the schema's parameter description, which is adequate but not enhanced.

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

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

The description clearly states the verb 'Delete', the resource 'memory', and the method 'by key'. It also distinguishes from siblings by explicitly pairing with 'remember' and 'recall'.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related 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?

The annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool fetches the page and extracts specific elements, which is useful context but does not disclose error handling or limitations beyond the annotations.

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

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

The description is concise with three sentences and a bullet list of use cases. It is front-loaded with the main purpose and each sentence adds value. Minor room for improvement in structuring output details.

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

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

Given the tool's simplicity (one required parameter, optional max_links, no output schema), the description covers purpose, parameters, output format, and use cases. It lacks mention of error handling or non-HTML URLs but is adequate for most scenarios.

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 briefly mentions 'max_links' but adds no new meaning beyond the schema's default and maximum values. It does not explain parameter behavior or constraints beyond what's in the schema.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file', and it details the action: fetches the page, extracts title/description/key links, and emits the standard markdown format. It also provides specific use cases that distinguish it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly lists when to use the tool: for getting a client's site indexed by AI, drafting for your own project, or auditing competitors. It does not mention when not to use or alternatives, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat these. The description adds context about the CKAN source and organization types, but no additional behavioral details like pagination or rate limits.

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, consisting of two sentences with no wasted words. The first sentence clearly states the purpose, and the second provides direct usage guidance.

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

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

Given the simple single-parameter tool with rich annotations, the description provides sufficient context about the source (CKAN) and how to use the output. It could briefly mention the output structure, but this is not critical due to the absence of 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 coverage is 100% with a description for the 'limit' parameter. The tool description does not add extra meaning beyond what the schema provides, so a 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 that the tool lists publishing organizations on data.gov.uk, including examples like government departments and agencies. It implicitly distinguishes from sibling tools like organization_details, but does not explicitly differentiate.

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 guidance on using the returned org 'name' with search_datasets, implying usage context. However, it does not specify when to avoid this tool or mention alternatives, though sibling tools are available.

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

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

The description does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint=false) and adds specific return fields. However, it does not disclose any behavioral traits beyond what annotations already provide, such as pagination or limits, missing an opportunity for additional transparency.

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

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

The description is concise with two sentences: one stating purpose and return fields, another stating usage. No filler words, every sentence adds value.

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

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

The description is fairly complete for a simple list tool with one optional parameter, given the annotations cover safety. It specifies return fields and usage context. It could mention ordering or result limits for full completeness, but it's not critical.

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

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

Schema coverage is 100% for the single parameter 'include_inactive', and its description is already in the schema. The tool description does not elaborate on this parameter, so it adds no additional semantic value. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'the caller's active subscriptions', and specifies the return fields. It distinguishes itself from siblings like 'subscribe' and 'unsubscribe' by focusing on listing active subscriptions for review.

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

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

The description explicitly tells when to use this tool: to review monitored subscriptions before adding more or to find an id to cancel. It does not explicitly state when not to use it or mention alternatives, but the usage context is clear and helpful.

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 that it returns specific fields (display name, description, dataset count, optionally a sample) and mentions the tool is for UK publishers, but does not disclose additional behavioral traits like auth needs or rate limits.

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

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

The description is two sentences, front-loaded with the main action, and contains 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?

Given the tool has two simple parameters, no output schema, and annotations cover safety, the description provides sufficient detail about return fields and context (UK publishers). It could be more explicit about what 'full details' includes beyond the listed fields.

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 description does not need to add parameter details. It mentions the optional sample, which the schema already covers. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides full details for one publishing organization, with specific fields listed. It implicitly distinguishes from sibling tools like 'list_organizations' which lists all organizations, and 'dataset_details' which focuses on a single dataset.

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

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

The description says 'Use to learn what a given UK publisher releases,' which gives a clear use case but does not explicitly mention when not to use or provide alternatives.

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

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

Annotations are all false, providing little safety insight, so the description carries the burden. It exceeds expectations by disclosing the claim_token workflow, rate limiting ('5 per identifier per day'), quota implications ('doesn't count against your tool-call quota'), and even advice on what not to include (don't paste the end-user's prompt). This is rich behavioral transparency.

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

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

The description is longer than average but is front-loaded with the core purpose and organized logically. Most sentences earn their place. The motivational closing ('The team reads digests daily and signal directly affects roadmap') is slightly extraneous, so not a full 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?

There is no output schema, so the description must convey return behavior. It explains the claim_token return and how to check status. Given the tool's complexity (nested context object, varied types, usage constraints), the description covers the what, when, how, and limitations completely. It's a self-contained guide.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for the claim_token parameter by explaining how filing without an account returns a token and how to use it later. It also advises describing issues in terms of Pipeworx tools/packs, which informs the 'context' and 'message' parameters. 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and distinguishes itself from siblings by explicitly scoping to tools served by this Pipeworx connection, making it unambiguous.

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

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

Provides explicit when-to-use guidance: '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).' Also gives a clear exclusion and alternative: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage 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 indicate safe read-only behavior. Description adds valuable context: data source (CF analytics), no PII, caching duration, and aggregation format. 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?

Concise, front-loaded, every sentence adds value. Three use cases in bullets, technical details in one sentence. No wasted words.

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

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

Despite no output schema, description explains return structure (top tools, packs, volume). Caching and data source documented. Fully adequate for a single-parameter tool.

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

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

Schema covers 100% with enum description explaining window semantics. Description repeats window options but doesn't add new parameter-level details 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 trending data (top tools, packs, volume) over recent windows, with specific verb and resource. It distinguishes from sibling tools by its unique focus on aggregated trending signals.

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

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

Explicitly lists three use cases and explains window trade-offs. No 'when not to use' but the guidance is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds rich behavioral context beyond annotations: explains scanning top 200 markets, date-axis/threshold-axis ordering, partition checks, semantic anchor with Jaccard similarity, partition filter, fill check, and recommendations on not trading when realizable edge is ≤0. No contradictions.

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

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

The description is well-structured with the purpose front-loaded, then modes, then detailed behavior. Every sentence adds value, but it is dense with technical details. Could be slightly more concise, but still efficient.

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

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

Despite no output schema, the description fully compensates by describing the response structure (opportunities[], partition_check fields, fill check results). It also explains edge cases like placeholder filtering and low similarity rejections. The description is complete for a complex arbitrage scanning 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 description coverage is 100% (both parameters described). The description adds extra meaning: explains that event slug can be a full URL, topic is a seed question for cross-event scanning, and details how each parameter behaves. This significantly augments the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) with specific explanations, differentiating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains the scenarios for each but does not explicitly state when not to use, though 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses extensive behavioral details: edge computation after slippage, Kelly caps, market move warning, Fed bet exclusion rationale, caching at KV level, and diagnostics transparency. 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 but logically structured: purpose -> model families -> response segments -> knobs -> diagnostics -> caching. Every sentence adds value, though it is lengthy. Could benefit from bullet points, but clarity is not sacrificed.

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 response structure (by_segment, fed_candidates, _diagnostics) and opportunity fields (edge_pp_net, kelly_fraction, etc.). It covers caching, diagnostics for empty results, and all parameter behaviors. Highly complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds significant semantic value: explains interactions between min_kelly and min_partition_leg_kelly, slippage assumptions, and tradeable-edge filter purposes. This clarifies parameter roles beyond the schema.

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

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

The description clearly states the tool's action ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and resource ('top Polymarket markets'). It uniquely identifies the purpose with specific model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like 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 rich usage context: built for 'what should I bet on today', explicit tradeable-edge knobs (min_liquidity, max_spread_pp), and diagnostics for empty segments. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Annotations already declare read-only, idempotent, open-world. The description adds context about limitations (60-day TTL, start from snapshot enablement, decay from daily closes) and output structure, providing transparency beyond annotations without contradiction.

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

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

The description is relatively long but every sentence adds value. It is front-loaded with the key question it answers. Minor redundancy could be trimmed (e.g., 'snapshots are written when polymarket_edges runs on a cache-miss'), but overall it is well-structured and informative.

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

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

Despite no output schema, the description provides a comprehensive outline of response fields (tracked[], expired[], snapshot_dates[]) with key subfields. Limitations are clearly stated. For a tool of this complexity, the description is complete enough for correct invocation and interpretation.

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

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

Schema coverage is 100% with descriptions, but the description adds defaults (days=14, window='1wk'), clamping (days 2-30), and explains window in terms of snapshot families. This adds significant meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering a specific predictive question about edge duration. The resource (daily polymarket_edges snapshots) and verb (track) are explicit, and while not explicitly differentiating from sibling polymarket_edges, the unique focus on persistence and decay distinguishes it.

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

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

The description implies when to use (when you need edge persistence info) but does not explicitly state when to avoid or list alternatives. Given sibling polymarket_edges, explicit guidance would be beneficial, but the description is clear enough for an agent familiar with the domain.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat safety. The description adds behavioral context: walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), details forced directional risk, and explains that partial basket fills can convert arb to directional position. This is valuable 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 long but well-structured with headings (SINGLE-MARKET, BASKET) and bullet points for return fields. It front-loads the core purpose. While some details like 'each share pays $1' could be implied, the structure is clear and earns its length given the complexity of dual modes.

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?

There is no output schema, so the description fully enumerates return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict (single-market); theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk (basket). It also describes the verdict and warns about thin legs. This is complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The tool description adds meaning by explaining side auto behavior for baskets ('sell if partition sum > 1, buy if < 1'), interpreting size_usd as settlement notional in basket mode, and providing default and range. This is additive context 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 checks realizable-vs-theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes with specific verbs and return fields, and explicitly says to use it before acting on polymarket_arbitrage or polymarket_edges signals, differentiating it from sibling tools.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains that theoretical overround on thin books is not capturable and partial basket fills convert an arb into an unhedged directional position, which is the dominant loss mode. This tells when and why to use the tool.

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

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

The annotations only cover safety (read-only, idempotent, open-world), so the description carries the behavioral burden — and it is exceptionally rich: compatibility_warning/codes[] 'can be non-empty even when matched_pairs>0, so read them', temporal_alignment null means 'could not be computed' not 'aligned', pairing_unverified is 'set in EITHER mode', unknown-metric legs are 'NEVER paired', and spread_pp is gross because Kalshi fees are not modeled. These disclose exactly the misinterpretation traps an agent would otherwise fall into.

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 organized with inline labels (TWO MODES, RESPONSE, SAFETY FIELDS) that aid parsing. Nearly every sentence carries non-redundant operational information given the absent output schema, though the temporal-mismatch concept is restated in multiple places and the compatibility_codes enumeration could have been 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?

With no output schema, the description carries the full burden of explaining the return shape, and it covers everything: leg-by-leg prices with 0-1 scaling, top_spreads_pp with per-entry flags, compatibility fields, temporal_alignment semantics, the fees caveat, skipped-type counters, and low_confidence_pairs. For a complex cross-venue matcher, this is about as complete as a description can be without becoming a spec document.

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

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

Schema coverage is 100%, so the baseline is 3; each parameter already has a description and examples. The description adds real value beyond the schema by explaining the mode semantics — that topic/override params select between two equivalent matching pipelines, that the 10 shortcut names map to event fetch behavior, and that topic results are frequently not tradeable, which is essential context for interpreting the topic parameter's output.

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 names a specific verb and resource ('Cross-venue spread between Kalshi and Polymarket for the same resolving question') and the scope is unambiguous. The description further sharpens the purpose by stating it distinguishes equivalent from non-equivalent bet shapes, which separates it from the single-venue sibling tools (polymarket_edges, polymarket_arbitrage) without ever confusing its domain.

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 TWO MODES are explicitly contrasted with when to use each ('topic' for 10 pre-mapped shortcuts, explicit ticker+slug for custom pairings), and the note that both run the same matcher removes a likely selection error. It warns that 'pre-mapped ≠ tradeable' and that most topics return warnings today, but it never explicitly routes the agent to or away from sibling tools like polymarket_arbitrage or polymarket_edges — clear context, but no formal exclusions.

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 scoping details (anonymous IP, BYO key hash, account ID) beyond annotations, which already indicate read-only, idempotent, and non-destructive behavior. 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 earning its place: purpose, usage context, scoping and pairing. 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?

With one optional parameter, good annotations, and no output schema, description adequately covers behavior and return types (value or list of keys). Minor gap: no example return format.

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?

Single parameter 'key' is well-described, with schema covering 100%. Description adds the important note that omitting key lists all saved keys, enhancing schema info.

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 retrieves a saved value by key or lists all keys when omitted. Differentiates from siblings 'remember' and 'forget' by explicitly pairing with them.

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

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

Provides clear use cases (look up stored context like ticker, address, notes) and mentions scoping, but lacks explicit 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 declare readOnlyHint=true, but description describes mark_read:true as flagging events read, which modifies state. This is a contradictory and thus severely misleading.

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

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

Three sentences front-loading purpose, then details, then usage tip and alternative. No redundancy.

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

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

For a read-only tool with rich annotations, the description covers what it does, what it returns, and how to use it. Lacks output schema details but states key return fields.

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

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

Schema coverage is 100% and description adds context on return fields (source, citation_uri, raw payload) beyond schema descriptions, 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 action ('Pull fired events'), the resource ('subscription feed'), and includes specific return fields and filtering options, distinguishing it from sibling tools.

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

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

Provides explicit guidance on how to use filters and mark_read, and mentions an alternative endpoint. Lacks explicit 'when not to use' or comparison to siblings like 'list_subscriptions'.

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 safe, idempotent behavior. Description adds key behavioral traits: multi-source fan-out with fallback logic (GDELT→GNews), USPTO soft-failure, return format (grouped changes, citation URIs). No contradictions.

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

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

Description is well-structured: starts with purpose/examples, explains sources and parameters, ends with sibling distinction. Every sentence adds unique 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?

No output schema exists, but description completely specifies return format (changes array, total count, citation URIs). All three required parameters are fully documented. Complexity of multi-source aggregation is addressed.

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

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

Schema coverage is 100%, and description adds significant detail: acceptable formats for `since` (ISO or relative), examples, recommendation; ticker/CIK for `value`; type restriction to 'company'. Enriches schema meaning.

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

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

The description clearly states it's a change feed for a company, using verbs like 'What's new with X' and listing specific sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool `entity_profile`, which provides static profiles.

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

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

Explicitly tells when to use (for 'latest on Y' queries) and when not to (use `entity_profile` for static profile). Provides parameter advice (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

Adds context beyond annotations: memory scoping by identifier, persistence duration (24h for anonymous, persistent for authenticated). Annotations indicate idempotent and non-destructive, which aligns.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

For a simple key-value store with 2 parameters and no output schema, the description is complete: explains when, what, and persistence 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%, so description adds marginal value. However, it does clarify scoping (by identifier) and the nature of value ('any text'). Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using specific verbs like 'save' and 'store'. It distinguishes itself 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?

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and mentions alternatives ('pair with recall to retrieve later, forget to delete').

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, open-world, and non-destructive behavior. The description adds substantial behavioral context: multi-endpoint cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, `figi_candidates` for ambiguous matches, and source labeling. This goes well beyond the annotations and gives agents a clear model of execution 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 long and dense, with many parentheticals, but it front-loads the purpose and usage rule before diving into type-specific detail. Almost every clause contributes useful information; it is verbose but appropriate for a tool that abstracts multiple lookup endpoints. A tighter structure would earn a 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 carries the burden of explaining return behavior, and it does so thoroughly: expected identifiers per entity type, ambiguity handling, unresolved results, source labeling, and fallback behavior. An agent has enough information to call the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description greatly enriches `value` semantics with concrete format expectations, accepted identifier types (ticker, CIK, ISIN), the instruction to pass only the entity name, and the warning that trailing security-class words fail. This adds non-obvious, call-critical meaning beyond the schema.

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

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

The description is very specific: it resolves user-spoken names to canonical identifiers and enumerates supported entity types (company, drug). The opening examples make the tool's purpose immediately recognizable. However, it does not explicitly differentiate from sibling tools like entity_profile or compare_entities, so it stops short of full sibling differentiation.

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 a clear directive: 'Use FIRST whenever you have a name but need an ID,' which is strong guidance for when the tool should be selected. It does not explicitly name alternative tools or state when-not-to-use cases, though the supported input types and scope imply boundaries.

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 safety (readOnly, idempotent, non-destructive). The description adds value by explaining internal behavior: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also notes the requirement for an API key when using 'anthropic' model.

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

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

Three sentences with no wasted words. The purpose is front-loaded, and each sentence adds essential information. Excellent structure.

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 4 parameters, no output schema, and annotations cover safety, the description is fairly complete. It explains the process, use case, and parameter roles. The only minor gap is no explicit description of the return format, but it is implied by 'ranked list'.

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 clear descriptions for all 4 parameters. The description adds semantic value by specifying that the first entity in 'entities' is treated as the 'subject' for narrative. This exceeds the baseline for high coverage.

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

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

The description clearly states the verb 'compare' and the resource 'AI visibility' across multiple entities, distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison). It is specific 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 a clear use case ('competitive AI-marketing audits') and implies when not to use (single entity checks best left to ai_visibility_check). However, it does not explicitly list alternatives or exclude other scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. Description adds valuable behavioral context: fans out across two external services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. 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?

Description is informative but slightly long. It front-loads the core purpose and use cases, then details return structure and limitations. Every sentence adds value, but 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 tool's complexity (composite from two sources), the description covers purpose, usage, return format, ecosystem limitation, and timeout behavior. Annotations provide safety context. No output schema, but return structure is described. Fully adequate.

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

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

Schema covers both parameters fully (100% coverage), so baseline is 3. Description adds minor value by noting scoped packages are accepted and default version behavior, but this is already in schema. No significant extra 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 clearly states it is a composite check for evaluating npm packages for addition to a project, listing specific sources (deps.dev, bundlephobia) and what it covers (license, advisories, bundle size, etc.). It distinguishes from sibling tools by being the only one focused on npm package 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes limitations: NPM only in v1, with fallback advice for other ecosystems. Also mentions partial failure behavior.

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, etc. The description adds that content is English and specifies return fields (titles, descriptions, organization, resources), which adds value beyond the structured data.

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

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

Two concise sentences, no filler, front-loaded with key purpose. 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 5 well-documented parameters and no output schema, the description covers the main purpose and return fields. It could mention pagination but is largely 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% with good parameter descriptions. The description adds 'Content is English' and 'browse everything' but does not significantly enhance parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it searches the data.gov.uk catalogue across 57k+ UK government open datasets. This specific verb+resource combination distinguishes it from sibling tools like dataset_details or search_within.

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 context on when to use (searching UK open data) and a tip for browsing with empty query. Does not explicitly exclude alternatives, but the purpose is clear enough for an agent to differentiate.

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, etc. The description adds significant behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K chars with truncation and flagging), and output format (passages with offsets and scores). No contradictions.

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

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

The description is a single, well-structured paragraph. It starts with the core purpose, followed by use case, pairing, then technical details. Every sentence adds unique value without fluff or redundancy.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores), cap and truncation behavior, and pairs with a sibling tool. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by giving concrete examples for the query parameter (e.g., 'supply-chain risk') and elaborating on the limit range (1-20, default 5) and its role in selecting top-N passages.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the use case of reducing context when records are too large. It explicitly pairs with a sibling tool (ask_pipeworx_grounded) to differentiate usage, making the purpose distinct 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 provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. It includes concrete examples (SEC 10-K, article) but does not explicitly list when not to use it.

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

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

The description contradicts the annotations: the idempotentHint is true, but the description says 'Create a subscription' and 'Returns the new subscription id,' implying each call creates a new entity (non-idempotent). This is a clear contradiction, so the score is 1 as per guidelines.

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 but somewhat verbose and unstructured; it runs as a single dense paragraph. Front-loading the purpose is good, but bullet points or clearer separation of type-specific details would improve readability and scanning.

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 (multiple types, delivery channels, auth requirements), the description covers most aspects: it explains the subscription creation, delivery options, and references the feed pull mechanism. However, it omits how to manage subscriptions (e.g., listing or unsubscribing) and does not detail the return structure beyond the subscription ID (no output schema).

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema by providing concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic), and detailed delivery channel constraints (SMS cap, phone verification, webhook HMAC signing). This greatly aids correct parameter usage.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly specifies the action (create), the resource (subscription), and the output. It also lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions or recent_alerts.

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

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

The description provides usage context such as requiring a Pipeworx OAuth account and noting that anonymous/BYO users cannot persist subscriptions. It lists supported types and their parameters, and mentions the always-on feed and optional delivery channels. However, it does not explicitly compare to one-time query tools like polymarket_edges or advise when not to subscribe, leaving room for improvement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it explains that results are drawn from the live catalog of thousands of tools, and that it returns category-bucketed examples. This adds value beyond annotations without contradiction.

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

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

The description is front-loaded with common user queries and then provides a concise explanation of the tool's behavior. It is structured logically: purpose, output, usage, examples, and placement. While slightly lengthy, every sentence adds value, and the structure is clear.

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 sufficiently covers what the tool returns (category-bucketed example questions with tool+argument shapes) and how to use it (topic filter, default full spread). It also mentions the live catalog and meta-tools, providing enough context for an agent to understand the tool's role in onboarding.

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 optional parameter (topic) having a basic description. The description enhances this by listing example topic values ('finance | pharma | economics ...') and explaining the behavior when omitted ('for a cross-category spread'). This provides practical guidance 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 begins with natural language queries ('What can I ask Pipeworx?') and clearly states the tool's purpose: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the output (category-bucketed example questions with exact tool+argument shape) and distinguishes itself from siblings (like ask_pipeworx, entity_profile, etc.) by being the first tool to use when exploring capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides guidance on argument usage ('Call with no arguments for the full spread, or pass topic... to focus'). While it doesn't explicitly say when not to use, the context is clear and covers the primary use case.

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

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

The description adds significant value beyond annotations: it explains ownership enforcement and the deactivation (not deletion) side effect. Annotations only indicate non-destructive, idempotent mutation; the description clarifies the concrete impact.

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

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

Three concise sentences: first states action, second adds ownership constraint, third explains deactivation. Every sentence adds necessary information with no redundancy.

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

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

For a simple mutation tool with one parameter and no output schema, the description covers purpose, ownership, and side effect. It could mention return value or success indication, but current completeness is sufficient for usage.

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

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

Schema coverage is 100% with a single parameter 'id' already described as 'Subscription id (uuid) returned by subscribe.' The description merely says 'by id' without additional parameter detail, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes the tool from its sibling 'subscribe' by detailing ownership and deactivation behavior.

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

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

The description provides explicit context: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. It implies when to use (you own the subscription) but does not name alternatives for deletion or other scenarios.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, and the description supplements these with rich behavioral context: it describes the two data paths, the fallback routing, the exact return structure, and the critical caveat that 'could_not_verify' means the check did not happen and must not be treated as evidence. This goes far beyond the annotations and is consistent with 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 long but every sentence serves a purpose. It opens with attention-grabbing natural-language triggers, proceeds to clear usage conditions, then details routing, return values, and error handling. The structure is logical and front-loaded, making it easy for an agent to quickly determine if this tool fits the user request.

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

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

Despite having no output schema, the description fully specifies the return format: the verdict set, the actual value with citation, and reasoning. It also explains the nuanced difference between 'could_not_verify' and 'unsupported'. Given the tool's complexity and the absence of an output schema, this description is exceptionally 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?

Though the input schema already has 100% description coverage, the description adds significant semantics for 'tolerance_pct' by explaining it overrides tolerance implied by the claim wording and recommending values (1–2 for hallucination detection). It also provides concrete examples for the 'claim' parameter. This enriches the schema with practical, invocation-relevant guidance.

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

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

The description clearly states the tool's purpose: natural-language claim verification. It provides concrete query phrasings ('Is it true that…', 'fact check', etc.) and distinguishes itself from siblings by describing its composite nature (replacing 4–6 sequential calls) and its two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else). This is a specific verb+resource with strong differentiation.

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 whenever the agent needs to check whether something a user said is factually correct.' It further clarifies routing based on claim type (company-financial vs. any other factual claim). The description also explains the meaning and handling of distinct verdicts like 'could_not_verify' and 'unsupported', giving clear operational guidance.

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