Datagov Il

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that Anthropic calls incur charges via user's own key and that default is free Workers AI. 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?

Single paragraph of 4 sentences, each carrying essential info: purpose, default model, conditional API key, return format, use cases. No fluff.

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

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

Despite no output schema, description adequately describes return structure (per-model fields + combined view) and scoring range. Includes typical use cases. No missing information for a probe tool of this complexity.

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

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

Schema has 100% coverage with good descriptions for all 4 parameters. Description adds extra context: default model for 'models', optional nature of _apiKey, and that 'context' disambiguates entities. This is a meaningful addition 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 probes LLMs for knowledge about an entity and scores visibility 0-100 per model, with a default model and optional Anthropic via API key. It distinguishes from siblings like entity_profile and scan_competitor_ai_presence by focusing on cross-model visibility scoring.

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

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

Explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to provide _apiKey (only if probing Anthropic). However, it does not contrast with similar sibling tools like scan_competitor_ai_presence, leaving some ambiguity.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable context: routing to a specific sub-tool, returning structured answers with stable pipeworx:// citation URIs, and being a single fast call. However, it does not mention error cases, rate limits, or authentication requirements, which are minor omissions.

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

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

The description is front-loaded with the key message ('PREFER OVER WEB SEARCH') and structured with examples and alternative tool guidance. However, it is somewhat verbose with repetitive phrases (e.g., 'works on every tier, one fast call') and a long list of example domains. Could be tightened without losing clarity.

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

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

Given the tool's complexity (routing to many sources) and lack of an output schema, the description adequately explains input and usage but falls short on output details. It mentions 'structured answer with pipeworx:// citation URIs' but does not specify the format, fields, or confidence levels, leaving ambiguity about what the agent will receive.

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 all parameters described as aliases for 'question.' The description provides examples and clarifies the type of input expected, but does not add significant new parameter-level semantics beyond what the schema already indicates. Baseline 3 is appropriate per the scoring guidelines.

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 answers factual questions using a vast database of verified sources, routing to appropriate sub-tools. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by specifying use cases. The verb 'ask' combined with 'routes to the right one of 4,774 tools' makes 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 explicitly advises to prefer this tool over web search for most factual queries and provides concrete 'when to use' and 'when not to use' guidance with alternatives. It says 'START HERE for most questions' and specifies stepping up to ask_pipeworx_grounded for evidence-based answers or deep_research for multi-source queries.

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

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

Adds significant context beyond annotations: return format with refusal reasons, cost of one extra LLM call, and that it extracts answers only from tool results. 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?

Well-structured and front-loaded with purpose. Every sentence adds essential information without redundancy. Length is appropriate for the complexity of the tool.

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

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

Despite lacking an output schema, the description covers return format, refusal reasons, use cases, and cost. Completely informs agent about what to expect and when to use.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by noting aliases (query, q, prompt, etc.) and providing usage context, but schema already documents these.

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?

Describes itself as a 'hallucination-resistant answer mode' for high-stakes reads, explicitly distinguishing from sibling 'ask_pipeworx' which is for casual lookups. Uses specific verb-resource pairing and clarifies scope.

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

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

Explicitly states when to use: when answers will be quoted, cited, or acted on and must not invent facts (financial, legal, medical). Also recommends sibling for casual lookups, providing clear alternatives.

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

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

The description richly discloses behaviors beyond annotations: fan-out logic, classifiers, short-circuiting on low confidence, closed market handling, cancellation rule parsing, and illiquid spread warnings. This adds substantial value without contradicting the readOnlyHint or idempotentHint 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 lengthy but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence provides critical detail; no redundancy exists. It earns its length 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?

Despite no output schema, the description comprehensively explains all output fields (market, analysis, evidence) and edge cases (low confidence, closed markets, wide spreads, cancellation rule, news fallback). It covers the full context needed for correct invocation.

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

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

