Datagov Ie

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: the default model is free, Anthropic is BYO-key with direct payment, and the return shape includes per-model {score, confidence, signals, raw_response} plus a combined view. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary action and output, then efficiently covers default behavior, API key usage, cost, use cases, and return structure. Every sentence earns its place with no fluff.

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

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

Despite no output schema, the description enumerates the per-model return fields (score, confidence, signals, raw_response) and the combined view. All four parameters are explained in the schema and the description adds default behavior and usage scenarios, making it sufficiently complete for a moderate-complexity tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by stating that Workers AI is the free default, that _apiKey is only needed when 'anthropic' is in models and is passed straight through to api.anthropic.com, and that context helps disambiguate common names. These are practical semantics not fully captured 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 opens with 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' which is a specific verb and resource with a clear measurable output. This distinguishes it from siblings like ask_pipeworx (which asks a single assistant) and scan_competitor_ai_presence (which is competitor-specific), establishing its own scope.

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

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

It provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains when to pass _apiKey for Anthropic. It stops short of explicitly naming when not to use this tool or naming alternatives, so it loses one point for not being fully prescriptive.

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 establish read-only, open-world, and idempotent behavior. The description adds valuable context about routing among 5,407 tools, returning stable citation URIs, and being a fast single call. It does not, however, disclose limitations like potential data freshness issues or error handling, so it falls slightly short of full 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 every sentence contributes actionable information, starting with the critical 'PREFER OVER WEB SEARCH' directive. The structure flows from usage priority to alternatives to examples, making it easy to scan. It is not as tight as a two-sentence description, but the length is justified by the richness of 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 tool's simple input schema (one required string) and no output schema, the description fully covers what an agent needs: when to use, what it does, what to expect in return (structured answer with citations), and how it differs from alternatives. It even notes it works on all tiers and is the default entry point, making it contextually complete.

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

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

The schema already provides 100% description coverage for all parameters, including aliases and examples. The tool description adds little beyond implying the parameter is a natural-language question; the examples in the description also appear in the schema. Thus the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: it routes questions to a large set of sources and returns structured answers with citations. It explicitly contrasts itself with web search and distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique role unmistakable.

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

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

Extensive usage guidance is provided: it says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', gives explicit trigger phrases ('what is', 'look up'), and names exactly when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). This makes alternative selection unambiguous.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context: it is an experimental edge with live candidate routing improvements, currently identical to stable, and results are compared for merging. It also explicitly states that it falls back to nothing, meaning it is fully functional, which complements rather than contradicts 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 four sentences and conveys the beta status, current identical state, usage instruction, and a clarification that it is a full router. Each sentence adds value, though the specific retirement date (2026-07-26) is a temporary detail that may become stale. Overall, it is appropriately sized and 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 tool has six parameters, no output schema, and a complexity level that could be confusing. The description covers the experimental nature, relationship to the stable sibling, and usage, while also clarifying that there is no fallback. It references 'same response shape' as ask_pipeworx, which is acceptable given the sibling tool, but does not spell out return values explicitly. It is sufficiently complete for an agent to decide whether to use it.

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?

All six parameters are documented as aliases for the required 'question', giving 100% schema coverage. The description adds no further parameter-level detail beyond mentioning 'same arguments' as ask_pipeworx, which is minimal. The schema fully covers semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,407 tools and arguments. It distinguishes itself from the stable sibling by being the experimental edge, though the core function is conveyed via the term 'router' rather than a direct verb. The scope and relationship are well articulated.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router. It names the alternative (ask_pipeworx) and clarifies that this is a full working router, not a fallback. This gives clear when-to-use 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?

Goes well beyond the readOnlyHint and idempotentHint annotations by disclosing refusal behaviors, the specific refusal reason enum, the extra LLM call cost, and the guarantee to only use tool result content. This gives the agent a complete picture of the tool's 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 dense and front-loaded with the core purpose, but includes a somewhat long list of refusal reasons and return fields. Every sentence adds important context, but it could be tightened without losing critical information.

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

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

Despite having no output schema, the description fully documents the return shape and failure modes. It covers the tool's cost trade-off, the routing behavior, and when to use it, making the description complete for safe invocation in high-stakes 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% and the description doesn't add parameter-level detail beyond what the schema already provides. The description implies the tool accepts a natural language question, which aligns with the schema, but doesn't enrich parameter semantics further. 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 states a specific purpose: a hallucination-resistant answer mode for high-stakes reads. It explicitly differentiates from sibling ask_pipeworx by noting it extracts answers using only tool results and returns evidence, making the tool's distinct role clear.

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

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

Provides explicit guidance: use when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. This clearly states when to use and when not to use, with the alternative named.

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

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

The description goes far beyond the annotations. It details the resolver contract, fan-out mechanics, status codes (“low_confidence_match”, “market_closed_or_inactive”), safety short-circuiting, cancellation-rule risk, and news fallback behavior. Annotations only say read-only/open-world/idempotent; the description provides extensive operational detail, including a warning about flat-50¢ void settlements.

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 label-prefixed sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Every section contains dense, valuable information; however, the length is substantial and could be slightly trimmed without losing key details. It earns a 4 rather than a 5 for tightness.

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 there is no output schema, the description thoroughly explains return shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news fallback fields, safety statuses, and cancellation-rule risk. It covers edge cases and warns about potential misinterpretation, making it effectively complete for an agent to invoke and understand 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. The description does not add much parameter-specific meaning beyond explaining the overall research flow and fan-out examples. The schema already documents the market input type, depth enum, and include_raw flag, so the description adds only contextual flavor rather than parameter semantics.

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

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

