Neso

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

Annotations provide readOnly/idempotent hints. The description adds that API keys are passed through to Anthropic, default model is free Workers AI Llama, and returns per-model and combined views. No contradiction.

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

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

Three sentences, front-loaded with the core purpose, then key parameter detail, then use cases. 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?

No output schema, but description lists return fields. Annotations cover safety. Parameters are all described. Lacks error handling or rate limits, but acceptable for 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 3. Description adds meaning by specifying the free default model and explaining _apiKey usage for Anthropic. It also describes the return format, adding value beyond schema.

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

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

The description clearly states the tool probes LLMs for brand/product visibility and scores it 0-100. It distinguishes from siblings like ask_pipeworx or entity_profile by focusing on multi-model visibility audits.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). While it doesn't contrast with alternatives, the context is clear enough for an agent to differentiate.

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

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

The description adds behavior beyond the annotations (readOnlyHint, openWorldHint, idempotentHint): it explains that the tool routes across thousands of sources, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier. No contradiction with annotations, though it does not cover rate limits or authentication, but those are not required given 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 longer than typical but every sentence carries weight: it front-loads the key 'PREFER OVER WEB SEARCH' directive, then lists domains, examples, and sibling tool distinctions. It is organized logically and does not repeat what annotations already state, earning a 4.

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

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

The description covers the tool's purpose, usage triggers, routing behavior, return format (citation URIs), performance characteristics ('one fast call'), and when to escalate to alternatives. For a complex routing tool with no output schema, this is fully sufficient for an agent to select and invoke correctly. The only minor gap is absence of explicit error/edge-case behavior, but that is not critical.

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

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

The input schema already fully describes the question parameter and all six aliases, so the baseline is 3 even without description-level parameter detail. The description provides example questions (e.g., 'current US unemployment rate') that illustrate expected values, but it does not materially add to the schema's 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 opens with a clear directive: 'PREFER OVER WEB SEARCH...' and enumerates specific domains (SEC filings, FDA drug data, FRED/BLS, etc.), then explicitly states it routes questions to 5,407 tools and returns structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research for different scenarios.

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

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

It gives explicit when-to-use guidance: 'Use whenever the user asks...' with examples, plus 'START HERE for most questions — this is the default entry point.' It also provides clear alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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

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

Discloses experimental nature, live candidate testing, current equivalence to stable, and comparison against the stable router. This goes beyond the read-only/idempotent annotations by explaining the dynamic behavior of routings, which could affect results over time.

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

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

Four sentences, front-loaded with identity, current state, usage, and a warning. No fluff; each sentence contributes critical operational 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?

Despite no output schema, the description addresses the tool's current behavior, how it relates to stable, and that it's fully functional. It mentions 'same response shape' to cover return format by reference, making it sufficiently complete for a beta router.

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 six parameters (aliases for question). The description doesn't add parameter-level meaning beyond saying 'same arguments', but the schema fully defines the accepted aliases, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router with the same 5,407 tools, arguments, and response shape. It distinguishes from the stable sibling ask_pipeworx by its experimental routing status, making its purpose 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?

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router, providing direct when-to-use guidance. Also clarifies it's a full working router, not a limited preview, eliminating potential misuse.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: the extra LLM call cost, the refusal mechanism with specific refusal_reason values, and the strict extraction policy from tool results only. 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 a single dense paragraph but well-organized: it states purpose, process, output format, use cases, and cost trade-off. Every sentence adds value, but it could benefit from bullet points or shorter sentences for easier scanning. Still, it's informative without redundancy.

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

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

Given the complexity (routing across many tools, extraction logic, refusal handling) and the absence of an output schema, the description thoroughly covers success and failure return values, refusal reasons, and behavioral notes. It is complete enough for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% with aliases clearly documented. The description does not add parameter-level details, but the schema already fully explains the question parameter and its aliases. Baseline 3 is appropriate since the schema carries the load and the description adds no extra 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 identifies the tool as a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb ('ask') and resource ('Pipeworx'). It distinguishes itself from the sibling tool 'ask_pipeworx' by emphasizing that it extracts answers using ONLY the tool result, and it explicitly names the alternative 'ask_pipeworx' for casual lookups.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear when-not-to-use directive: 'prefer ask_pipeworx for casual lookups.' This directly addresses selection between siblings.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are supplemented with extensive behavioral details: low-confidence resolution short-circuit, closed market handling, wide-spread illiquidity note, cancellation rule parsing, fan-out examples, response shapes, and error fields like _fallback_attempted. No contradictions with annotations.

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

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