Schema coverage is 100% with descriptions, but the DESCRIPTION adds context about parameter purpose (e.g., depth levels explained with evidence source counts) and examples (e.g., include_raw default vs. true payload sizes), improving 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies acceptable inputs (slug, URL, question) and outputs (evidence packet + comparison), and the examples distinguish it from siblings like polymarket_edges.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes detailed examples and classifiers, though it does not explicitly mention when not to use it or compare against siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), specific fields (revenue, net income, etc.), handling of off-calendar fiscal years, and citation URIs. No contradictions.

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

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

Front-loaded with common query patterns. Each sentence adds value, but the description is slightly long. However, given the need to explain two entity types, the length is justified.

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

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

Covers purpose, input details, output (paired data + URIs), behavioral constraints, and replaces many sequential lookups. No output schema, but description sufficiently explains return value structure.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds further meaning: explains that 'values' are tickers/CIKs for company and drug names, provides examples (AAPL, ozempic), and notes sorting by primary metric.

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?

Explicitly defines the tool's purpose: side-by-side comparison of 2-5 companies or drugs. Uses specific verbs like 'compare', 'rank', 'head-to-head'. Clearly distinguishes from sequential single-entity lookups and sibling tools like entity_profile.

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

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

Provides explicit usage patterns ('Compare X and Y', 'X vs Y', etc.) and directs to prefer this tool over sequential lookups. Gives concrete examples for each entity type (company/drug) and what data is pulled.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds value by explaining the returned structure (resources) and instructing which fields to inspect for further actions. No contradictions.

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

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

Two sentences: first defines purpose, second gives actionable guidance. Every word earns its place. Front-loaded and efficient.

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

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

For a simple 1-param tool without output schema, the description adequately explains the response structure and provides follow-up instructions. No gaps.

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

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

Schema coverage is 100% and parameter description is already clear ('id or slug' with example). Description adds minimal additional parameter info, 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 retrieves a full dataset record by id or slug, including resources. It specifies the underlying CKAN function and distinguishes from sibling tools like datastore_query 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 context for using the output to decide next steps (querying via datastore_query). It doesn't explicitly state when not to use, but the guidance is clear and practical.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond these by specifying the data source (CKAN datastore_search), the prerequisite (datastore_active), and the encoding (Hebrew/UTF-8). There is no contradiction with annotations; in fact, 'Read' aligns with readOnlyHint.

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 extremely concise with two sentences. The first sentence states the core action, and the second covers prerequisite and data encoding. Every word adds value, and it is well 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 rich annotations and fully described schema, the description covers the essential context: what the tool does, the prerequisite, and a data encoding note. The output format is not described, but as a standard CKAN query, the agent may infer it. Slightly more detail on return structure would improve completeness.

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 5 parameters have descriptions in the schema (100% coverage), so the description does not need to add parameter-level detail. The description provides overarching context (Hebrew encoding, prerequisite) but does not enhance individual parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states 'Read actual table rows from a resource via CKAN datastore_search', providing a specific verb (Read) and resource (table rows). It distinguishes this tool from siblings by mentioning the CKAN datastore_search mechanism and the prerequisite 'datastore_active=true', which is unique among the given 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 gives clear context on when to use: only for resources with datastore_active=true, and advises to get resource_id from dataset_details. It also notes that field values are often Hebrew (UTF-8), which informs query construction. However, it does not explicitly mention when not to use or suggest alternatives, though siblings are mostly unrelated.

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

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

Adds significant behavioral context beyond annotations: account requirement, depth limitations, parallel processing, gaps array, stable citations, non-open-web nature, expected latency (15-60s), and behavior when topic not in catalog (empty gaps). No contradiction with annotations.

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

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

The description is fairly long but every sentence is informative and necessary. It front-loads the most critical information (account requirement) and provides structured guidance. A minor redundancy (mentioning 'free' and 'paid plan' could be tightened) but overall efficient.

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

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

Given the tool's complexity (2 params, no output schema), the description thoroughly explains what to expect: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps array. It covers limitations, alternatives, and performance, leaving no obvious gaps.

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

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

Schema coverage is 100%, but description adds valuable meaning: explains enum values for depth (quick=3, standard=5, thorough=8) and clarifies that question can be broad/multi-part. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from sibling tools like ask_pipeworx (single lookup) and explicitly notes it is not open-web 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?

