Datagov Il

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

Beyond the annotations, the description adds important behavioral disclosures: the default model is free Workers AI Llama-3.3-70b, and passing `_apiKey` triggers direct Anthropic calls for which 'you pay Anthropic directly.' It also previews the response structure (per-model score, confidence, signals, raw_response), giving the agent expectations without contradicting annotations.

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

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

The description is three sentences with no filler, front-loading the core action first, then the default model/cost, return format, and use cases. Every sentence earns its place, making it highly scannable.

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

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

Given the tool's moderate complexity (4 params, optional API key, multiple models), the description covers essential invocation details: what it does, how to enable Anthropic, cost implications, and the shape of the response. It does not explain the combined view's structure or error cases, but with no output schema and full param schema coverage, this is a minor gap.

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

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

The schema already provides high coverage for all four parameters, so the baseline is 3. The description adds value by naming the exact default model ('Workers AI Llama-3.3-70b') and implying the optionality of models, though most parameter details are handled by 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 explicitly states the tool 'Probe one or more LLMs for what they know... and score visibility (0-100) per model,' providing a specific verb and resource. It distinguishes this tool from siblings like ask_pipeworx by focusing on LLM knowledge scoring rather than simple Q&A, making its purpose unmistakable.

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

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

The description lists concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that inform when to invoke it. It does not explicitly state when not to use it or name alternatives like scan_competitor_ai_presence, so guidance is clear but lacks exclusions.

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

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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context by explaining the routing mechanism, the verified sources, the structured return format with stable citation URIs, and the 'one fast call' performance trait. This goes beyond the annotations without contradiction.

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

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

The description is long but well-structured and front-loaded. The first sentence states the primary directive (prefer over web search), followed by domain examples, trigger phrases, usage guidance, and escalation paths. Every sentence contributes meaningful information, and the length is justified by the tool's complexity.

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

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