The description is long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that make it scannable. Each sentence adds information, though some details could be more concise. Front-loads key purpose and usage.

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

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

Despite no output schema, the description thoroughly documents response shape, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. It provides sufficient context for an agent to correctly interpret and use the tool's output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining depth's default value and when to use include_raw=true, and provides input examples for the market parameter. This extra context raises the score.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), output content (evidence packet + comparison), and use cases ('should I bet on X', etc.). This distinguishes it from siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description explicitly lists when to use the tool: for assessing bets, data, or edge. It does not explicitly state when not to use or list alternative tools, but the clear use cases and context implied by the description provide adequate guidance.

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

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

The description discloses beyond annotations: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted data, and includes citation URIs. No annotation contradiction.

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

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

The description is well-structured with examples and important guidance in all-caps, but it is slightly verbose. Each sentence adds value, so still effective.

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

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

Despite no output schema, the description adequately describes return value (paired data + citations, sorted by primary metric) and covers both entity types completely.

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

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

Schema coverage is 100%, but the description adds detailed context: for type it explains what data is pulled (revenue, net income, etc.), and for values it specifies formats and limits.

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 it performs side-by-side comparison of 2-5 companies or drugs, with examples like 'compare X and Y'. It clearly distinguishes from sequential lookups.

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

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

The description says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides query examples, making the usage context explicit.

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

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

The description goes far beyond the annotations by detailing the return packet structure ('verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation'), explicit gaps[] for unanswered facets, contradictions[] detection, hop fields, semantic excerpting behavior, and performance expectations (15-60s, up to ~90s). It also notes account requirements and tier limitations, providing rich behavioral context.

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

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

The description is long but every sentence earns its place: it front-loads the critical account requirement, then proceeds through core functionality, use cases, behavioral details, and performance. It is well-structured and dense with information without being redundant. For such a complex tool, the length is justified and 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, the absence of an output schema, and the need to explain return values, the description is exceptionally complete. It explains the findings packet, citation format, gaps array, contradictions, hop field, excerpting, and depth behavior, plus account prerequisites. It leaves no significant question about tool behavior unaddressed.

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

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

Schema coverage is 100% for both parameters (question and depth), so the baseline is 3. The description adds meaningful elaboration: it explains what kind of questions are suitable ('Broad/multi-part is fine'), and expands on the depth enum values beyond the schema's one-liner, describing quick/standard/thorough in terms of facet counts, hops, gap-recovery, and contradictions scanning. This adds genuine value over 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 function: 'Grounded multi-source research across Pipeworx's 1403 STRUCTURED data sources... in ONE call'. It explicitly distinguishes from siblings by saying 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups or current news. Specific verbs and resource scope are present, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and gives direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also includes account prerequisites and fallback instructions, covering both appropriate and inappropriate use 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description adds value by detailing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' This goes beyond the annotations, though it could mention pagination limits.

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

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

The description is front-loaded with the purpose, then lists domains, then explains return value and usage order. Every sentence adds value, but the list of domains is somewhat lengthy. Still, it's well-structured and avoids redundancy.

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

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

Given the tool has no output schema, the description adequately explains what is returned (tools with names, descriptions, schemas) and how to use it. It covers purpose, usage context, and return format sufficiently for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with all parameters described, including aliases and examples. The description adds semantic context by specifying the query as a 'natural language description' and providing example tasks, which is more helpful than the schema alone. However, the schema already covers the parameter details, so the increment is moderate.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, financials, etc.), making it distinct from sibling tools like search_within or neso_search_datasets. It also explicitly says 'Call this FIRST when you have many tools available and want to see the option set,' differentiating its role as a tool discovery mechanism.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and advises to call it first. However, it does not explicitly state when not to use it or provide alternatives, though the context implies it's for exploration rather than direct answers.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds detail on parallel execution, specific return fields, patent soft-fail, and data sources. No contradiction, and adds useful context beyond annotations.

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

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