Provides detailed guidance on when to use (broad/multi-part questions over structured data) and when not to (breaking news, single lookup), including explicit alternatives (ask_pipeworx). Also covers account requirements and depth plan limitations.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds value by explaining it returns full input schemas with examples and that results are ready to call directly without a second lookup, which goes beyond the annotations.

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

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

Two sentences with a list of examples. The second sentence is somewhat long but packs useful information. Could be slightly more concise but overall efficient.

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

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

Given no output schema, the description compensates by describing the return structure (top-N tools with names, descriptions, full schemas, examples). Covers usage context and what to expect adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema already provides for parameters; it mentions aliases but those are also in the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and provides specific examples (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by emphasizing discovery and that it returns full schemas ready for direct invocation, with instruction to call it first.

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 recommends usage when browsing or discovering tools ('Use when you need to browse, search, look up, or discover what tools exist') and advises to call it first. Lacks explicit 'when not to use', but context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations, such as the patent source sunset (USPTO PatentsView API May 2025) and soft-fail behavior, and details the fan-out across multiple data sources. No contradiction with annotations.

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

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

The description is well-structured, starting with example invocations and then explaining functionality. It is slightly lengthy but front-loads the most important use cases. Every sentence adds value, though it could be trimmed slightly.

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 profile) and lack of output schema, the description is fairly complete. It lists all returned data fields (CIK, filings, fundamentals, patents, news, LEI) and mentions the patent soft-fail. It covers input constraints and fallback behavior. Minor omission: no mention of output format or URI scheme details.

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: it explains that the 'type' parameter is currently restricted to 'company', and that 'value' can be a ticker or zero-padded CIK with concrete examples ('AAPL', '0000320193'), and clarifies that names are not supported. This adds useful context.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific examples (e.g., 'Tell me about X', 'research Acme') and distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' The verb+resource is precise.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies acceptable inputs (ticker or zero-padded CIK) and directs users to resolve_entity for names, clearly delineating when to use this tool vs alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is beyond what annotations provide. No contradiction.

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

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

Two sentences, no wasted words. Front-loaded with the primary action and followed by usage guidance and siblings.

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 (1 param, no output schema), the description covers purpose, usage context, and behavioral implications comprehensively.

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

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

Schema coverage is 100% with one parameter described. The description does not add meaningful details beyond the schema beyond reiterating 'by key'. Baseline 3 is appropriate.

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

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

The description clearly states the action (delete), resource (previously stored memory), and method (by key). It distinguishes from siblings like 'remember' (store) and 'recall' (retrieve) by mentioning them as paired tools.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and implicitly when not to use. Also explicitly recommends pairing with 'remember' and 'recall', guiding the agent on alternatives.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it fetches page, extracts title/description/key links, emits markdown. No contradictions.

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

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

Three sentences: purpose, process, use cases. Every sentence adds value. Front-loaded with clear action.

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

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

For a 2-param tool with no output schema, description covers input, process, and output ('single text blob'). Sufficient for agent to understand and invoke.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions default and max for max_links, which is already in schema description. Adds minimal extra value.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file'. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on producing the standard file for any URL.

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

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