The description uses a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly differentiates from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on single-market research with evidence fan-out, not cross-market arbitrage. The scope is explicit with input types and output 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 explicitly lists use cases ("should I bet on X", "what does the data say about Y", "is there edge in Z") and gives examples of fan-out behavior. However, it does not explicitly state when NOT to use this tool or name specific alternatives, so it falls short of a 5. Still, the context is clear enough to guide an agent.

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

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

With annotations already covering readOnly/idempotent/non-destructive, the description goes further by disclosing data sources (SEC EDGAR/XBRL, FAERS), specific financial metrics pulled (revenue, net income, cash, long-term debt), sorting behavior by primary metric, and the return format (paired data + citation URIs). It also highlights correct handling of off-calendar fiscal years, which is a subtle but important behavioral detail.

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 efficiently structured: query patterns lead, followed by the core directive, then type-specific data details, and finally return format/savings. It packs extensive useful information into about 80 words without fluff. Every sentence contributes to the agent's understanding of when and how to use the tool.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete: it states inputs, data sources, output composition (paired data, citation URIs), sorting behavior, and scale of savings (replaces 8–15 lookups). It answers likely questions an agent would have when deciding to invoke it, leaving little ambiguity.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds semantic value by explaining what each type does (company pulls 10-K financials, drug pulls FAERS/trial data) and providing concrete examples (AAPL, MSFT, ozempic) beyond the schema's basic descriptions. This enriches parameter understanding, though not to a level of 5 given the schema already does significant work.

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

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

The description opens with concrete user phrasings ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single call. It distinguishes itself from sibling tools like entity_profile by explicitly claiming to replace 8–15 sequential lookups, making the purpose unmistakable.

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

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

The description gives explicit when-to-use signals with query patterns and the imperative 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates usage by type (company vs drug) and notes the tool handles off-calendar fiscal years, which is a clear edge-case guideline. This is strong 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 mark it as read-only, idempotent, and non-destructive. The description adds value by explaining the structure of the return (resources, url, datastore_active flag) and the relationship to datastore_query. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary purpose and immediately followed by relevant resource details. Every clause earns its place, with no redundant or tangential content.

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

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

For a simple tool with one parameter, rich annotations, and no output schema, the description provides sufficient context: what the record contains, how to identify resources, and the path to row-level access via datastore_query. This is complete for an agent to invoke the tool correctly.

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

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

The single parameter 'id' is fully documented in the schema with examples and the notion of slug. The description reinforces 'by id or slug' but does not add new parameter semantics or format details 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 clearly states the tool returns a full dataset record by id or slug, naming the CKAN package_show operation and explicitly noting it includes resources. This distinguishes it from sibling tools like datastore_query and search_datasets by specifying the granularity (record-level vs row-level vs search).

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

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

It implies when to use this tool (to get a dataset record and its resources) and points to datastore_query as an alternative for row-by-row access of datastore-active resources. However, it does not explicitly contrast with search_datasets or mention when not to use it, leaving some implicit 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 read-only, idempotent, and non-destructive behavior. The description adds the crucial constraint that the tool only works for resources with datastore_active=true, which is not captured by annotations, and implies failure conditions for inactive resources.

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 consists of exactly two sentences: the first states the primary action and method, the second gives a prerequisite and a pointer to obtaining the ID. It is front-loaded and every word earns its place.

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

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

Given the rich schema and clear annotations, the description is largely complete for a read-only query tool. It conveys the core purpose, a key constraint, and the source for the required parameter. It does not elaborate on output structure, but that is acceptable without 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?

The input schema provides 100% coverage with descriptions for all five parameters, including examples and types. The description itself adds minimal extra meaning, only pointing to dataset_details as the source for resource_id, which is a minor supplement.

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 reads actual table rows from a resource via CKAN datastore_search. It specifies the resource type (with datastore_active=true) and distinguishes from sibling tools focused on metadata or dataset discovery.

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 prerequisite (datastore_active=true) and instructs the agent to obtain resource_id from dataset_details, giving an explicit usage context. It does not, however, explicitly list alternative tools or 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description goes far beyond this by disclosing account requirements, the need for a paid plan for 'thorough', the output packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), the explicit gaps[] and contradictions[] arrays, the hop field, semantic excerpting, and expected latency (15-60s). No contradictions with annotations.

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

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

The description is long but front-loaded with the critical account warning and densely packed with high-value information. It is logically structured (access, mechanism, usage guidance, depth semantics, output details, timing). There is minor redundancy in the repeated contrasts with ask_pipeworx, but every sentence contributes meaningful operational knowledge.

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 high complexity, simple schema (2 params), no output schema, and minimal annotations, the description carries the full burden. It comprehensively covers auth/fallback, data source types, parallel routing, output format, edge cases (breaking news → gaps[], 'never invented'), depth differences, contradictions[], and timing. No significant ambiguity remains.

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

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

The schema already has 100% coverage for both parameters with detailed descriptions, so the baseline is 3. The description adds operational meaning beyond the schema: 'thorough' requires a paid plan, 'standard' triggers gap recovery with a contradictions[] scan, and latency scales with depth ('up to ~90s' for thorough). It also reinforces that broad/multi-part questions are valid.

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

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