Description is informative but slightly verbose. Every sentence adds value, listing example queries, data sources, and return fields. Could be more structured (e.g., bullet points) but remains clear and front-loaded with use cases.

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, so description must explain return values. It does so thoroughly: lists CIK, filings with URIs, fundamentals sorted by period, patents with sunset caveat, news with fallback, and LEI. Covers main aspects but lacks detail on limits or pagination.

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 coverage is 100%, so schema itself documents parameters. Description adds value by clarifying that names are not supported and directing users to resolve_entity, and explains the value format (ticker or zero-padded CIK).

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 starts with clear example queries and states it provides a holistic cross-source profile of a US public company. It explicitly distinguishes from sibling tools by advising preference over chaining single-source lookups and references resolve_entity for name resolution.

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

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

Description clearly indicates when to use the tool (holistic view, one parallel call) and when not (if only have a name, use resolve_entity). Could be more explicit about alternatives like compare_entities or deep_research, but current guidance is strong.

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 include destructiveHint: true and idempotentHint: true. The description confirms the destructive nature and adds context about clearing sensitive data, enhancing transparency beyond annotations.

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

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

Two sentences with no wasted words. The action is front-loaded, followed by usage context and related tools. Highly efficient.

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

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

Given the single parameter, absence of output schema, and presence of annotations, the description fully captures the tool's purpose, usage, and pairing, leaving no gaps.

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

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

With 100% schema coverage, the input schema already describes the 'key' parameter. The description does not add additional parameter details, so baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Delete a previously stored memory by key.' It specifies verb, resource, and method, distinguishing it from sibling tools like 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly provides when to use ('context is stale, task is done, clear sensitive data') and mentions related tools ('Pair with remember and recall'), offering clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it fetches the page and extracts data, confirming non-destructive behavior. No contradictions, and the description adds useful process details.

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

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

The description is concise (about 60 words) and front-loaded with the core purpose. Every sentence adds value: purpose, process, output format, and use cases. No wasted words.

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

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

Despite no output schema, the description explains the output format (standard llms.txt markdown, single text blob) and where to deploy it. It covers the process, input, and output completely for this tool's complexity.

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

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

Schema coverage is 100%, so parameters are fully described in the schema. The description adds 'Full URL' and 'Maximum number of link entries' but does not provide additional semantics beyond what the schema already offers. 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 verb (generate), the resource (llms.txt file), and the purpose (help AI crawlers index the site). It distinguishes from siblings like scan_competitor_ai_presence by focusing on llms.txt generation specifically.

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

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

The description explicitly lists use cases: '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 provides clear context, though it doesn't explicitly mention when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that it returns specific fields and defaults to active subscriptions, which is useful context beyond annotations.

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

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

Two sentences without any fluff. The first states purpose and output, the second gives usage guidance. Efficient and well-structured.

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

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

For a simple tool with one optional param and no output schema, the description explains what is returned and when to use it. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, and the description does not add significant new meaning about the parameter beyond what the schema provides. 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?

Clearly states it lists active subscriptions and specifies the returned fields. It is distinct from sibling tools like subscribe/unsubscribe, though no explicit differentiation is made.

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

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

Explicitly recommends using it before adding more subscriptions or to find an id to cancel, providing clear context. Does not mention when not to use or alternatives, but sufficient for the simple 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 indicate readOnlyHint=true and idempotentHint=true, so the tool is safe. The description adds value by detailing the return fields (resource_id, name, format, datastore availability, last_modified) and the condition on datastore_active for further querying, providing context beyond annotations.

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

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

The description is a single informative sentence followed by an example. No wasted words; every sentence adds value. It is front-loaded with the core purpose.

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

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

For a tool with one parameter, no output schema, and comprehensive annotations, the description covers all necessary aspects: input source, output fields, and follow-up usage. It is complete and well-integrated with sibling 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% with a description for the 'id' parameter. The description adds meaning by providing an example usage and linking to neso_search_datasets for obtaining the id, which helps the agent understand where the parameter value comes from.

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 resource 'resources (data files/tables)' and clearly distinguishes from siblings like neso_search_datasets and neso_query_data by stating the input comes from neso_search_datasets and the output is used for neso_query_data.

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

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