Explicitly lists use cases (getting client's site indexed, drafting for own project, auditing competitor). Does not explicitly state when not to use or mention alternatives, but context is clear.

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

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

Annotations already provide strong safety cues (readOnlyHint, idempotentHint, destructiveHint). Description adds little beyond naming the underlying CKAN method; no details on result structure or pagination.

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

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

Single sentence with essential information and useful parenthetical about CKAN. No wasted words.

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

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

For a simple list tool with no output schema, the description covers the resource and source. Could mention that it returns a list of groups, but annotations cover safety adequately.

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% (limit parameter fully described), so baseline 3 applies. Description adds no additional meaning to parameters beyond schema.

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

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

The description clearly states it lists thematic groups/categories on data.gov.il, with a specific reference to CKAN group_list, distinguishing it from sibling tools like list_organizations.

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?

No guidance on when to use this tool versus alternatives; no when-not or context for selection among siblings like list_organizations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no further behavioral context beyond the data source and CKAN reference. It doesn't disclose pagination behavior, rate limits, or other traits.

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

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

Single sentence, front-loaded with purpose, no unnecessary words. Every part 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 low complexity (1 param, no output schema), the description adequately states purpose and source. However, it omits what the output looks like (e.g., list of organization names/IDs), which would be helpful for an agent 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 coverage is 100% with the 'limit' parameter already described. The description does not add any meaning beyond what the schema provides, so 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?

Clearly states it lists publishing organizations (ministries/agencies) on a specific platform (data.gov.il) and references the underlying CKAN function (organization_list). Distinguishes from siblings like 'list_groups' by specifying the resource 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?

Describes what the tool does but provides no guidance on when to use it versus alternatives such as 'list_groups' or 'search_datasets'. No mention of prerequisites or when not to use.

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

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

Annotations already declare readOnlyHint, destructiveHint, etc. Description adds that it lists active subscriptions and returns specific fields, which is consistent but does not significantly extend behavioral knowledge 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?

Two sentences, front-loaded with purpose and return fields, no unnecessary words. Efficient and clear.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, and return fields. Annotations further complete the 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% and the parameter has a description. The tool description adds that it lists 'active' by default, which aligns. Baseline 3 is appropriate.

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

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

The description clearly states the action ('list'), resource ('subscriptions'), scope ('caller's active'), and lists the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit context: use to review subscriptions before adding more or to find an id to cancel. Does not explicitly state when not to use, but the context is clear and helpful.

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

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

Adds important behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and digests are read daily. Annotations are all false, so description fully informs about side effects and constraints.

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

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

Five sentences, front-loaded with purpose, followed by usage, constraints, and benefits. No filler, every sentence earns its place.

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

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

For a simple feedback tool with input schema and no output schema, the description covers purpose, when to use, what to include, limitations, and behavior. No gaps.

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

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

Schema coverage is 100%, but description adds extra guidance on parameter usage (e.g., explaining enum values in type, instructing to describe in terms of tools/packs). This goes beyond the schema descriptions.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from siblings as no other tool serves this feedback 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?

Explicitly says when to use each feedback type (bug, feature, data_gap, praise) and instructs not to paste end-user prompts. Also notes rate limits and free usage, providing clear context for appropriate use.

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

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

Builds on annotations (readOnly, idempotent) by adding that data is self-aggregating from CF analytics-engine, no PII, and caching strategy (5min-1h). Missing details on what 'top' means (e.g., by count?), but overall strong 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?

Description is three paragraphs but front-loaded with the main purpose. Every sentence is informative. No redundancy or unnecessary words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately explains return values (top tools, top packs, total call volume) and caching behavior. No gaps.

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

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

Parameter 'window' has schema with enum and description. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Clearly describes the tool's function: returning trending tools/packs and call volume over a window. Specific verb 'returns' and resource 'top tools, top packs, total call volume'. Distinct from siblings like 'discover_tools' by focusing on current usage trends.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choice, aligning use case). Provides guidance on window selection: shorter windows for hotness, longer for steady-state. No explicit when-not-to-use, but context is sufficient.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds critical behavioral details: semantic anchor, partition filter, fill check, and response structure. No contradiction with annotations.

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

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

The description is detailed and well-organized with section-like labels, but it is somewhat lengthy. Some internal details (e.g., fill check logic) could be more succinct, but all information is relevant and well-structured.

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

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

Despite the complexity, the description is complete: covers all modes, parameter usage, internal checks, return format, and edge cases. The absence of an output schema is compensated by describing the response structure.

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

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

Schema coverage is 100%, but the description adds significant context: explains differences between `event` and `topic`, provides examples, and describes how each mode operates. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arb detection.

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

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

Explicit guidance on when to use each mode: no args for trending scan, `event` for specific markets, `topic` for cross-event scans. Includes recommendations, mode-specific behaviors, and conditions to avoid trading. Also references a related tool for custom sizing.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. Description adds substantial context: caching at KV level for 1h, response structure with diagnostics, Fed exclusion explanation, and edge calculation details. 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?

Description is lengthy but well-structured with bullet points for segments and response details. Front-loaded with purpose. Every sentence adds value, though some technical depth might be overwhelming; still appropriate for complexity.

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

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

Despite no output schema, description explains response structure (by_segment, fed_candidates, _diagnostics), caching behavior, and tradeable-edge knobs. Covers enough for an agent to understand inputs, outputs, and internal logic fully.

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 9 parameters are described in schema (100% coverage). The description adds significant meaning beyond schema: e.g., min_kelly explains it's half-Kelly and skips small opportunities; min_edge_pp notes it's net of slippage. Provides examples and rationale for defaults.

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

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

Description clearly states the verb 'scan' and resource 'Polymarket markets', with the purpose 'find opportunities where Pipeworx data disagrees with market price'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-data disagreement rather than intra-market arbitrage.

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

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

Explicitly states it's built for 'what should I bet on today' and details when to use (discovery without paging). Provides knobs for filtering tradeable edges. However, no explicit when-not or direct comparison to siblings is given, though context implies it for opportunity scanning.

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 and idempotent. The description adds significant context: it relies on daily snapshots, details response structure, explains decay computation from daily closes, and notes history limits (60-day TTL). No contradictions.

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

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

The description is longer but well-structured: starts with core concept, then args, response format, and limits. Every sentence adds value, though minor redundancy exists in explaining trend calculations.

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 comprehensively details the response (tracked, expired, snapshot_dates), edge notation, trend labels, and limitations. This fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions. The description adds default values (14 for days, '1wk' for window), clamp range (2-30) for days, and context for window options, providing meaning beyond the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry, answering a specific question about edge age. It distinguishes from sibling tool polymarket_edges by focusing on historical tracking rather than current edges.

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

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

The description contrasts a fresh wide edge with a 3-week-old one, implying when to use this tool for historical context. It provides explicit limits, but does not directly state when to use alternatives like polymarket_edges.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and for basket mode returns theoretical_sum, realizable_sum, per-leg details, thin_legs, and directional risk. No contradiction with annotations. The description provides transparency beyond what annotations convey.

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

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

The description is somewhat lengthy but well-structured with clear headings for modes and bullet-like enumeration of return fields. Every sentence carries useful information; however, a slightly more concise presentation might improve readability without losing detail.

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

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

Despite lacking an output schema, the description fully lists all return fields, explains edge cases (thin legs, partial fills), and warns about dominant loss modes. It covers both modes comprehensively and addresses real-world usage pitfalls, making it complete for agent decision-making.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'side', it explains defaults and auto-behavior in basket mode; for 'market' and 'event', it associates them with respective modes; for 'size_usd', it specifies interpretation (max spend on buys, target proceeds on sells) and valid range. This greatly enriches the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly tells when to use it relative to sibling tools like polymarket_arbitrage and polymarket_edges, making it highly specific and differentiated.

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

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

The description provides explicit usage instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It details the required parameter (market or event), explains each mode, and warns about the risk of partial basket fills converting arb into directional positions. This gives clear when-to-use and when-not-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?

The description provides extensive behavioral context beyond annotations, including compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the note that pre-mapped topics are often not tradeable. No contradiction with annotations.

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

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

The description is structured with clear sections and is front-loaded with the core purpose. While lengthy, every sentence adds value, and it avoids redundancy.

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

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

Despite lacking an output schema, the description thoroughly explains all response fields (prices, spreads, compatibility, temporal alignment, skipped counters). It covers what the tool returns and the meaning of safety fields.

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

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

Schema coverage is 100%, and the description adds value by explaining the meaning and override behavior of kalshi_event_ticker and polymarket_event_slug, as well as listing the pre-mapped topic 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 states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on inter-venue comparison.

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

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

The description explains two usage modes (topic shortcuts vs explicit event pairs) and discusses when spreads are meaningful, including compatibility warnings. However, it does not explicitly state when to use alternative tools like the single-venue 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 cover read-only, idempotent, non-destructive traits. Description adds value by mentioning scoping and pairing with remember/forget, no contradictions.

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

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

Three sentences, front-loaded with main action, no wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema), description covers all needed: purpose, usage, scoping, and sibling relations.

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

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

Schema coverage is 100%. Description adds meaning by explaining that omitting the key lists all saved keys, beyond the schema's description.

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

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

The description clearly states the tool retrieves a saved value via 'remember' or lists all keys when omitted, distinguishing it from 'remember' and 'forget' siblings.

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

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

It explicitly notes when to omit the key argument (to list all keys) and indicates the scope (per identifier), but lacks explicit when-not or alternative guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains the effect of mark_read (flagging events so next call shows newer ones), confirms polling suitability, and describes the return payload format. No contradiction with annotations (readOnlyHint, etc.).

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 (4 sentences), front-loaded with purpose, and each sentence adds essential information—return fields, filtering options, mark_read behavior, and polling note. No wasted words.

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

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

Despite no output schema, the description covers return format (source, citation_uri, raw payload), filtering parameters, and behavioral details (mark_read, polling). It also provides alternative access method, making the tool's context complete for an agent.

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

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

Schema coverage is 100%. The description reinforces parameter meanings (e.g., example for type 'sec_8k', explanation of mark_read's effect on subsequent calls) and adds context about return fields, adding value beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It distinguishes itself by mentioning specific return fields (source, citation_uri) and the alternative GET endpoint for scripts/dashboards, differentiating it from sibling tools.

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

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

The description implies usage for polling and provides an alternative endpoint, but it does not explicitly compare to sibling tools like 'recent_changes' or 'list_subscriptions' to guide when to use this tool over others. The guidance is helpful but not comprehensive.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds fallback behavior, soft-fail for USPTO, return structure (changes[] grouped by source, total_changes, citation URIs), and parameter formatting details.

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

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

The description is front-loaded with example queries and has a logical flow. It is somewhat lengthy but every sentence adds value. Minor improvement could be more conciseness.

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

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

Given the tool's complexity (multiple sources, fallbacks) and absence of output schema, the description covers return structure but could be more explicit about fields in each changes item. Still, it is largely 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?

All parameters are described in the schema (100% coverage), but the description adds value by explaining 'since' can be ISO or relative with examples, and 'value' can be ticker or CIK. However, the schema already provides basic descriptions.

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

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

The description clearly states the tool's purpose: a change feed for a company, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It differentiates from sibling 'entity_profile' by specifying that tool is for static profiles.

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

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

Explicitly provides query examples ("What's new with X", "latest on Y") and when to use alternatives ('Use entity_profile instead when you want the static profile'). Also explains fallback logic for GDELT→GNews.

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

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

Discloses memory persistence behavior per user type (authenticated vs anonymous) beyond annotations, with no contradictions.

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

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

Four sentences, front-loaded with purpose, no wasted words, well-structured.

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

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

Covers purpose, usage, behavioral details, and relationships to sibling tools, complete for a simple 2-param tool with no output schema.

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

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

Schema coverage is 100%, but the description adds value with naming conventions and context about scoping. Baseline 3 is elevated due to meaningful addition.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using specific verbs and resource (save key-value pairs). It distinguishes from siblings like recall and forget.

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

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

Explicitly says when to use (discover something worth carrying forward) and how it relates to recall and forget, providing clear alternatives and context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining internal cascading behavior ('each call cascades through several lookup endpoints internally') and that it replaces multiple manual lookups, 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?

Description is front-loaded with examples and use cases, and is structured by type. While slightly long, every sentence adds value and it remains efficient for the information conveyed.

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

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

Given no output schema, the description fully explains return values for each type, including citation URIs. It also mentions the internal cascading behavior, covering behavioral complexity adequately for an AI agent.

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

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

Schema description coverage is 100%, but the description significantly enriches semantics by detailing what each type returns (e.g., for company: ticker, 10-digit CIK, company name, citation URI; for drug: RxCUI, ingredient, brand, citation). It also explains valid input formats for 'value' beyond the schema's brief description.

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

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

Description clearly states it resolves a name to a canonical identifier, with concrete examples like 'What's the ticker for...' and specifies supported types ('company', 'drug'). It distinguishes from sibling tools by noting it replaces 2-3 manual lookups.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to use. It does not explicitly mention when not to use, but context implies alternatives like 'compare_entities' or 'entity_profile' for other purposes.

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

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

Description reveals that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This adds beyond annotations (which only declare read-only, idempotent). No contradiction with annotations.

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

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

Four sentences front-loading purpose, then process, use case, and output. Every sentence provides unique value; no redundancy or 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?

No output schema, but description specifies return: ranked list with score, confidence, signal density per entity. Could be more structured (e.g., format), but adequate for a comparison 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?

Despite 100% schema coverage, description adds crucial meaning: entities ordering (first is subject), models defaults and dependencies, context examples. This significantly aids correct invocation.

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

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

Description clearly states verb ('Compare', 'Probes') and resource ('AI visibility across multiple entities'). Explicitly distinguishes from sibling for single-entity probes. "Compare AI visibility across multiple entities side-by-side."

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

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

Description provides clear use case: competitive AI-marketing audits. Implies when to use (side-by-side comparison) and mentions ordering convention. Does not explicitly state when not to use, but sibling differentiation is implicit.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool fans out to external APIs, that bundlephobia's first measurement can take 5-30 seconds, and that partial failures degrade gracefully with sources_failed listing timeouts. This is comprehensive.

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 paragraph that front-loads purpose and then provides necessary details. While long, every sentence adds value for a complex tool. Minor improvement could be breaking into bullet points, but it's still concise relative to information density.

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

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

Given the tool's complexity (composite, external APIs, partial failures, no output schema), the description thoroughly explains return data (summary block, advisories, links, alternatives), behavior (graceful degradation, timeout), and ecosystem scope. Nothing critical is missing.

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

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

Schema coverage is 100%, but the description adds context: scoped packages are accepted, version defaults to latest when omitted. This enhances understanding beyond the brief schema descriptions.

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

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

The description clearly states the tool does a composite check for npm package safety, popularity, and size, combining deps.dev and bundlephobia. It specifies the verb (check), resource (npm package), and scope (one call), distinguishing it from siblings.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and notes the NPM-only limitation, directing other ecosystems to a different tool (deps.dev:version). This provides clear when-to-use and when-not-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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing strong safety and behavior characteristics. The description adds value by clarifying the return format ('titles/descriptions, mostly Hebrew') and the query language flexibility, going beyond what annotations alone convey.

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

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

The description is exceedingly concise at two sentences, with no wasted words. It front-loads the core purpose and critical details about return content and language support.

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?

While no output schema exists, the description covers the primary return type ('matching datasets with titles/descriptions') and language aspect. It misses details like sorting or filtering behavior, but those are addressed in the schema. Given the tool's simplicity and sibling context (e.g., dataset_details), the description is adequately 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?

With 100% schema description coverage, the input schema already fully documents all parameters. The tool description does not add any additional parameter-specific information beyond what the schema provides, meriting 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 verb 'Search' and the specific resource 'data.gov.il catalogue (CKAN package_search)'. It also mentions what is returned ('matching datasets with titles/descriptions') and the language capabilities ('mostly Hebrew', 'Hebrew or English'), distinguishing it from sibling tools like dataset_details or datastore_query.

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 that this tool is for searching the data.gov.il catalogue but does not explicitly state when to use it versus alternatives like dataset_details or datastore_query. No 'when not to use' guidance or comparisons are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. No contradictions.

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

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

Single paragraph that efficiently communicates purpose, use case, technical details, and pairing. No wasted words. Every sentence serves a purpose. Well 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?

Even without an output schema, the description explains what is returned (top-N passages with character offsets and similarity scores). Also covers constraints (200K char cap, truncation flag). Complete enough 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 baseline is 3. Description adds context beyond schema: provides example queries for the query parameter, specifies default and range for limit, and mentions the max char limit for text. Adds moderate value.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' – a specific verb+resource pair. It explains the use case (record too large for prompt) and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded for a different workflow.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also provides guidance on when not to use implicitly (if it fits, don't need this). Mentions an alternative tool: ask_pipeworx_grounded, showing how they pair. This helps agent decide.

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

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

Annotations only indicate idempotent and non-destructive; the description adds extensive behavioral context: the need for a Pipeworx OAuth account, type-specific parameter structures, delivery channel details (feed always on, email, SMS with verification and daily cap, webhook with HMAC signing and auto-disable after failures). 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 packed with information but well-structured: purpose first, then requirements, types, and delivery details. Every sentence adds value, though it is dense. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple subscription types, delivery options, no output schema), the description is highly complete. It covers purpose, prerequisites, parameter configurations, delivery limitations, and returns the subscription ID. No gaps are evident.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds significant value by providing examples and nuances for each type (e.g., sec_8k items codes, polymarket_edge topic) and for delivery channels (always-on feed, optional channels with constraints). Despite high coverage, the description enriches understanding.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation, not listing, removal, or pulling.

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 specifies prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist) and details supported types and delivery options, helping the agent decide when to use. However, it does not explicitly contrast with sibling tools like list_subscriptions for listing existing subscriptions.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds that it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, enriching understanding 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 somewhat long but well-structured, front-loading with common queries and using parentheses for categories. It is efficient given the complexity, though could be slightly more concise.

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

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