The description is complete for a complex tool with no output schema. It clearly states what the tool returns (structured answers with pipeworx:// citations), covers a wide range of use cases, and explains when to use alternative tools. The annotations further round out the safety profile, making the description comprehensive.

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

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

The input schema provides complete descriptions for the question parameter and all its aliases (100% coverage). The description does not add new parameter-specific semantics; it only offers example questions. Since the schema already defines the parameters thoroughly, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it routes factual questions to the most appropriate of 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its unique role 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 offers explicit guidance on when to use the tool, listing trigger phrases ('what is', 'look up', 'find') and giving concrete examples. It also explains when NOT to use it by directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part queries, 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial live-behavior context: 'candidate routing improvements enabled live whenever one is under test', 'No candidate is active right now... so this currently matches ask_pipeworx exactly', and 'Falls back to nothing — this IS a full working router, just the experimental edge.' These details explain potential variability, current state, and reassure that the tool is not a stub, which annotations cannot 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 dense but organized: it opens with the core identity, then explains beta status, current state, usage, and ends with a reassurance about functionality. Each sentence provides necessary information without repetition, though it's slightly longer than typical tool descriptions. The front-loading of 'Beta version of ask_pipeworx' ensures immediate context.

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 referencing 'same response shape' as ask_pipeworx, which is sufficient for an agent to infer return structure. It covers what it is, when to use it, current behavior (no active candidate), and the fact that it's fully functional. Minor gaps like error behavior or how to detect an active candidate are acceptable for a beta router 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?

The input schema has 100% coverage with clear descriptions for all 6 parameters, including the main 'question' parameter and its aliases. The description adds no additional parameter-level semantics, but because the schema fully documents parameters, the baseline of 3 is appropriate. No extra value beyond schema, but no deficiency either.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router (same 5,529 tools, same arguments, same response shape)', which clearly identifies it as an experimental routing tool with a specific verb (router) and resource (the same 5,529 tools). It distinguishes from sibling tools by framing itself as beta and noting it 'currently matches ask_pipeworx exactly', making its purpose and relationship to the stable router unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This clearly implies ask_pipeworx is the stable alternative and directs the agent to use this beta when experimental routing is desired. It lacks explicit 'do not use when stability is critical', but the implication is strong enough for a 4.

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, the description details the internal behavior: 'picks the right tool from 5,529 across 1455 sources, fills arguments, fetches the data, then EXTRACTS the answer'. It also discloses the exact success/refusal response structure and refusal reasons, adding substantial context annotations cannot 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 dense and well-organized, front-loading with the essential purpose ('Hallucination-resistant answer mode'). Every sentence adds value—mechanism, return format, usage, cost tradeoff—with no fluff or repetition.

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

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

No output schema exists, so the description fully compensates by explaining success and refusal return shapes, including refusal_reason enum values. It also covers use cases, cost, and how it differs from ask_pipeworx, making it complete for a single-required-parameter tool.

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

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

Schema coverage is 100% with all parameters (including aliases) documented in the input schema. The description does not need to elaborate on parameters; it only implies 'question' as the core input. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' that extracts answers using only tool results, distinguishing it from the sibling ask_pipeworx. It specifies the same routing but adds the grounded extraction behavior, making the tool's purpose and differentiation unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists example domains. It also gives the alternative: 'prefer ask_pipeworx for casual lookups' and highlights the cost tradeoff of one extra LLM call.

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

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

The annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: fan-out in parallel, resolver confidence levels, low-confidence short-circuit status, closed-market blocking, wide-spread tradeability flag, and cancellation-rule parsing. It even documents fallback behavior for GDELT 429s. This goes far beyond the annotation baseline.

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

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

The description is long but well-structured with clear all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Every section adds useful context for correct invocation and result interpretation. It is not as lean as a two-sentence description, but the length is justified by the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers response shapes for market, analysis, evidence, resolver contract, parent_event, news fields, safety statuses, and cancellation rules. It also includes fan-out examples by bet category. This is a thorough and complete description for a complex tool.

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

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

Schema description coverage is 100%, and the schema already documents all three parameters (market, depth, include_raw) with their types and defaults. The tool description reinforces the market parameter's accepted formats but does not add new meaning beyond the schema. Baseline 3 is appropriate given the high schema coverage.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It distinguishes itself from siblings like polymarket_edges or polymarket_arbitrage by framing use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.

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

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

Provides explicit use cases ('Use for...') and operational guidance (e.g., 'ALWAYS inspect these before trusting the analysis block', 'Check this before sizing sports/esports/event-occurrence bets'). However, it does not name alternative tools or state when not to use it, so it lacks explicit exclusions that would merit a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses concrete behaviors: it pulls from SEC EDGAR/XBRL and FAERS/FDA, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with pipeworx:// citation URIs. This adds substantial behavioral context that annotations alone do not provide.

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

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

The description is dense and information-rich, covering purpose, examples, usage preference, data sources, sorting, and return format in a compact paragraph. It uses space efficiently, though the all-caps "ALWAYS PREFER" and multiple examples make it slightly longer than strictly necessary, but no sentence is wasted.

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

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

Given the tool's complexity (two entity types, no output schema), the description is remarkably complete: it states exactly what the tool does, when to prefer it, what each type returns, and the output structure (paired data + citation URIs). It addresses edge cases like off-calendar fiscal years and sorting, leaving minimal ambiguity 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%, so the baseline is 3, but the description significantly enriches parameter meaning: it explains that type="company" pulls 10-K financial metrics and type="drug" pulls FAERS/FDA/trial counts, and provides value examples (tickers, drug names). It also clarifies edge cases like off-calendar fiscal year handling, exceeding what the schema offers.

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

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

The description opens with example queries ("Compare X and Y", "X vs Y") and explicitly states it performs "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." This clearly identifies the tool's purpose as a comparison tool and distinguishes it from single-entity lookups like sequential calls.

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

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

The description gives explicit guidance with "ALWAYS PREFER over sequential single-pack lookups when comparing entities," naming the alternative approach (sequential lookups) and setting clear usage context. However, it lacks an explicit 'when not to use' clause, though the limit to 2–5 entities and comparison-focused phrasing makes it implied.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important response semantics: how to interpret each resource's 'id' and 'datastore_active' fields to determine queryability. This is valuable context that annotations alone do not convey.

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

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

Two sentences: the first states the core purpose and scope, the second gives a practical tip. Front-loaded and free of waste.

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

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

With no output schema, the description sufficiently explains the return value ('full dataset record' including resources) and how to use the output for the next step. It is complete for a simple lookup tool with one parameter.

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

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

The single parameter 'id' is fully described in the schema (100% coverage). The description's mention of 'by id or slug' mirrors the schema, adding no new parameter-level detail. Baseline of 3 applies.

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

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

The description clearly states the tool returns a full dataset record by id or slug, referencing CKAN package_show. It explicitly includes resources, which distinguishes it from sibling tools like datastore_query that operate on rows.

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

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

The description provides explicit guidance: use this to get dataset metadata and resource IDs, then use datastore_query for row-level queries on resources flagged 'datastore_active'. This directly addresses when to use this tool versus the key alternative.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: the datastore_active prerequisite and the Hebrew/UTF-8 encoding note. These are not redundant with annotations and provide practical operational guidance.

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 efficient sentences deliver the core purpose and the key constraint without wasted wording. The critical action is front-loaded in the first sentence.

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 read-only annotations, full parameter documentation, and examples, the description covers the essential operational aspects. It omits return format details, but 'actual table rows' conveys the outcome. For a straightforward read tool, this is sufficiently complete, though a mention of the response structure would push it to 5.

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 already have detailed schemas. The description adds value by explaining Hebrew/UTF-8 for field names/values and instructing that resource_id comes from dataset_details, which helps construct valid queries beyond the schema's generic examples.

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

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

The description opens with 'Read actual table rows from a resource via CKAN datastore_search', a specific verb and resource. It clearly distinguishes the tool from metadata-only tools by emphasizing 'actual table rows' and noting the datastore_active=true condition.

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

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

The description provides a clear prerequisite ('Works only for resources with datastore_active=true') and directs users to get resource_id from dataset_details, implying a workflow. However, it does not explicitly name alternative tools or state when not to use this tool.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral traits: account/paid tiers, parallel routing to 5,529 tools, findings packet structure (evidence, confidence, source, fetched_at, citation), explicit gaps[] for unanswered facets ('never invented'), fetchable citation_uri, hop field, contradictions[] scanning, semantic excerpting, and expected latency. This far exceeds the annotation bar.

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

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

The description is long but densely packed with actionable information. It is front-loaded with the sign-in requirement and follows a logical flow: purpose, usage guidance, depth semantics, citation behavior, timing. While some details (e.g., hop field and citation_uri) are explained in adjacent sentences, the length is justified by the tool's complexity.

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

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

Given there is no output schema, the description thoroughly covers return values (findings packet with evidence, confidence, source, fetched_at, citation), behavior across depth levels, gaps handling, contradictions, and performance expectations. It accounts for edge cases (unstructured topics → empty gaps[]) and confirms citations are always fetchable. No critical information 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 already covers both parameters with 100% description coverage. The description adds value by elaborating on the 'question' parameter's applicability to broad/multi-part questions with example queries and by explaining depth levels' behavioral implications (quick/standard/thorough, gap recovery, contradictions, timing). Minor redundancy with enum descriptions, hence not a 5.

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 the tool does 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and distinguishes it from open-web search. It also contrasts with sibling ask_pipeworx for single lookups and breaking news, making the purpose and differentiation crystal clear.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and clearly directs alternatives for single lookups and current news ('For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also notes account requirements and the fallback when not signed in.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe, so the description's main contribution is the behavioral detail about returning top-N results with full input schemas and curated examples, plus the 'ready to call directly, no second schema lookup needed' note. This adds useful context beyond the annotations without contradicting them.

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

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

The description is a single, well-structured paragraph with three logical parts: what it does, when to use, and what it returns. The domain list is lengthy but informative, listing concrete examples that help the agent understand the tool's coverage. Every sentence earns its place, though it is slightly longer than strictly necessary.

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

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

Given the tool's simple search-based nature, the comprehensive schema, and the strong annotation set, the description is complete. It covers the return payload (top-N tools with names, descriptions, full input schemas with examples) and the callability of results. Since there is no output schema, this textual description fully compensates.

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

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

Schema coverage is 100% with detailed descriptions for all six parameters, so the description doesn't need to add parameter-level detail. The description's 'data or task' phrasing aligns with the 'query' parameter but adds no new semantics or syntax beyond what the schema already provides, warranting 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 'Find tools by describing the data or task' – a specific verb and resource. It further distinguishes itself from sibling tools by enumerating covered domains (SEC filings, financials, FDA drugs, etc.) and explicitly positioning itself as the discovery entry point, which is unique among the sibling list.

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 context: 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance, though it stops short of naming specific alternative tools for other cases.

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

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

Annotations already declare read-only/idempotent/non-destructive behavior. The description adds substantive behavioral context: parallel fan-out across multiple sources, returns specific fields with ordering, patents API sunset with soft-fail, and GDELT→GNews fallback. This exceeds what annotations provide.

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

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

Dense but purposeful; front-loaded with example intents and followed by structured results list and input constraints. Slightly verbose with multiple query examples, but each adds matching value for an AI agent recognizing user intent.

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

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

With no output schema, the description thoroughly explains return payloads (filings, fundamentals, patents, news, LEI), including URIs, sorting, and fallback behavior. Input format and unsupported names are also covered, making the tool self-contained 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% with both type and value described. The description reinforces these details with examples (AAPL, 0000320193) and restates the name-not-supported constraint, but adds no new semantic 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 identifies the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It provides concrete example queries and distinguishes it from chaining single-topic lookups and from resolve_entity for name-based input.

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 instructs when to use: ALWAYS PREFER for holistic company views rather than chaining SEC/XBRL/news lookups. Also states names are not supported and to use resolve_entity first, giving clear alternative and prerequisite guidance.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds useful context that the deletion targets 'previously stored memory' and is appropriate for clearing sensitive data, giving the agent a mental model of the behavior and consequences beyond the raw annotation.

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

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

The description is two sentences, front-loaded with the action, then provides usage guidance and a sibling pairing. Every sentence earns its place with no filler or redundancy.

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

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

This is a simple tool with one parameter, a clear deletion action, and annotations that cover safety (destructive, idempotent). The description fully explains what, when, and why, and there is no output schema to document. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, with the parameter 'key' clearly documented as 'Memory key to delete'. The description only adds 'by key', which does not provide additional semantic value beyond the schema. Baseline of 3 is appropriate per the rubric.

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

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

The description uses a specific verb 'Delete' with a clear resource ('previously stored memory by key'). It distinguishes itself from siblings by explicitly pairing with 'remember' and 'recall', making its role in the memory workflow unambiguous.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear guidance on when to invoke the tool and why, and the mention of pairing with remember/recall further clarifies its place among alternatives.

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

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

The description goes beyond the annotations (readOnly, idempotent, non-destructive) by explaining what the tool actually does internally: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output as 'a single text blob ready to drop at site-root/llms.txt,' which is useful behavioral context. 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 three sentences, front-loaded with the core purpose, then process, then use cases. Every sentence adds value, no redundancy or fluff. It is concise while covering key aspects.

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

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

For a two-parameter tool with no output schema and comprehensive annotations, the description is complete. It explains the input (any URL), the process, the output format, and common use cases. This is sufficient for an agent to decide when and how to invoke it.

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

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

The schema already provides 100% coverage of both parameters with descriptions for 'url' and 'max_links'. The description adds minimal semantic value beyond the schema, such as implying the URL is any site and mentioning the output format. Per the rubric, baseline 3 is appropriate when schema coverage is high.

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: 'Generate a production-ready llms.txt file for any URL' and details the process (fetches page, extracts title/description/key links, emits standard llms.txt markdown). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on generating the file itself, not just checking presence.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context on when to use the tool, though it doesn't explicitly mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the CKAN endpoint context ('CKAN group_list') but does not disclose behavioral details such as return format, pagination behavior, or whether authentication is needed. With strong annotations, the description does not need to duplicate safety traits, so a 3 reflects minimal added value beyond the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It contains the verb, resource, and technical context all in one line, which is ideal for a simple list 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?

For a simple read-only tool with one optional parameter and strong annotations, the description is nearly complete. It clearly states what is listed and the source. The only meaningful gap is the lack of return format detail (e.g., returns an array of group names), but given the tool's simplicity and CKAN context, this is not a severe shortcoming.

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

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

The schema has 100% description coverage for the single 'limit' parameter, including type, min/max, and default. The description does not mention parameters at all, so it adds no extra semantic value. Baseline is 3 because the schema already provides complete parameter meaning.

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

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

The description uses a specific verb ('List') with a specific resource ('thematic groups/categories on data.gov.il') and references 'CKAN group_list', providing clear scope. This distinguishes it from sibling tools like list_organizations by naming the data source and type.

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 explicit guidance is given about when to use this tool versus alternatives such as list_organizations or search_datasets. The CKAN group_list mention implies a direct API listing, but there is no stated context or exclusions, leaving the agent to infer usage.

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, and idempotentHint, so the description's added value is minimal. It clarifies the scope (ministries/agencies) and references the CKAN endpoint, but does not disclose return format, pagination behavior, or other operational details beyond the annotations.

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

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

The description is a single sentence that is direct and without redundancy. It includes essential context (data.gov.il, ministries/agencies, CKAN endpoint) while remaining tightly worded.

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

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

For a simple list tool with one optional parameter, the description combined with annotations and schema covers purpose, safety, and parameter semantics. No output schema exists, but the return type (a list of organizations) is implied by the tool's nature, making the description sufficient.

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

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

Schema coverage is 100%, with 'limit' fully described in the input schema. The description does not add any parameter-specific information beyond what the schema already provides, so the 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?

Description uses a specific verb ('List') and resource ('publishing organizations (ministries/agencies) on data.gov.il'), clearly distinguishing it from sibling tools like list_groups. The mention of 'CKAN organization_list' adds implementation clarity.

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

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

The description implies usage context (listing organizations on data.gov.il) but provides no explicit guidance on when to choose this over alternatives, nor any exclusions or prerequisites. Sibling tools like list_groups are not referenced for differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context by revealing the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it returns only the caller's subscriptions. This goes beyond annotations and is useful for the agent.

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

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

The description is two sentences: the first states the action and output, the second provides use cases. It is front-loaded, compact, and every sentence adds value without unnecessary wording.

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 (one optional parameter, no required fields), the description is complete. It lists return fields despite no output schema, covers the scope (caller's subscriptions), and includes use cases. Annotations round out the safety profile, so the agent has all needed 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% for the single include_inactive parameter, with a clear description in the schema. The tool description doesn't add extra meaning about the parameter, but it doesn't need to since the schema fully explains it. The description's mention of 'active subscriptions' implicitly reinforces the default behavior.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions'. It also lists the fields returned, which distinguishes it from other list tools like list_groups and list_organizations, and from subscribe/unsubscribe 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 explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for usage relative to sibling tools like subscribe and unsubscribe, though it doesn't explicitly state when not to use it or name alternative tools directly.

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

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

Annotations are all false, so description carries the full burden. It discloses rate limiting (5/day/identifier), free usage, no tool-call quota impact, the anonymous claim_token flow, and the expectation to describe issues in terms of Pipeworx tools/packs rather than end-user prompts. No contradictions found.

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

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

The description is long but each sentence provides distinct value: purpose, exclusions, usage examples, behavioral notes, and follow-up mechanics. It is front-loaded with the core purpose and then drills into specifics, earning its length despite being dense.

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

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

Despite lacking an output schema, the description explains expected outputs (claim_token when anonymous, later status via token), operational context (daily digests, rate limits), and edge cases (wrong MCP server). This is a complete picture for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but description adds substantial meaning beyond schema: it explains how to use claim_token for follow-up, advises not to paste user prompts, and clarifies that context fields (pack/tool/vertical) are optional but helpful. This enriches parameter understanding well 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: reporting broken/missing/needed things to the Pipeworx team. It goes beyond a simple verb+resource by enumerating specific feedback categories (bug, feature, data_gap, praise) and explicitly distinguishes itself from sibling tools by scoping only to Pipeworx-served tools.

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

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

The description provides explicit when-to-use guidance (bug, feature/data_gap, praise) and an explicit when-not-to-use exclusion (tools from other MCP servers). It also gives concrete follow-up guidance via claim_token and mentions daily digest review, making it exceptionally actionable.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable details: data is self-aggregating from CF analytics-engine, no PII is included, output is just (pack, tool, count), and results are cached for 5min-1h depending on window. This gives a clear picture of behavior and limitations.

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

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

The description is three sentences, each serving a distinct purpose: purpose, use cases, and technical details. It is front-loaded with the most critical information and contains no filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what is returned, the supported windows, caching behavior, and privacy implications. No important aspect is left unexplained.

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

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

The input schema already provides a complete description of the single parameter `window` (enum values and their meaning). The description merely repeats the window options without adding additional semantic depth, matching the baseline for full schema coverage.

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

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

The description opens with a specific purpose ('What other AI agents are calling on Pipeworx right now') and explicitly lists the outputs (top tools, top packs, total call volume). This clearly distinguishes it from sibling tools like discover_tools or 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 three concrete use cases ('Useful for: ...') that clearly indicate when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already guarantee read-only/open-world/idempotent safety, but the description goes far beyond: it discloses filtering thresholds (0.30 Jaccard, >3pp partition deviation, >20% placeholder fraction), how fill_check prices against CLOB depth, and warns that realizable_edge_pp ≤ 0 means 'do not trade it.' This richly adds behavioral context without contradicting the annotations.

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

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

The description is long but brilliantly structured: core purpose first, then mode-specific guidance, then filters/response/fill check. Each sentence delivers actionable detail (thresholds, examples, trade recommendations) with no fluff. Front-loading and logical sectioning earn the length.

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 the full operation lifecycle: input modes, output shape (opportunities[] with gap_pp, suggested_trade, partition_check fields), edge cases (skipped_low_similarity, placeholder filtering), and the crucial fill-check semantics for real-world tradability. Despite no output schema, the description leaves little ambiguity.

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

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

Input schema descriptions cover the basics, but the description adds deep semantics: accepted slug formats ('fed-decision-may-2026'), full URL acceptance, the internal workflow for each mode (walks child markets, runs comparator), and concrete example seed questions. This goes far beyond schema coverage.

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

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

Description is explicit and specific: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three modes (trending_scan, event-specific, cross-event topic scan) and differentiates from siblings by referencing polymarket_fill_risk for custom sizing.

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

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

Provides precise when-to-use guidance: 'use this if you know the specific Polymarket event' for event mode, 'use this if you want to scan related events across the platform' for topic mode, and explicit exclusion: 'For custom sizing use polymarket_fill_risk.' It also explains the advantage of cross-event mode over single-event mode.

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

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

Even with readOnlyHint=true, the description adds extensive behavioral context: it explains the three response segments, the filtering logic (e.g., placeholder-slug filter, partition >20% placeholder skipped), edge computation (net of slippage, Kelly caps), a 24h-move warning, caching behavior ("Cached 1h at the KV level keyed on all knobs"), and diagnostics for empty segments. This goes far beyond the annotations and provides critical behavioral transparency.

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

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

The description is long but front-loaded with the core purpose and organized with clear uppercase section labels (MODEL_DRIVEN, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Each paragraph adds essential functionality details for a complex tool. It is dense rather than redundant, so it earns a 4 rather than a 3 or 5.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure: top-level by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It details what each opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, etc.) and explains edge cases like empty segments. This is a complete picture for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful grouping and interaction context—e.g., "TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly." It also clarifies that min_kelly does not affect partition arbs, which is not obvious from the schema alone. This adds value beyond the schema, warranting a 4.

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

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

The description uses a specific verb and resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It clearly states the tool's purpose and scope, and distinguishes it from siblings by detailing the unique three-segment output (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and model families. This is not tautological or vague.

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

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

The description provides clear context for when to use the tool: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It implies this is the go-to tool for opportunity discovery. However, it does not explicitly name alternatives or state when-not-to-use, so it falls short of a full 5.

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

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

The description discloses substantial behavioral traits beyond the annotations: snapshot TTL (60 days), cache-miss behavior, decay computation from daily closes, and response structure (tracked, expired, snapshot_dates). These details deeply complement the readOnlyHint and idempotentHint annotations, enhancing transparency without contradiction.

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

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

The description is densely packed but well-structured, with a clear intro, argument list, response format, and limits. Each section provides essential information, though it is somewhat verbose. The front-loaded question and answer demonstrate excellent prioritization.

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 (time-series telemetry) and absence of an output schema, the description fully explains return fields, computation methods, and limitations. It covers edge cases like missing snapshots and TTL constraints, making it self-sufficient for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, with both parameters (days, window) already described adequately in the schema. The description repeats the defaults but adds minimal new semantic nuance. It mentions 'snapshot family' for window, which clarifies the value space, but does not significantly exceed the schema's existing documentation.

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 with a specific verb ('telemetry built from daily polymarket_edges snapshots') and answers a precise question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling tool polymarket_edges by focusing on persistence and decay rather than just fetching 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 clear context on when to use this tool, using the example of a fresh versus a 3-week-old wide edge. It does not explicitly name alternative tools or state when not to use it, but the usage context is strong and the LIMITS section helps set expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavior context: it reads live order-book depth, walks the ladder, computes VWAP/slippage, and returns a verdict. It also transparently discloses the risk of unhedged directional positions from partial basket fills, which is valuable beyond annotation hints.

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

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

The description is long but well-structured with SINGLE-MARKET and BASKET sections plus a final usage directive. Every sentence adds value, though the enumeration of returned fields could be trimmed slightly without losing essential behavior. Overall it is appropriately dense 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 absence of an output schema and the tool's complexity (two modes, multiple parameters, detailed outputs), the description covers all critical aspects: mode selection, parameter semantics, return fields, risk warnings, and relationship to sibling tools. An agent can confidently invoke the tool correctly without needing additional documentation.

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 beyond the schema. It explains that market and event are mutually exclusive modes, interprets size_usd differently in single-market vs basket (spend/target proceeds vs settlement notional), and clarifies side defaults per mode. This is rich semantic context that the schema alone does not convey.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from the sibling polymarket_arbitrage and polymarket_edges tools by focusing on fill risk and execution quality rather than opportunity 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 usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market vs basket mode and warns against partial farb conversions, giving clear context versus alternatives.

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

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

Beyond the read-only annotation, the description thoroughly explains compatibility_warning triggers, temporal_alignment, and skipped_cross_type counters, covering edge cases in detail. It also cautions that most pre-mapped topics return warnings, which is valuable behavioral insight. No contradictions with annotations.

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

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

The description is dense and long, but it is front-loaded with the core purpose and each sentence adds value – from modes to safety fields. Despite being a single wall of text, it is well-structured 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?

Despite lacking an output schema, the description fully enumerates the response shape, safety fields, and failure modes, making it self-sufficient for an agent to understand what will happen and why. It even covers the rarity of real spreads.

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

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

The schema already provides 100% parameter coverage, but the description adds meaning by explaining how topic shortcuts map to venues and how explicit overrides interact. This goes beyond the schema's individual field descriptions.

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

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

The description states it is a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' – a specific verb+resource that clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It also outlines two distinct modes of operation.

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

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

The description explicitly defines TWO MODES (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics often return compatibility_warning, giving clear context for when results are reliable. However, it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: scoping to an identifier, listing all keys when the argument is omitted, and its role in a save/retrieve/delete workflow. It does not contradict annotations.

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

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

The description is three sentences, front-loaded with the main action, and each sentence adds meaningful information (behavior, usage, scoping, related tools). 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 tool with one optional parameter, no output schema, and clear annotations, the description fully covers behavior, scoping, and relationships to remember/forget. It also implies the return behavior (value or list of keys), making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with a clear property description. The tool description goes beyond the schema by illustrating example key values ('user's target ticker, an address, prior research notes') and explicitly stating that omitting the key lists all keys, enriching the parameter semantics.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('Retrieve') and resource, and distinguishes from siblings by explicitly naming remember and forget as complementary tools.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier' and contrasts with re-deriving. It names alternatives ('Pair with remember to save, forget to delete'), though it does not explicitly list when not to use the tool, giving it a 4 rather than 5.

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

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

The description discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a write operation. This directly contradicts the readOnlyHint:true annotation, which claims the tool is read-only. Per the rubric, this is an annotation contradiction and must be scored 1.

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

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

The description is four sentences, front-loaded with a clear purpose, and each sentence adds meaningful info (payload, filtering, mark_read, polling/alternative). No fluff or repetition.

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

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

For a read tool with no output schema, the description explains the return payload (source, citation_uri, raw event payload), filtering options, the mark_read side effect, and even an alternative HTTP endpoint. It is sufficiently complete for an agent to use the tool correctly, with the schema covering parameter 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 all 5 parameters have descriptions. The description adds valuable examples ('e.g. sec_8k'), clarifies the ISO timestamp format, and explains the behavioral consequence of mark_read affecting subsequent calls. This goes beyond the basic schema definitions.

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

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

The description clearly states a specific verb ('Pull') and resource ('fired events from your subscription feed'), and explains what each alert carries (source, citation_uri, raw payload). This distinguishes it from sibling tools like recent_changes because it focuses on alerts from the persisted feed.

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 says 'Polls work fine' and recommends the HTTP endpoint (registry.pipeworx.io/alerts.json) for scripts and dashboards, offering an explicit alternative. It does not mention when to use this over sibling tools, but the polling context and alternative access provide clear usage guidance.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: it fans out to multiple sources, explains the GDELT→GNews fallback with rate-limit/5xx conditions, notes the USPTO soft-fail due to PatentsView API sunset, and describes the parallel call optimization. It also discloses the return structure (changes[] grouped by source, total count, citation URIs) and the supported `since` shorthand formats. This goes well beyond the annotation baseline.

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

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

The description is dense but every element earns its place: example queries, source fan-out, fallback logic, param formats, return summary, and sibling alternative. It is front-loaded with illustrative queries and remains a single coherent paragraph without redundancy or filler. For the tool's complexity, the length is justified 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?

With no output schema, the description fully explains the return structure (changes[], total_changes, pipeworx:// URIs). It covers all three parameters (with enum and formats), system dependencies (SEC EDGAR, GDELT/GNews, USPTO), fallback behavior, and the key alternative (entity_profile). The provided annotations plus this description give an agent everything needed to select and invoke the tool correctly in a complex domain.

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?

Although schema coverage is 100%, the description enriches parameter understanding by providing concrete examples for `since` (ISO date and relative shorthand '7d', '30d', '3m', '1y'), recommending '30d'/'1m' for typical monitoring, and clarifying `value` as ticker or zero-padded CIK. It also reinforces `type` as only company. This adds value beyond the schema's field descriptions, though the schema itself already handles the basics.

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

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

The description clearly identifies the tool as a change feed for a company, with concrete example queries ('What's new with X', 'updates on Acme'). It specifies the verb (fans out to SEC EDGAR, GDELT/GNews, USPTO) and resource (company changes over a time window). It also distinguishes itself from sibling tool entity_profile by explicitly stating when to use that alternative, which solidifies purpose clarity.

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

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

The description provides explicit guidance on when to use this tool (for time-boxed change monitoring) and when to avoid it in favor of entity_profile (for static profile regardless of window). It also includes example natural language queries and fallback behavior (GDELT preferred, GNews on failure), giving an agent strong contextual cues for appropriate invocation.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: key-value scope by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. It does not contradict annotations and provides extra details about data lifecycle, though it stops short of explaining overwrite behavior or failure modes.

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

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

The description is three sentences, front-loaded with the main action and purpose, followed by usage context and pairing information. Every sentence contributes unique value with no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage scenarios, persistence, and companion tools. It is complete enough for an agent to select and invoke correctly, though it leaves minor edge-case behaviors (like overwriting existing keys) unspecified, which is acceptable given the annotations and schema richness.

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 both 'key' and 'value' having descriptive examples. The description reinforces the parameter roles by illustrating typical keys and values, but does not add substantial new meaning beyond the schema. Thus a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Save') and resource ('data the agent will need to reuse later'), and it distinguishes from sibling tools by naming the paired operations (recall, forget). Concrete examples of use cases (resolved ticker, target address, user preference) further ground the purpose.

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

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

The description provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and differentiates contexts (authenticated vs. anonymous sessions, cross-conversation vs. cross-sessions). It alludes to alternatives by mentioning 'Pair with recall to retrieve later, forget to delete,' but does not explicitly state when not to use the tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses important behavioral details: identifier sources (SEC EDGAR, GLEIF, OpenFIGI), explicit handling of unresolved identifiers via an 'unresolved' field, and graceful degradation when external services are unavailable. It also mentions internal cascading through several endpoints, giving agents a clear picture of what happens under the hood.

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 verbose but efficient, packing many useful details into a single paragraph. The front-loaded example queries immediately signal the tool's purpose, and the structure logically progresses from usage to supported types to technical details. A slight deduct for length—it could be broken into bullets for readability—but every sentence contributes value.

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

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

With no output schema, the description needs to explain return values, and it does: identifiers are labeled by source, unresolved items are explicitly listed, and fallback behavior is described. It covers input formats, supported entity types, source endpoints, and failure modes, making it fully self-contained 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?

The schema already describes both parameters (type, value) with examples, but the description adds significant semantic depth: for 'company' it lists the full identity spine (CIK, ticker, LEI, FIGI) and the types of input accepted; for 'drug' it specifies the return format (RxCUI, ingredient, brand) and citations. This goes well beyond the schema's basic enum and string descriptions, fully compensating for any gaps.

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 resolves user-spoken names to canonical identifiers, with specific verbs and resources ('resolve a user-spoken NAME to the canonical/official identifiers'). It distinguishes itself from sibling tools like entity_profile by emphasizing identifier lookup as the primary purpose and including example queries that make the function unmistakable.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the supported types (company, drug) and what identifiers are returned for each, making it clear when to choose this tool over alternatives. The note about replacing 2-3 manual lookups reinforces its role as a preliminary lookup tool.

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

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

While annotations already cover read-only, open-world, idempotent, and non-destructive behavior, the description adds meaningful process details: it probes via ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. This goes beyond what annotations provide, illuminating the tool's internal workflow and output structure.

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

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

The description is four sentences, each serving a distinct purpose: core action, operational detail, use-case illustration, and output summary. It is slightly more verbose than the two-sentence ideal but contains no filler or repetition, making it efficient and well-structured.

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

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

With no output schema, the description appropriately states the return value ('ranked list with score, confidence, signal density per entity'). It also covers the multi-entity comparison context and the probe method, providing enough information for an agent to decide when to use the tool. Minor gaps like entity count limits are already in the 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 for all 4 parameters, including the special treatment of the first entity and the optional _apiKey. The main description only mentions 'your brand + N competitors' which echoes the entities parameter but adds no unique semantics beyond the schema. Thus 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 starts with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side,' which immediately distinguishes it from the single-entity sibling ai_visibility_check. It also details the mechanism ('Probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized'), leaving no ambiguity about what the tool does.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative scenario ('does Claude know about us as well as our competitors?'). It implicitly contrasts with ai_visibility_check for single entities, but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that the tool fans out to external services, degrades gracefully on partial failures, and may take 5-30s for the first measurement on a new version with sources_failed listing timeouts. This rich context helps set expectations.

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 dense paragraph but logically ordered: purpose, usage triggers, return content, limitations, and failure behavior. While each sentence carries necessary information, the overall length is slightly high; however, it remains readable and efficiently 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 lacking an output schema, the description enumerates the summary block fields and mentions per-advisory details, links, and alternative versions. It also covers ecosystem scope and error handling, making it fully sufficient 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?

The input schema already fully describes both parameters (package and version), including examples and the default behavior for version. The description does not add any additional parameter semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a composite check for 'should I add this npm package to my project' and specifies the exact data sources (deps.dev and bundlephobia). It is a specific verb+resource that distinguishes it from sibling research tools. The return fields are also listed, making the purpose unambiguous.

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

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

Explicit usage triggers are given ('is X safe / popular / small' or 'what does adding lodash cost me'). It also clearly states the NPM-only limitation and directs users of other ecosystems to deps.dev:version directly, providing an alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful context: returns titles/descriptions (mostly Hebrew) and accepts Hebrew or English queries. It does not disclose pagination or default limits, but the schema covers those details, so this is adequate though not rich.

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 only two sentences, front-loaded with the primary verb and resource, and includes key behavioral details without any filler. Every clause 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 tool's moderate complexity, a fully described schema, and rich annotations, the description is sufficient: it states the catalogue, what is returned, and language support. It does not explain pagination or filter behavior, but those are in the schema. The absence of an output schema is partially mitigated by the mention of titles/descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific value beyond the schema: it reiterates that queries may be in Hebrew or English, which is already in the query parameter description. No additional semantic clarification is provided.

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 ('Search') and the target resource (the data.gov.il catalogue via CKAN package_search). It also specifies the output (matching datasets with titles/descriptions) and language behavior, making its purpose distinct 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 the tool is for searching the data.gov.il catalogue and returns dataset metadata, providing clear context. However, it does not explicitly mention when to use this over siblings like dataset_details or datastore_query, nor any exclusions.

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

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

The description adds rich behavioral details beyond the readOnly/openWorld/idempotent annotations: it returns 'top-N passages with character offsets and similarity scores,' uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows,' and caps at '200K chars (longer inputs are truncated and flagged).' This is exactly the kind of non-obvious behavior an agent needs to know.

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

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

The description is compact (~120 words) and front-loaded with the core purpose. Each subsequent sentence builds on it: use case, output characteristics, integration with a sibling, and technical behavior. No fluff or repetition — 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?

With no output schema, the description compensates by specifying return details (passages with offsets and similarity scores), input constraints (200K cap, truncation flag), and integration pattern. Combined with the annotations covering safety, the description is fully sufficient for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond by giving real-world examples for 'text' (SEC 10-K, article) and 'query' (supply-chain risk), and clarifies 'limit' as 'top-N passages.' It also adds the important 200K-char constraint context, giving the agent a clearer mental model of parameter usage.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates from sibling tools like ask_pipeworx_grounded by emphasizing it operates on text the agent already has, not a broader knowledge base. Concrete examples (SEC 10-K, article) further reinforce the 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 the record is too big to cram into the prompt.' It also names a complementary alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' This gives clear when-to-use and workflow guidance, exceeding basic context.

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

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

Annotations declare idempotentHint=true, but the description says each call 'Returns the new subscription id', implying each invocation creates a new subscription. This is an annotation contradiction. Despite the rich behavioral details about OAuth and delivery channels, the scoring rule requires a 1 when description contradicts annotations.

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

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

The description is long but dense and appropriately structured. It front-loads the core purpose and then organizes supported types and delivery channels. Every sentence adds operational value, though it is more verbose than strictly necessary.

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

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

The description covers prerequisites, type-specific parameters, delivery channels, webhook security details, and the one-time return of the webhook secret. It is nearly complete, but the idempotency contradiction with annotations leaves a meaningful behavioral gap, preventing a top score.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: it gives examples for sec_8k, polymarket_edge, and fred_series parameters, specifies phone verification requirements for SMS, explains the 10/day cap, and details webhook HMAC signing and one-time secret return.

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 'Create a proactive monitoring subscription to a live-data event stream' and explicitly says it returns the new subscription id. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides strong usage context: supported subscription types with concrete examples, a hard prerequisite (Pipeworx OAuth account), and delivery channel options. It does not explicitly contrast with alternative tools, but the guidance is clear enough for an agent to decide when to use subscribe.

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

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

Annotations already mark it read-only/idempotent; description adds return-shape transparency: 'category-bucketed example questions' and 'drawn from the live catalog of thousands of tools,' plus the optional topic focusing behavior. No contradictions.

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

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

Dense but every sentence adds: natural-language triggers, entry-point purpose, return contents, invocation options, and when-to-use. It is front-loaded and appropriately sized for an onboarding 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?

For a simple 0-required-param tool with no output schema, the description supplies purpose, return detail, category list, parameter options, and usage timing. It is fully self-contained.

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 already documents allowed values; description adds only examples ('finance', 'pharma', 'betting') and the phrase 'full spread,' which is marginal. Baseline 3 holds.

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 opens with concrete user queries and explicitly names the tool as 'the onboarding entry point for an agent that just connected,' clearly distinguishing it from siblings like discover_tools. It specifies the deliverable: 'category-bucketed example questions' with 'exact tool + argument shape.'

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This tells the agent when to invoke it, though it doesn't explicitly list when-not alternatives, so 4.

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

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

The description goes beyond the annotations by disclosing the deactivation (not deletion) behavior, ownership enforcement, and the impact on historical events. This adds meaningful context that the annotations alone (readOnlyHint false, destructiveHint false) do not fully 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 two sentences long and immediately front-loads the core action. Every clause adds value: the action, the ownership constraint, and the deactivation side effect. No filler or redundancy.

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

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

For a simple one-parameter cancellation tool, the description covers the essential behavioral outcomes (deactivation, visibility of historical events). It does not describe the response format, but given the absence of an output schema and the low complexity, this is a minor gap.

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

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

The schema already provides 100% coverage for the single parameter 'id', including its type and source ('returned by subscribe'). The description only repeats 'id' without adding new semantic details, so it does not meaningfully supplement the schema.

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

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

The description opens with a specific verb+resource structure: 'Cancel a subscription by id.' It clearly distinguishes this tool from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action and the unique ownership constraint.

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

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

The description implies when to use this tool (when you want to cancel a subscription) and provides a key prerequisite: ownership enforcement means you can only cancel your own subscriptions. It also hints at a non-alternative by noting that deactivation keeps history accessible via recent_alerts, though it does not explicitly name alternatives or exclusion cases.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds crucial behavioral context: 'could_not_verify' means the check did not happen and must not be treated as evidence, 'unsupported' means no source was found, and it explains the return payload (verdict, value, citation, reasoning) and internal routing paths. This goes well beyond annotation hints.

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

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

The description is longer than average but front-loads examples and the 'use whenever' statement, followed by necessary routing and error-semantics details. There is some duplication of schema parameter descriptions, but every section adds functional value and it remains 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?

With no output schema, the description compensates by defining the verdict enum, explaining the distinction between error states, noting the inclusion of citations and reasoning, and covering both financial and non-financial claims. This is sufficient for an agent to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds actionable semantics: tolerance_pct overrides the tolerance implied by the claim wording, defaults are capped at 5, and setting 1–2 is recommended for hallucination detection. This provides meaningful guidance 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 opens with concrete natural-language examples and explicitly frames the tool as claim verification against authoritative sources, using specific verbs like 'verify' and 'fact check.' It clearly distinguishes itself from siblings by focusing on factual claim checking with verdicts, rather than open-ended research or data lookup.

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

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

It provides an explicit trigger condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other claims, and notes that it replaces multiple sequential calls. It does not explicitly name alternative tools or state when not to use it, but the context is clear.

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