The description guides the agent to use this tool to list resources before querying data with neso_query_data, and mentions the prerequisite of neso_search_datasets. It implicitly says when to use (to find a resource_id with datastore_active) but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations by specifying it returns 'demand in MW at each cardinal point with start/end times' and mentions default limit behavior. No contradictions with annotations.

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

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

The description is extremely concise yet informative: two sentences capturing purpose and scope, plus an example call. It is front-loaded and directly addresses the tool's function.

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 lacks detail on the return format or structure beyond 'demand in MW at each cardinal point'. Since there is no output schema, more context about the response shape would improve completeness.

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

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

Schema coverage is 100% with one parameter (limit) already described. The description adds an example call and mentions default value, but does not provide additional semantic meaning beyond 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 clearly identifies the tool as retrieving the GB day-ahead national electricity demand forecast from NESO, specifying the resource (demand forecast), action (retrieve), and scope (next day, cardinal points). It differentiates from sibling tools like neso_query_data and neso_search_datasets by focusing specifically on demand forecasts.

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

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

The description provides example queries ('what is tomorrow's UK electricity demand') to indicate typical use cases, and implies usage context for demand forecast retrieval. However, it does not explicitly state when to use this tool over siblings or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns field names/types plus records, which is useful but does not disclose behavioral traits beyond what annotations provide. No contradictions.

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

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

The description is three sentences, front-loaded with the primary action, lists key features concisely, and includes a relevant example. No extraneous content; every sentence adds value.

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

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

Given 6 parameters with nested objects and no output schema, the description explains the return format (fields + records) and provides an example. It does not cover error handling or pagination details beyond offset/limit, but overall is sufficient for an agent to use the tool effectively.

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

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

The input schema has 100% description coverage for all parameters. The description adds a brief summary ('exact-match filters', 'full-text query') and an example, but does not significantly enhance understanding beyond the schema provided. Baseline 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 it queries rows from a NESO GB energy dataset resource by resource_id, and lists examples like electricity demand and wind forecasts. However, it does not explicitly distinguish from sibling tools like neso_dataset_resources or neso_demand_forecast, so the purpose is clear but not fully differentiated.

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

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

The description implies usage context by mentioning resource_id from neso_dataset_resources, but does not provide explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The example shows typical usage but no when-not-to-use criteria.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive behavior. The description adds value by detailing the return fields (slug/id, title, summary, resource count), which is not in annotations.

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

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

The description is a single concise paragraph that front-loads the tool's action, provides examples, and avoids redundancy. Every sentence earns its place.

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

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

Given the tool's low complexity (2 optional params, no output schema, rich annotations), the description fully covers its purpose, usage, and return format, leaving no significant gaps.

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

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

Schema coverage is 100% with both parameters described. The description adds an example usage but does not significantly enhance parameter semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool serves to search NESO open data for UK electricity grid datasets, listing specific data types and the returned fields. It differentiates from sibling NESO tools like neso_query_data or neso_demand_forecast by being the general search entry point.

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

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

The description implies usage when one needs to find datasets via keywords, and provides example queries, but it does not explicitly state when not to use it or compare to alternatives like neso_dataset_resources or neso_demand_forecast.

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=false, etc.), the description adds valuable behavioral context: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also informs about the team's reading habits and roadmap impact. 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 concise and front-loaded, using a single paragraph that covers purpose, usage, constraints, and tips without redundancy. Every sentence adds value.

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

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

Given the tool's moderate complexity (3 parameters including a nested object and enum) and no output schema, the description is complete. It covers all necessary aspects: usage, constraints, behavioral notes, and parameter hints. No output schema is expected for a feedback 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 clear descriptions for each parameter and enum values. The description adds extra guidance like 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It provides specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by being explicitly for feedback.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises what not to do: 'don't paste the end-user's prompt.' This clearly differentiates it from other tools.

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

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