With only one optional parameter, no output schema, and rich annotations, the description adequately explains the tool's purpose, output nature, and use cases. It is complete for the tool's simplicity.

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 description for the optional topic parameter. The description lists valid topics and clarifies behavior when omitted, adding value beyond the schema.

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

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

The description clearly states it returns example questions in categories for onboarding. It distinguishes from siblings like discover_tools by explicitly targeting 'what can I ask?' and 'getting started' queries.

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 advises to use this tool first when unfamiliar with Pipeworx's capabilities. It explains optional topic filtering and fallback to full spread. While not listing exclusions, it provides clear context for when to use.

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

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

Annotations indicate destructiveHint=false; the description adds that the row is deactivated (not deleted) and that historical events stay available. This is valuable behavioral context beyond annotations.

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

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

Two sentences, no filler, all information is relevant 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?

Given one parameter, no output schema, and annotations covering safety, the description provides enough context: input, behavior, ownership, post-call state. Minor gap: no mention of error cases or idempotency despite idempotentHint.

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

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

Schema already describes the 'id' parameter with high coverage. Description adds ownership and source context (returned by subscribe), but no additional parameter details beyond schema.

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

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

The description starts with 'Cancel a subscription by id,' using a specific verb (cancel) and resource (subscription). It clearly distinguishes from the sibling tool 'subscribe'.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context for when to use. Does not mention alternative tools for other scenarios, but is sufficient.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint) are comprehensive. The description adds behavioral context: returns verdict categories, extracted form, actual value with citation, percent delta, and underlying sources (SEC EDGAR + XBRL). No contradictions.

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

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

The description is well-structured: front-loaded with example trigger phrases, then purpose, then scope, then technical details. Each sentence adds distinct value, though slightly lengthy for a simple tool; still 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?

Despite a single parameter and no output schema, the description fully covers the tool's behavior: return format, supported domain, limitations (v1 company-financial claims), and efficiency benefits. No gaps for an AI 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 coverage is 100% from the description, meeting the baseline of 3. The description adds value by providing multiple natural-language examples of what the claim parameter should look like, enhancing understanding beyond the schema's description.

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

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

The description clearly states the tool's function: verifying natural-language claims against authoritative sources, with specific examples of user intents ('Is it true that…', 'fact check') and explicit differentiation from sibling tools by replacing a multi-step process.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and defines the scope (company-financial claims). It implies alternatives by noting it replaces 4-6 sequential calls, providing clear guidance on when to invoke.

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