The description clearly identifies the tool's purpose with a specific verb+resource ('Grounded multi-source research across Pipeworx's 1403 STRUCTURED data sources') and distinguishes it from siblings by explicitly stating 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups. It also explains the parallel decomposition mechanism, making it unique among the 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 when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also handles the auth fallback: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds meaningful context beyond these: it discloses the return format (top-N tools with names, descriptions, and full input schemas with curated examples) and the fact that results are directly callable without a second schema lookup. This enriches understanding of what the tool does without contradicting 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 and front-loaded, starting with the core purpose. It lists relevant domains in a compact enumeration, then explains the return format and recommended usage in a tightly structured few sentences. No fluff or redundancy; every sentence contributes 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 tool has no output schema, but the description fully explains what is returned: top-N tools with names, descriptions, and full input schemas, ready to call directly. It also covers the intended usage context and the discovery workflow. Given the tool's simplicity and the schema's parameter documentation, this is complete.

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

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

Schema description coverage is 100%, with clear descriptions for query and its aliases, plus limit. The description itself does not add additional parameter-level detail beyond the schema, but it aligns with the 'query' parameter by giving usage examples. Baseline 3 is appropriate since the schema carries the semantic weight.

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 'Find tools by describing the data or task,' which clearly states the verb, resource, and mechanism. It distinguishes itself from siblings by specifying this is a meta-tool for discovering other tools, not for executing tasks, and lists the domains it covers. This is specific and unambiguous.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (when you already know the tool). It also gives a concrete alternative context by contrasting with returning just one answer.

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 read-only/non-destructive annotations, the description discloses significant behavioral details: it fans out across multiple sources in parallel, returns specific fields with 'up to 5' filings and URIs, uses a GDELT→GNews fallback for news, and soft-fails for the sunsetting USPTO API. This gives the agent a clear picture of what happens during execution.

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, starting with example user queries to signal intent, then listing data sources, output components, and constraints. Every clause earns its place, and the structure flows logically from purpose to execution 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?

With no output schema, the description carries full responsibility for explaining return values. It enumerates the output fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and provides data source specifics, fallback behavior, and parameter constraints. This is complete for a complex tool with multiple integrations.

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

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

The input schema already provides thorough descriptions for both parameters, including the ticker/CIK format and the 'names not supported' condition, giving 100% schema coverage. The description repeats this information without adding new semantics, so the baseline of 3 applies.

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 function: producing a full cross-source profile of a US public company. It uses specific verbs like 'profile', 'research', and 'brief me' and distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and referencing resolve_entity for name resolution.

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 guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when-not-to-use ('names not supported (use resolve_entity first if you only have a name)'). It also mentions the patents API sunset and fallback behavior, giving clear context for 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 annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds little behavioral context beyond confirming it deletes by key; it doesn't mention error handling, irreversibility, or permission requirements. Since annotations cover the main behavioral traits, a score of 3 is appropriate.

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

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

The description is three concise sentences: the first states the action, the second gives usage triggers, and the third mentions related tools. Every sentence earns its place with no redundancy or filler, and the most important information is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema) and the presence of destructive and idempotent annotations, the description is largely complete. It covers purpose and usage, but doesn't mention what happens on success/failure or if the key doesn't exist, which would be helpful but is not critical for such a simple operation.

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

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

The input schema already provides a full description for the 'key' parameter ('Memory key to delete') and marks it required, with 100% schema_description_coverage. The description adds no extra parameter semantics beyond what the schema states, so the baseline of 3 applies.

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 deletes a previously stored memory by key, using a specific verb and resource. It also distinguishes itself from sibling tools by implying it is the deletion counterpart to 'remember' and 'recall', making its purpose unambiguous.

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

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

The description provides explicit conditions for when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data'), which is clear context. However, it does not explicitly state when not to use it, though naming 'remember' and 'recall' gives some alternative context. This falls short of a full 'when-not' exclusion but is still strong guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it fetches the page and emits a text blob, which clarifies the side-effect-free network behavior. It does not mention failure modes, rate limits, or edge cases, but the annotations lower the bar.

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

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

Three sentences, front-loaded with the primary purpose, followed by process and use cases. Every sentence adds value without redundancy.

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

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

For a simple two-parameter tool with no output schema, the description explains what it does, how it behaves (fetches, extracts, emits), the output format ('single text blob'), and when to use it. This is complete for selecting and invoking the 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% for both parameters, so the schema fully documents url and max_links. The description does not add parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states it 'Generate a production-ready llms.txt file for any URL' and explains the process (fetches page, extracts title/description/key links, emits standard markdown). This specific verb+resource combination distinguishes it from siblings like ai_visibility_check or scan_competitor_ai_presence.

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

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

Provides explicit 'Useful for' contexts: client indexing, drafting for own project, auditing competitor AI crawler view. It lacks explicit alternatives or when-not-to-use conditions, but the use cases are clear enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the CKAN group_list reference and specific source, but discloses no additional behavioral traits such as pagination, rate limits, or output format. Overall, the description contributes some context without contradicting annotations.

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

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