Annotations already indicate read-only, idempotent, safe. The description adds crucial context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and that it's self-aggregating. No contradictions.

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

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

Concise with front-loaded summary sentence, followed by bulleted use cases and additional details. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one parameter and rich annotations, the description covers data source, privacy, caching, and use cases. It does not detail the exact return structure, but that is acceptable without an output schema.

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

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

Schema description coverage is 100% with the 'window' parameter having a clear enum description. The tool description reiterates the windows but adds minimal new meaning, so baseline 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 that the tool returns top tools, top packs, and total call volume over a window, specifying the resource (Pipeworx trending data) and distinguishing it from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate trends.

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

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

Explicitly lists three concrete use cases and provides guidance on window selection (shorter for hot now, longer for steady-state). Lacks explicit when-not-to-use or alternative tools, but the context is clear enough.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds critical behavioral context: semantic anchor for cross-event pairs (Jaccard similarity ≥0.30), partition filter for placeholder slugs, fill check against CLOB depth, and response structure. No contradictions.

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

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

The description is thorough and well-structured with sections, but slightly verbose. Front-loaded with main purpose, every sentence adds value, but could be slightly more concise.

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

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

Despite no output schema, the description fully explains response fields (opportunities[], partition_check{}, fill check results) and even references polymarket_fill_risk for custom sizing. Provides enough context for an AI to use the tool correctly.

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

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

Both parameters (event, topic) have schema descriptions, and the high-quality description adds examples of valid inputs (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and notes that full URLs are accepted for event. Coverage is 100%.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending scan, event mode, topic mode) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit instructions for each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. Recommends event for specific markets and topic for cross-event scanning. Also warns against trading when realizable_edge_pp ≤ 0.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral detail (cached 1h, model families, edge calculation, knob effects, diagnostics) 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 thorough but verbose; it packs extensive detail into a dense paragraph. While well-structured, it could be more concise for quick comprehension.

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 the response structure (by_segment, fed_candidates, _diagnostics), caching, and filtering logic, making it self-contained and complete.

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

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

Schema coverage is 100% with detailed descriptions. The description adds contextual grouping and tradeable-edge logic (e.g., min_liquidity, max_spread_pp) beyond schema, justifying above baseline 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 explicitly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, clearly distinguishing it from sibling tools like polymarket_edge_tracker or polymarket_arbitrage. Purpose is specific and actionable.

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

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

The description sets clear context ('what should I bet on today') and implies discovery use case, but does not explicitly state when not to use or name alternatives beyond the sibling list. Still, guidance is strong.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully supported. The description adds rich behavioral context: output structure (tracked[], expired[], snapshot_dates[]), decay calculation details (computed on absolute value, negative for SELL YES), and limitations (60-day snapshot TTL, no intraday data). No contradictions.

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

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

The description is information-dense but front-loads the core purpose. Every sentence adds value, though it could be slightly more concise. The structure is logical: purpose, output explanation, limitations.

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 two simple parameters, no output schema, and supportive annotations, the description fully explains what the tool returns (tracked, expired, snapshot_dates) and its limitations (TTL, not intraday). It is comprehensive 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 both parameters described. The description adds default values and clamp range for 'days', which is helpful but not essential. It explains the meaning of 'window' as snapshot family. Baseline 3 is appropriate since the schema already does 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers specific questions about edge duration and decay, distinguishing it from the sibling tool 'polymarket_edges' which likely provides current edge snapshots.

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

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

The description implies usage for analyzing how long edges have existed and their decay trend, with examples like 'a fresh wide edge and a 3-week-old wide edge are different trades.' However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.

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

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

Adds substantial behavioral context beyond annotations: describes walking the order-book ladder, returning fields like top_of_book, vwap_fill_price, slippage_pp, verdict, and warns about partial basket fills converting arbs into unhedged directional positions. No contradiction with readOnlyHint=true.

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

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

The description is detailed but every sentence adds value; uses capitalization and dash lists for structure. Slightly long but justified by tool 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?