The description is a single sentence, front-loaded with the primary action, and contains no unnecessary words. It efficiently conveys the tool's purpose in minimal space.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description provides adequate context: it names the source (data.gov.ie) and the underlying API call (CKAN group_list). It does not explicitly describe the return format, but the tool's name and purpose make that relatively clear. The combination of description and annotations is sufficient for basic 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?

The schema covers 100% of the parameters, with the 'limit' parameter described as 'Max groups, 1-1000 (default 100)'. The description adds no extra parameter meaning beyond what the schema already provides, so the baseline score of 3 applies.

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 lists thematic groups/categories on data.gov.ie, with the verb 'List' and a specific resource. It also references the underlying CKAN group_list endpoint, which distinguishes it from sibling tools like list_organizations and 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 implies usage for retrieving groups/categories but gives no explicit guidance on when to use this tool over alternatives such as list_organizations or dataset_details. No exclusions or alternative tool mentions are provided, but the context of the data source is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the source domain and CKAN endpoint, but does not disclose additional behaviors such as pagination specifics, response shape, or rate limits. It adds minimal value beyond annotations.

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

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

The description is a single, concise, front-loaded sentence that states the action and scope without any redundancy or filler. It earns its place with zero 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?

The tool is simple (one optional parameter), has rich annotations (readOnly, openWorld, idempotent), and the description clearly conveys purpose and domain. No output schema exists, but for a list operation the expected return is obvious, and the mention of CKAN organization_list provides enough context. The description is complete for this tool's complexity.

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

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

The input schema has 100% coverage for the single 'limit' parameter, including its range and default. The description itself does not elaborate on parameters beyond what the schema already provides, so the baseline of 3 applies without additional contribution.

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') and the specific resource ('publishing organizations (government departments, state agencies, county/city councils)') on data.gov.ie. It also names the underlying CKAN endpoint (organization_list), which distinguishes it from siblings like list_groups and 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 provides clear context about what the tool does but does not explicitly state when to use it versus alternatives. It does not mention exclusions or direct users to another tool for related needs (e.g., list_groups). Usage is implied but not articulated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns specific fields (id, type, params, etc.) and scopes to the caller, providing behavioral context beyond annotations. It does not mention pagination, but the tool is simple.

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

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

Two sentences: first states the core action, second lists return fields and use cases. Every sentence earns its place, front-loaded and free of fluff.

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

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

For a simple list tool with one optional parameter, the description covers what it returns, when to use it, and the caller scope. No output schema exists, but the return fields are enumerated. Completely 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?

The single parameter include_inactive is fully described in the schema with 100% coverage. The description does not add extra meaning specifically about the parameter, 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 lists the caller's active subscriptions, specifying the exact resource and scope. It distinguishes itself from siblings like subscribe and unsubscribe by focusing on listing, and includes the return fields for clarity.

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

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

Explicitly provides when to use: 'review what you're monitoring before adding more' and 'find an id to cancel.' This implies complementary use with subscribe/unsubscribe, giving clear context without needing to name 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 no behavioral hints. The description compensates by disclosing key traits: it is rate-limited ('Rate-limited to 5 per identifier per day'), free (doesn't count against tool-call quota), and that feedback is read daily and affects roadmap. This adds useful context beyond the neutral annotations, though it doesn't describe the response format or what happens after submission.

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

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

The description is concise and well-structured, with each sentence providing distinct value: purpose, when-to-use, content guidelines, and rate-limit constraints. It is front-loaded with the primary action and contains no filler or repetition.

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

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

For a simple feedback tool with 3 parameters, no output schema, and neutral annotations, the description fully covers purpose, usage, message guidance, and limitations (rate limit, quota). It is complete enough for an agent to correctly select and invoke the tool without additional context.

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 all parameters are documented. The description adds valuable guidance for the 'message' parameter by instructing users to describe issues in terms of Pipeworx tools/packs and not to paste the end-user's prompt. This goes beyond the schema's plain-text description and helps ensure high-quality feedback.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource+scope. It clearly distinguishes this feedback tool from sibling tools like ask_pipeworx or discover_tools by focusing on submitting feedback rather than retrieving information.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a when-not instruction: 'Don't paste the end-user's prompt.' This provides clear usage context and exclusions, covering all major 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=true and other safety hints. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, contents, and caching behavior 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 information-dense with clear segmentation: core description, use cases numbered (1-3), and technical notes. All sentences add value, but it is longer than necessary compared to the model two-sentence example. Still, it remains concise given the amount of context provided.

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

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

With only one optional parameter and no output schema, the description covers all essential aspects: what the tool returns, why an agent would use it, data source, privacy (no PII), contents, and caching. It even hints at the return structure ('just (pack, tool, count)'). Complete enough for selection and invocation.

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

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

The single parameter 'window' is fully described in the schema with enum values and semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The description itself only mentions the window in passing without adding 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 clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' This specific verb+resource+outcome distinguishes it from siblings like ask_pipeworx or discover_tools by focusing on aggregated trending data.

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

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

It provides explicit use cases: '(1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' However, it does not explicitly mention when not to use this tool or name alternative tools.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals behavioral details: the partition filter drops placeholder slugs and returns null when >20% placeholder fraction, the semantic anchor uses ≥0.30 Jaccard similarity, and the fill check prices against live CLOB depth with a warning not to trade if realizable_edge_pp ≤ 0. These traits are not in annotations and are critical for correct usage.

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

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

The description is long (several hundred words) but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds value for a complex tool, so it earns a 4. It could arguably be condensed, but the density is warranted.

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

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

The tool has no output schema, so the description compensates by detailing the response shape: opportunities[] with fields, partition_check object, and fill check results. It also covers edge cases (null arb signal, placeholder filter, low similarity) and provides a fail-safe trading caution. This makes it adequately 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 good descriptions already, but the description adds significant meaning: it explains that calling with no arguments is a valid trending_scan mode, gives concrete slug examples for event, notes that full URLs are accepted, and elaborates on how topic mode works across events. This transforms understanding of the parameters.

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

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

The description opens with a precise statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the resource (Polymarket) and the specific action (finding arbitrage) and then distinguishes among three modes (trending_scan, event, topic). It also differentiates from sibling tools by mentioning polymarket_fill_risk for custom sizing.

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 the agent when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides an explicit alternative: 'For custom sizing use polymarket_fill_risk.' This gives clear when/when-not/alternatives 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?

Even with readOnlyHint=true and idempotentHint=true, the description adds rich behavioral context: explains the three model families, the 24h-move warning, why Fed bets are excluded from ranking, the diagnostic funnel counters, and that partition_overround always returns kelly_fraction_half=0 at parent level. It also discloses caching behavior. No contradictions with annotations.

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

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

The description is long but densely informative, with each section (model families, knobs, response structure) adding unique value. It could be more scannable, but for a tool with 9 parameters and no output schema, the length is justified. The opening sentence is front-loaded with the core 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?

Given no output schema, the description fully documents the response top-level structure (by_segment, fed_candidates, _diagnostics) and explains why segments may be empty (e.g., filter_skips, funnel counters). It also covers all parameters with usage context and caching behavior, making it complete for an agent to select and invoke correctly.

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

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

The schema coverage is 100%, so baseline is 3. The description adds extra semantics beyond the schema: it explains knob interactions (e.g., min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable'), and clarifies that min_partition_leg_kelly applies per-leg because parent Kelly is always 0 for partitions. This goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings by detailing the multi-model approach (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the response segmentation, making its purpose as an opportunity discovery tool unambiguous.

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

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

The description provides clear usage context: 'Built for "what should I bet on today"' and explains when to apply specific knobs (e.g., 'Set to 2 to require tight books' for max_spread_pp). It does not explicitly name alternative tools, but the niche is well-defined and the sibling context suggests differentiation.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail: full time-series of edge_pp_net, trend classification (new/widening/stable/decaying), decay_pp_per_day computation, expired opportunities with lifespan, snapshot gaps, TTL limits, and net-of-slippage caveat. 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 well-organized into Args, RESPONSE, and LIMITS sections. It is dense yet every sentence contributes essential context, especially critical given there is no output schema. Purpose is front-loaded and the structure enhances readability.

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

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

Without an output schema, the description fully documents the response shape: tracked[] with fields (first_seen, trend, decay), expired[] with lifespan_days, and snapshot_dates[]. It also explains data availability caveats (TTL, gaps, net of slippage), making the tool self-sufficient for an agent to reason about 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 description coverage is 100%, so baseline is 3. The description mostly repeats schema info (days as lookback with default/max, window as snapshot family with default). It adds minimal nuance like 'snapshot family' and cache-miss context, but no 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 states a clear, specific purpose: edge persistence and decay telemetry. It explicitly answers the questions 'how long has this edge existed and is it shrinking?', which distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage (opportunity scanning).

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 effectively conveys when to use the tool: for assessing edge freshness and decay, with the example that a 3-week-old wide edge differs from a fresh one. However, it does not explicitly name alternative tools or exclusion criteria, instead relying on sibling context to signal differentiation.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds deep behavioral context: ladder walking, return fields, verdict outcomes, basket fill mechanics, and the dominant loss mode (unhedged directional position). 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?

Despite being long, every sentence carries unique information and the structure is highly efficient: intro, required parameters, single-market details, basket details, usage guidance. Labels like 'SINGLE-MARKET:' and 'BASKET:' create scannable sections. No redundant phrasing or filler.

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

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

Given the tool's complexity (two modes, 4 params, no output schema), the description is remarkably complete. It enumerates all return values, explains edge cases (thin_legs, forced_directional_risk), and provides concrete usage thresholds. Absolutely adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description adds substantial semantic meaning: it explains how size_usd is interpreted differently in single-market vs basket mode (max spend vs settlement notional), clarifies the side parameter defaults and auto-detection logic, and defines what each mode requires. This goes far beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market vs basket) and explicitly names sibling tools it complements, making the purpose unmistakable.

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

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

The description directly says when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create directional risk), providing clear guidance and 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?

The annotations already declare read-only and non-destructive behavior, but the description goes far beyond by disclosing response structure, the two modes, and crucially the safety fields: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also transparently notes that most pre-mapped topics currently return warnings, setting accurate expectations. 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 long but dense, covering multiple modes, response details, safety fields, and caveats. It is front-loaded with the core purpose, though the rest is a wall of text that could benefit from bullet points or clearer section breaks. Every sentence contributes essential information, justifying its length for a tool with this complexity.

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

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

Given the absence of an output schema, the description compensates thoroughly by explaining the response structure: leg-by-leg prices, spread[].top_spreads_pp, and safety fields. It also anticipates edge cases (non-equivalent bet shapes, temporal misalignment) and explains what they mean for the user, making the tool self-sufficient for an agent to understand both input and output.

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

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