Comprehensively covers both modes, output fields, and risks (thin_legs, forced_directional_risk) despite no output schema. Provides enough context for an agent to use 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 meaning: explains default side for basket (auto from partition sum), interprets size_usd differently for single-market and basket, and clarifies that one of market or event is required.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why theoretical overround may not be capturable on thin books.

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 read-only and idempotent. Description adds extensive context on safety fields (compatibility_warning, temporal_alignment, skipped counters) and conditions for meaningful spreads, far exceeding annotation coverage.

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

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

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value; front-loaded with purpose. Information-dense but not verbose.

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

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

Despite no output schema, description fully explains response fields (spread[], compatibility_warning, temporal_alignment). Covers all necessary context for a complex cross-venue 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 has 100% coverage with descriptions for all 3 parameters. Description adds value by listing exact topic values, providing examples for explicit parameters, and explaining override 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison with explicit modes and safety handling.

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 explains when to use topic shortcuts vs explicit parameters, warns that pre-mapped topics often return compatibility warnings, and advises that real spreads are rare.

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 no contradiction. Description adds value by stating scoping per identifier (anonymous IP, key hash, account ID), which is beyond annotations.

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

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

Two sentences, no wasted words. Front-loaded with core action 'retrieve a value'. Each sentence provides essential information: operation, use case, scoping, and sibling relationship.

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 param, no output schema), the description thoroughly covers retrieval, listing, scoping, and integration with siblings. No gaps remain.

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

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

Schema coverage is 100% with one optional 'key' parameter. Description adds meaning: explains that omitting key lists all saved keys and gives concrete examples of stored values (ticker, address, notes), enriching 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?

Clearly states the tool retrieves a saved value or lists all keys. Uses specific verb 'retrieve' and resource 'value saved via remember'. Distinguishes from siblings 'remember' and 'forget' with examples of use cases like 'user's target ticker'.

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 describes when to use: to look up previously stored context. Instructs to omit key to list all keys. Mentions pairing with 'remember' and 'forget' for complete workflow. Provides clear context for selection among siblings.

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

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

Annotations already declare idempotent, read-only, and non-destructive. Description adds valuable context: mark_read behavior (flags events read to show newer ones on next call) and that polling works fine, enhancing the agent's understanding of side effects.

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

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

Single paragraph with no wasted words: front-loads purpose, lists key fields, explains filtering and mark_read, and notes polling compatibility and alternative access. Every sentence adds value.

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

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

For a tool with no output schema, the description covers return fields (source, uri, payload) and explains mark_read. Mentions alternative access. Lacks details on limit defaults or pagination, but is nearly complete for a filtered-list tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies mark_read behavior, providing meaning beyond the schema.

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

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

The description explicitly states 'Pull fired events from your subscription feed' with specific verb and resource. It details return fields (source, citation_uri, raw event payload) and filtering options, clearly distinguishing it from sibling tools like list_subscriptions or subscribe.

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

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

Provides clear context on when to use filters (type, since) and how mark_read affects subsequent calls. Mentions an alternative access method (HTTP GET) for scripts/dashboards. Lacks explicit exclusions but gives solid usage guidance.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description adds rich behavioral details: parallel fan-out to multiple sources, GDELT-to-GNews fallback logic, USPTO soft-fail, and return structure. 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 relatively long but well-structured and front-loaded with purpose via natural language examples. Every sentence adds value, though some details (e.g., full source list) could be slightly more concise. Overall efficient for the complexity.

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

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

Despite no output schema, the description fully explains what is returned (changes[] grouped by source, total_changes, citation URIs). It covers fallback behavior and soft-failure for USPTO. Given the tool's complexity and external API dependencies, the description is comprehensive and leaves no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical guidance beyond schema: explains 'since' format with examples (ISO date and relative shorthand), recommends typical values, and clarifies that 'type' only supports 'company'. This adds real value for correct parameter usage.

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

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

The description clearly states it provides a change feed for a company over a time window, with specific verb+resource ('change feed for a company'). It distinguishes from sibling entity_profile by explicitly advising when to use that tool instead.

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

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