Schema description coverage is 100%, but the description adds substantial meaning by explaining the interplay between parameters: topic as a shortcut, and kalshi_event_ticker/polymarket_event_slug as overrides to the topic-mapped side. It also clarifies that the parameters are optional (required: 0) and shows examples, going beyond the schema's individual field descriptions.

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

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

The description opens with a clear statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This specific verb+resource definition distinguishes it from sibling tools like polymarket_arbitrage, making the tool's function immediately evident.

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?

Usage guidance is implicit but strong: it explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, implying when to trust results. It does not explicitly compare to alternatives, but the caveat 'pre-mapped ≠ tradeable' and the compatibility_warning conditions offer clear practical guidance on when the tool's output is meaningful.

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 safety profile is established. The description adds valuable behavioral context: scoping to identifier (anonymous IP, BYO key hash, or account ID), the ability to list all keys by omitting the key argument, and the relationship to remember/forget. This goes beyond the annotations without contradicting 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 concise, with three sentences that are all informative. It front-loads the primary function, then provides usage context and scoping. No redundant or filler content.

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

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

The tool is simple with one optional parameter and no output schema. The description covers operation, listing behavior, usage examples, scoping, and related tools. It adequately explains what the agent needs to know to invoke it correctly, including the behavior when the key is omitted.

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

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

Schema description coverage is 100% for the single 'key' parameter, including the note to omit it to list all keys. The description restates this but does not add new semantic detail beyond what the schema already provides, so the 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 a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It explicitly distinguishes from sibling tools by naming 'remember' and 'forget', and clarifies the scope of operation.

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

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

The description provides clear context for when to use the tool: 'look up context the agent stored earlier' and examples like 'user's target ticker, an address, prior research notes'. It also mentions pairing with remember and forget, but does not explicitly state when not to use it or alternative tools for different needs.

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

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

The description adds significant behavioral context beyond the annotations: the mark_read side-effect ('flag returned events read so the next call only shows newer ones'), the persistent feed nature, and the return payload contents (source, citation_uri, raw event). It also notes the same feed is available via HTTP, which is additional transparency. No contradiction with readOnlyHint since the side-effect is explicitly disclosed.

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

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

The description is well-structured and front-loaded with the primary purpose. Every sentence contributes useful information: purpose, return details, filtering, mark_read side-effect, and polling/alternative access. It is not overly verbose, and remains succinct given the tool's complexity.

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

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

For a read tool with 5 optional parameters and no output schema, the description is complete. It covers what the tool returns (source, citation_uri, payload), how to filter, the read-state side-effect, and an alternative access method. The schema covers parameter details, so the description compensates for the missing output schema with a summary of the return envelope.

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 by explaining usage of 'type' (e.g. 'sec_8k') and 'since' (ISO timestamp), and clarifies the mark_read behavior. It does not explain every parameter, but the schema handles those (limit, unread_only), and the description enriches the key ones.

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 function: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It identifies the specific resource (subscription feed alerts) and differentiates from siblings like list_subscriptions (which would manage subscriptions, not pull alert events).

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

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

The description provides clear context on when to use the tool ('Polls work fine') and an alternative for scripts/dashboards (direct HTTP endpoint). However, it does not explicitly contrast with sibling tools or state when not to use it, so it falls just short of a 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses fan-out behavior across SEC EDGAR, GDELT→GNews fallback (with rate-limit/5xx triggers), and USPTO soft-fail due to API sunset. It also describes the return structure (changes[], total_changes, citation URIs), providing robust behavioral context without contradicting 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 every segment serves a purpose: query examples, core function, data sources, since syntax, return structure, and an explicit alternative. It is front-loaded with user-intent phrases and structured in a logical flow without redundancy. No wasted sentences.

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

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

Given the tool's complexity (multi-source fan-out, fallbacks, no output schema), the description fully covers return values, source-specific behavior, and caveats like PatentsView sunset. It provides sufficient context for an agent to invoke the tool correctly and interpret results, even without 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 covers 100% of parameters, but the description adds meaningful guidance: since accepts ISO dates or relative shorthand with examples and a recommendation ('Use "30d" or "1m" for typical monitoring'). This goes beyond the schema's raw format definitions and helps agents choose appropriate values.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with specific verb phrases like 'What's new with X' and 'change feed for a company in the last N days/weeks/months'. It explicitly distinguishes it from siblings by naming entity_profile as the alternative for static profiles, ensuring no confusion.

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 context (e.g., 'latest on Y', 'updates on Acme') and when-not-to-use guidance ('Use entity_profile instead when you want the static profile... regardless of window'). It also explains source fallbacks and acceptable since formats, giving the agent clear decision criteria.

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 (idempotent, non-destructive), the description adds key behavioral context: scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. These details meaningfully inform an agent's expectations and are not present in annotations.

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

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

Four tightly written sentences, front-loaded with the core purpose. Every sentence adds value: usage guidance, storage mechanics, retention policy, and relationship to related tools. No redundancy or filler.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, when-to-use, storage format, scoping, expiration, and companion tools. This is fully adequate for an agent to invoke correctly without additional context.

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

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

Schema has 100% coverage with descriptive parameter explanations. The description adds no new parameter-level information beyond what's in the schema, though it reinforces the key-value nature. 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, specifies it works across conversations/sessions, and distinguishes itself from siblings by naming recall and forget as companions. Specific verb 'Save' plus resource and scope.

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

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

Provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference). Names alternatives (recall/forget) and explains how they pair with this tool. Clear context for when to apply.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds valuable context: 'Each call cascades through several lookup endpoints internally' and details the exact return structure (ticker, CIK, citation URI, RxCUI, ingredient, brand) and auto-disambiguation. This goes well beyond the annotations.

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

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

The description is front-loaded with common user queries, then organizes supported types clearly. Every sentence contributes either usage guidance, parameter detail, or behavioral context. It is dense but not bloated, making efficient use of structure with headings like 'SUPPORTED TYPES'.

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

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

With no output schema, the description fully explains return values for each type, including specific fields and citation URIs. It also covers input edge cases (ticker vs CIK vs name) and the internal cascade behavior. For a two-parameter tool, this is comprehensive enough for an agent to invoke it correctly.

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

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

The input schema already covers both parameters with descriptions (100% coverage). The tool description adds extra meaning by explaining the output for each type and clarifying that value accepts ticker, CIK, or name for companies and brand/generic for drugs, with auto-disambiguation. This enriches the schema but does not radically transform it, justifying a 4.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific examples ('ticker', 'CIK', 'RxCUI') and details the resource types, distinguishing it from siblings like entity_profile or compare_entities. The verb 'resolve' and target resource are explicit and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the supported entity types and input formats. However, it does not explicitly mention when not to use the tool or name alternative tools for other use cases, so it stops short of a 5.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) already cover safety. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density. It does not contradict annotations and explains the multi-step nature of the operation.

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 fluff: action, mechanism, use case, and return format. The example query is illustrative but concise. All information is front-loaded and directly relevant.

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 the operation flow, return format, and use case. There is no output schema, so the mention of 'ranked list with score, confidence, signal density per entity' is essential and present. It does not detail error scenarios or call volumes, but for a read-only comparison tool this is sufficient.

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

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

Schema coverage is 100% with detailed parameter descriptions, including the 'first entry treated as subject' rule for entities. The tool description adds no new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the explanatory 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 states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from the single-entity tool ai_visibility_check by explaining it probes multiple entities and ranks them. The example query ('does Claude know about us as well as our competitors?') further clarifies the purpose.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits.' It implicitly contrasts with ai_visibility_check (single-entity) by describing multi-entity probing, but does not explicitly name alternatives or say when not to use. Sibling tools like compare_entities are not mentioned, so differentiation is not fully explicit.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timed-out sources. It also discloses the fan-out across multiple services and that the tool returns a structured summary plus details. Not exhaustive but strong.

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

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

The description is long but front-loaded with the core purpose. Every sentence adds useful information: purpose, usage triggers, service fan-out, output summary fields, ecosystem limitations, and failure handling. It could be tightened slightly, but it is well-structured and information-dense.

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 and lack of an output schema, the description does an excellent job of covering what the tool returns (summary block, per-advisory detail, links, recent alternative versions), how it behaves under partial failures, and its scope (NPM only). This is nearly complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the description's burden is low. The description does not add significant parameter-specific meaning beyond the schema; it merely reinforces that 'package' is an npm package name and 'version' defaults to latest. This is adequate but not additive.

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 as a composite 'should I add this npm package to my project' check, with specific verb 'fan out across deps.dev and bundlephobia'. It distinguishes itself from sibling tools by focusing on npm dependency scanning and mentions the exact outputs (summary block, advisory details, links).

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 provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states ecosystem limitations and directs other ecosystems to 'deps.dev:version directly', giving a clear alternative for non-NPM cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and non-destructive, so the safety profile is covered. The description adds useful context about the source (data.gov.ie), the scope (government departments, state agencies, local councils), and return content (titles/descriptions and resources, in English), which goes beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the main purpose, and follows with relevant detail about scope and results. There is no redundant information or filler.

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

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

For a search tool with well-described parameters and safety annotations, the description is complete enough: it explains the source, the result contents, and the scope. It does not mention pagination behavior, but the schema covers 'start' and 'rows'. Given the absence of an output schema, the description reasonably clarifies what will be returned.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema; it does not clarify formats, relationships between parameters, or edge cases. The schema itself already documents each parameter thoroughly, so the description's contribution here is minimal.

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

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