The description gives clear context on when to use (for 'what's new' queries), suggests typical 'since' values ('30d' or '1m'), and explicitly recommends entity_profile for static profiles. It lacks explicit 'do not use' scenarios but provides adequate guidance for correct 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 declare idempotentHint=true and destructiveHint=false. Description adds context about scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated), and that it's a key-value store. However, it doesn't explicitly state overwrite behavior for same key, which would be helpful.

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

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

Four sentences, each serving a distinct purpose: function, when to use, storage details, and companion tools. No wasted words. Front-loaded with the core action.

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

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

Given no output schema, the description covers purpose, usage scenarios, storage behavior, and scope. It does not describe return value (e.g., success confirmation), but for a simple write operation this is acceptable. Completeness is high 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 coverage is 100% with good descriptions. The tool description reinforces parameter usage with examples ('subject_property', 'target_ticker') and clarifies that value can be 'any text', adding value beyond schema. Baseline 3, bumped for illustrative 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 clearly states 'Save data the agent will need to reuse later' with specific verb and resource, and distinguishes from siblings like recall and forget by mentioning them explicitly. Examples of stored data (resolved ticker, target address, etc.) further clarify purpose.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and what not to do ('so you don't have to look it up again'). Also directs pairing with recall and forget for complementary operations, giving clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that each call cascades through several lookup endpoints internally and replaces manual lookups, providing useful behavioral context without contradicting annotations.

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

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

Front-loaded with core purpose, uses bullet-like structure for types, and is informative without extraneous detail. Slightly long but justified by the complexity of the tool's output.

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 input format, output for each type, and internal behavior. No output schema, so description must explain returns, which it does thoroughly. Annotations cover safety. Fully complete given tool complexity.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds examples for each type, explains return values (ticker+CIK for company, RxCUI for drug), and mentions auto-disambiguation, significantly enhancing schema info.

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

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

Description explicitly states 'resolve a user-spoken NAME to the canonical/official identifier', gives examples like 'What's the ticker for...', and lists supported entity types, clearly distinguishing from siblings like entity_profile or compare_entities.

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

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

Directly instructs 'Use FIRST whenever you have a name but need an ID', which is strong guidance. Lacks explicit when-not-to-use or alternatives, but the context of sibling tools makes the use case clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that the tool internally calls ai_visibility_check, ranks results, and returns score/confidence/signal density. This provides process-level transparency beyond the annotations, though it could mention that results may vary over time (implied by openWorldHint).

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 explains what the tool does and how, the second gives a use case and output summary. Every sentence is essential, no redundant phrasing, and the key action is front-loaded. Excellent conciseness.

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

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

Given no output schema, the description covers return values (ranked list with score, confidence, signal density). Input requirements are clear (2-8 entities, with first as subject). Use case and process are well explained. No missing information for a tool of this complexity.

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

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

The input schema has 100% description coverage, already documenting entities (including that the first is the subject), models, _apiKey, and context. The description restates entities as 'your brand + N competitors' and the purpose of ranking, but adds no new syntactic or semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'compare' and 'scan' with the resource 'AI visibility across multiple entities'. It explicitly positions the tool as a side-by-side comparison that probes each entity with ai_visibility_check, ranks results, and identifies most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (likely generic comparison).

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and a sample question. It references the sibling tool ai_visibility_check, implying when to use this aggregated version. However, it does not explicitly state when not to use this tool (e.g., if only a single entity is needed) or contrast with compare_entities.

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

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

Discloses beyond annotations: composite fan-out, graceful degradation, timeouts for first bundlephobia measurement, and partial failure behavior. No contradiction with readOnlyHint/idempotentHint.

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 single paragraph with all essential information in the first sentence. Efficient despite length due to high information density. Slight room for structural improvement.

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?

Fully describes return fields, error handling, and ecosystem constraints. No output schema, so the description carries the full burden, which it meets comprehensively.

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

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

Schema coverage is 100%, and the description adds value by specifying version format (e.g., '18.3.1'), scoped packages, and default behavior (latest version). Minor redundancy but helpful.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages, combining license, advisory, and bundle size data. It distinguishes well from siblings by naming its specific data sources and use case.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and when not to (non-npm ecosystems go to a different tool). Provides concrete context for 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 declare safe, read-only, idempotent behavior. The description adds important details: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K) with truncation and flagging, and that passages include offsets for verification. No contradictions.

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

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

The description is concise yet packed with essential information. It starts with the core purpose, then usage guidance, then technical specifics. Every sentence serves a purpose without redundancy.

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

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

Given the moderate complexity (3 params, no output schema), the description covers all needed aspects: purpose, usage, behavioral details, parameter hints, and output characteristics (passages with offsets and scores). It leaves no major gaps for the agent to infer.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by providing example queries for the 'query' parameter and clarifying the purpose of offsets in the output. It does not repeat schema details but enhances understanding.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the input (text and query) and output (top-N passages with offsets and scores). It distinguishes itself from siblings by focusing on searching within already-fetched data, not on fetching or grounding.

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

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

The description explicitly tells when to use this tool ('when the record is too big to cram into the prompt') and how it complements a sibling tool ('Pairs with ask_pipeworx_grounded'). This provides clear guidance on appropriate use 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?

The description adds significant behavioral context beyond annotations: authentication requirements, delivery channels with caps/verification, webhook auto-disable after failures. No contradictions with annotations.

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

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

The description is a single dense paragraph with clear front-loading of purpose. Every sentence adds useful information, though length could be slightly reduced.

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

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

Given the tool's complexity (multiple types, delivery channels, no output schema), the description covers prerequisites, type-specific parameters, delivery details, and error handling comprehensively.

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

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

Schema coverage is 100%, but the description elaborates each parameter with examples and usage details (e.g., sec_8k items meaning, webhook HMAC signing). It adds substantial value.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (OAuth account), lists supported types with examples, and mentions delivery options. It lacks explicit when-not-to-use or direct alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns category-bucketed example questions drawn from the live catalog, and explains the tool's role as an onboarding entry point. 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 somewhat lengthy (multiple sentences) but well-structured: starts with example queries, explains returns, then usage. Every sentence adds value, though it could be slightly more concise without losing depth.

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 role as an onboarding entry point with many sibling tools and no output schema, the description is very complete. It covers purpose, usage, parameter, and when to use it. The mention of meta-tools (ask_pipeworx, entity_profile, etc.) provides necessary context 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%, baseline 3. The description adds meaning beyond the schema by explaining the parameter's role: 'pass topic to focus' and listing example values ('finance', 'pharma', etc.). This clarifies usage context beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions. The verb 'suggest questions' and the title 'What Can I Ask Pipeworx?' precisely convey the function. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on generating ideas rather than executing queries.

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

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

Explicit instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also specifies calling with no arguments for full spread or with topic to focus. This provides clear context for when to use the tool versus alternatives.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds crucial details: ownership enforcement, deactivation (not deletion), and preservation of historical events. This enhances understanding beyond annotations.

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

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

Two concise sentences: first states action and mechanism, second details behavior. No wasted words, front-loaded with key purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully explains behavior, side effects, and constraints. No gaps remain.

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 the only parameter (id as subscription uuid returned by subscribe) with 100% coverage. The description adds context by noting the id comes from 'subscribe', linking tools meaningfully.

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 'Cancel a subscription by id,' specifying the verb, resource, and mechanism. It distinguishes well from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. However, it doesn't contrast with alternatives like 'forget' or 'recall', though the constraint itself is helpful.

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

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral context: two pipelines (SEC EDGAR fast path and grounded pipeline), exact percent-delta math, verdict types, return fields with citations, and that it replaces multiple sequential calls. 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 front-loaded with purpose and examples, but is somewhat lengthy. Every sentence adds value, covering different claim types and return format. It could be slightly more concise, but structure is clear with quotes and logical flow.

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

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

Given the tool's complexity (multiple pipelines, no output schema), the description is remarkably complete. It explains verdict types, return values with citations, and reasoning. It covers all necessary behavioral aspects for an agent to understand what to expect.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds valuable context: for 'claim' it gives natural-language examples; for 'tolerance_pct' it explains the default behavior, range, and use case for hallucination detection, significantly enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example intents like 'fact check' and 'verify the claim that…', and distinguishes between company-financial claims and other factual claims, which differentiates it from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives detailed context on claim types and processing pipelines, but does not list explicit alternatives or when not to use it, though sibling tools like ask_pipeworx_grounded might overlap.

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