The description uses a specific verb ('Search') and identifies the exact resource ('Ireland's national open-data catalogue'), with further detail about the backend (data.gov.ie, CKAN package_search). It clearly distinguishes this from sibling tools like dataset_details (which likely retrieves a specific dataset) or datastore_query (which queries data within a 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 provides clear context for when to use the tool (searching the Irish national open-data catalogue) and what it returns (matching datasets with titles/descriptions and resources). It does not, however, explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations cover read-only, idempotent, open-world, and non-destructive traits. The description adds valuable behavioral details beyond this: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and a 200K char cap with truncation flag. It also mentions the output includes character offsets and similarity scores, helping the agent anticipate results.

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

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

The description is four sentences, each earning its place. It front-loads the core purpose, then adds usage context, pairing with another tool, and technical specifics without any fluff. It is concise yet information-dense, with a logical flow from purpose to use case to implementation.

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?

Even without an output schema, the description tells the agent exactly what to expect: top-N passages with character offsets and similarity scores. It covers the use case, saves-context benefit, pairing, and technical constraints. This is a complete picture for a tool of moderate complexity.

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

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

The input schema already provides 100% coverage with detailed descriptions for text, query, and limit, including example queries. The description adds conceptual context (e.g., the record is 'a SEC 10-K body' and offsets verify quotes) but does not significantly expand what the schema already states about parameter semantics. It's adequate, not exceptional.

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 a specific action: 'Semantic search INSIDE a fetched record,' with a defined resource (the text parameter). It differentiates from sibling tools by emphasizing it operates on an already-fetched record, not on the entire dataset, and explicitly pairs it with ask_pipeworx_grounded. This makes the tool's purpose unmistakable.

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

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

The description provides explicit guidance on when to use the tool: 'Use when the record is too big to cram into the prompt.' It also describes the workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'), effectively distinguishing it from alternatives. This is strong, actionable 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?

Beyond annotations, it discloses the OAuth account requirement, that anonymous/BYO cannot persist subscriptions, the always-on feed behavior, and SMS verification/rate caps. It also states the return value (subscription id), which is especially valuable since no output schema exists. No contradictions with the annotations are present.

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

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

The description is dense and well-structured, moving from purpose to types to delivery channels. Every sentence carries operational weight, though the long single paragraph could be more scannable with bullet points. Still, there is no filler 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?

For a tool with complex nested parameters and no output schema, the description is remarkably complete: it covers purpose, auth prerequisites, supported types, delivery options, constraints, and the return value. Webhook details are left to the schema, which is acceptable given the high schema coverage.

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 adds meaningful semantic value by providing concrete examples for each subscription type (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and explaining delivery semantics in prose. This enhances what the schema already documents.

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 'Create a proactive monitoring subscription to a live-data event stream,' clearly identifying the verb and resource. It distinguishes this tool from siblings like list_subscriptions, recent_alerts, and unsubscribe by focusing on proactive creation and ongoing delivery.

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 provides clear context for when to use the tool and explicitly mentions the OAuth prerequisite and alternative consumption methods ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly state exclusions, but the context is sufficient for an agent to choose this over 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable context beyond annotations by detailing the output structure (category-bucketed examples with tool+argument shape), the live catalog source, and the optional topic parameter behavior. No contradictions found.

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

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

The description is a single dense paragraph but is front-loaded with trigger phrases and immediate purpose. Every sentence adds relevant information, though it could be slightly more structured; the length is justified by the tool's complexity.

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

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

For a tool with no output schema and one optional parameter, the description covers purpose, usage triggers, parameter options, output format, and relationship to other tools. It is fully sufficient for an agent to decide when and how to invoke it.

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 documentation already covers the optional `topic` parameter with a full list of allowed values and the omit-for-spread behavior. The description repeats these same examples (e.g., 'finance', 'pharma') without adding new semantic meaning, so it does not raise the baseline score of 3.

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

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

The description clearly states the tool's purpose as the onboarding entry point for Pipeworx, returning category-bucketed example questions with the exact tool and argument shape that answers each. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying this unique role.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance. It also gives example trigger phrases and mentions meta-tools as learning targets, though it does not explicitly name alternative tools to avoid using.

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 meaningful behavioral context beyond the annotations: deactivation instead of deletion, ownership enforcement, and the availability of historical events. These details align with the annotations and deepen the agent's understanding of side effects.

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

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

The description is three concise sentences, each adding essential information: the action, the ownership constraint, and the non-destructive side effect. There is no wordiness or repetition of schema 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?

For a simple single-parameter tool with no output schema, the description covers all critical aspects: the operation, a key constraint, and the post-condition. The mention of recent_alerts ties it to the broader tool ecosystem, making it contextually 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 covers the only parameter (id) with a clear description. The tool description reinforces that the id must be your own subscription, adding a semantic constraint not explicitly in the schema, though it doesn't elaborate further on the parameter format.

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 cancels a subscription by its ID, with a specific verb and resource. It is easily distinguished from sibling tools like subscribe (opposite) and list_subscriptions (listing), making the purpose unambiguous.

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

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

The description provides clear context for use: canceling a subscription, with ownership constraints and a note that historical events remain available via recent_alerts. It does not explicitly name alternative tools, but the context is sufficient to guide when 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 provides rich behavioral context beyond annotations: it explains the SEC EDGAR/XBRL fast path, the grounded pipeline, the return verdicts and citations, and the tolerance behavior. The readOnlyHint and idempotentHint are consistent with the described verification operation, and no contradictions exist.

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 moderately long but well-structured with examples, usage, internal behavior, and outputs. Each sentence provides value, though it could be slightly trimmed without losing meaning.

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 the tool's purpose, input, outputs (including verdict types and citation), and when to use it. With no output schema, it adequately explains the return structure. It does not mention edge cases or limitations, but the verdict 'unsupported' implies handling for unverifiable claims.

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

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

Schema coverage is 100% with detailed descriptions for both 'claim' and 'tolerance_pct'. The description does not add significant new parameter semantics beyond what the schema already provides; the mention of 'exact percent-delta math' is a minor enhancement.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims, with multiple trigger phrases and a specific verb-resource pairing ('validate claim'). It distinguishes from sibling tools by focusing on verification rather than general Q&A, and explicitly states it replaces multi-step sequences.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the internal routing for financial vs. other claims. However, it does not name alternative tools or explicitly state when not to use it, leaving a small gap.

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