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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds useful behavioral context by explaining that the tool routes to many internal tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotations, though it stops short of describing failure modes or rate limits.

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

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

The description is longer than average but every sentence contributes: preference over web search, domain list, routing behavior, trigger phrases, examples, and sibling routing. The most critical directive, 'PREFER OVER WEB SEARCH', is front-loaded. While it could be tightened slightly, the length is justified for a router tool that must guide tool selection.

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

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

The tool has a single natural-language parameter and no output schema, so the description appropriately explains that the result is a structured answer with stable pipeworx:// citation URIs. It also covers the full decision space among siblings, which is essential for correct invocation. The only minor gap is the lack of detail about edge cases (e.g., no data found), which is not critical for calling the tool.

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

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

Schema description coverage is 100%, and the schema already explains that the question parameter accepts natural language and lists aliases (query, q, prompt, text, input). The description reinforces this by giving concrete example questions, which helps the agent formulate valid inputs. Since the schema carries the parameter burden, the description adds only marginal semantic value beyond examples.

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

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

The description opens with 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates concrete domains such as SEC filings, FDA drug data, and economic statistics, making the tool's function unmistakable. It clearly states that it routes questions to 5,798 tools, fills arguments, and returns structured answers with citation URIs. This distinguishes it from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'START HERE for most questions' and 'Use whenever the user asks...' with trigger phrases like 'what is', 'look up', and 'get the latest'. It also names exclusions, directing users to ask_pipeworx_grounded for auditable answers, deep_research for broad synthesis, polymarket_* for prediction markets, and plain web search for quick definitions or conjecture. This is exemplary routing guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the experimental beta behavior, that candidate routing is only active during tests, that no candidate is currently active, and that this is a full working router rather than a fallback. This is rich, non-contradictory 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 longer than strictly necessary, but it is front-loaded with the core identity and each additional sentence contributes useful context about experimental state, usage, and non-fallback nature. The structure is coherent, with no redundant filler.

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

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

For a simple one-required-parameter router with safety annotations, the description covers identity, input equivalence, experimental behavior, and comparison purpose. It relies on ask_pipeworx for the actual response shape, but the sibling relationship makes that acceptable given the rich context provided.

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 documented as aliases of the required question field. The description only says 'same arguments' as ask_pipeworx, which does not add meaningful parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly positions this as a beta universal router identical to ask_pipeworx, with the same tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx and grounded sibling by emphasizing experimental candidate-routing status.

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 says to use this like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It stops short of explicitly saying 'use ask_pipeworx for stable routing,' but the contrast is implied and the current no-candidate state makes guidance 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?

The description discloses rich behavioral details beyond the annotations: it only uses content contained in the tool result, returns structured evidence and confidence, refuses rather than guesses, enumerates refusal reasons, and costs an extra LLM call. These traits are not visible in the annotations and materially shape how the agent should interpret responses.

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

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

The description is dense but every sentence contributes: mode definition, routing behavior, extraction constraint, success output shape, refusal behavior, use cases, and cost tradeoff. It is front-loaded with the key concept and remains focused throughout.

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

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

Despite lacking an output schema, the description fully specifies the return structure on success and failure, including refusal reason values. It also explains when to use the tool, how it differs from a sibling, and the cost implication, giving an agent everything needed to invoke and interpret this tool correctly.

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

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

The only required parameter is question, and the schema already documents it and its aliases with 100% coverage. The description adds no additional parameter-level nuance, but because the schema fully covers the parameter semantics, the baseline of 3 is appropriate.

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

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

The description clearly states a specific mode: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from tool results. It explicitly contrasts itself with ask_pipeworx by noting same routing but stricter extraction, making the purpose and differentiation 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?

Usage guidance is explicit and actionable: use when answers will be quoted, cited, or acted on, and when the agent must not invent facts. It also names the alternative ask_pipeworx and advises preferring it for casual lookups, so an agent knows exactly when to choose this tool.

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

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

Annotations (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?

Despite annotations declaring readOnly/openWorld/idempotent, the description adds substantial behavioral context: it decomposes questions into facets, routes to 5,798 tools in parallel, returns verbatim evidence with confidence/source/fetched_at and pipeworx:// citations, never invents gaps[], performs gap recovery and contradiction scans at certain depth levels, semantically excerpts large records, and gives latency expectations. This goes far beyond what annotations express and is highly transparent.

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

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

The description is long but information-dense and front-loaded with the most critical operational constraint (account requirement and free/paid difference). It earns its length by explaining behavior, limits, and latency. A slight cut would be possible (the parenthetical 'depth: thorough needs a paid plan' is repeated in schema and description), so not a 5.

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

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

For a complex tool with 2 parameters and no output schema, the description is remarkably complete: it covers input semantics, output packet structure, gaps behavior, citation behavior, edge cases (unresolvable citations), handling of large records, and latency. It also gives guidance on tier differences. Nothing critical is missing for an agent to decide to call it 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%: both question and depth parameters are already described in the schema. The description adds useful color about what 'standard' and 'thorough' do beyond the schema's explanation (e.g., contradiction scan, chasing leads), but does not materially reinterpret the parameters. 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 specific action (grounded multi-source research) and resource (Pipeworx's 1517 structured data sources), distinguishes itself from open-web search and from siblings like ask_pipeworx, and explains its decomposition and parallel-routing behavior. The examples of use cases (comparing regulatory/financial exposure, researching filings + market picture) make the purpose concrete.

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 when to use this tool (broad/multi-part questions over structured data), and explicitly names the alternative (ask_pipeworx) when not signed in or on a free tier. It also contrasts a single lookup vs multi-faceted research, giving the agent a clear decision rule. The account requirement and paid-tier note are also provided.

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

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

Annotations 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: single parallel call, fan-out across specific sources, sources_used/sources_failed explain empty sections, name resolution via EDGAR, private-company behavior, and type interchangeability. It doesn't fully disclose rate limits or partial-failure semantics beyond sources_failed, but for a read-only research tool the description adds substantial value above annotations.

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

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

The description is long but information-dense and front-loaded with trigger phrasings and the core value proposition. Every clause adds either a routing cue, a data-source enumeration, an edge-case expectation, or an input-format clarification. It earns its length for a broad research tool, though it could be tightened slightly by moving the source-list details into a more scannable structure.

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

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

For a read-only profile tool with no output schema, the description covers input formats, resolution behavior, private-company handling, source fan-out, expected-empty cases, and status reporting via sources_used/sources_failed. An agent knows what to pass, what to expect back, and how to interpret partial or empty results. The only minor omission is explicit pagination or result-limit details, but the description already notes 'up to 5' filings, which is sufficient for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating that type accepts 'company' or 'ticker' interchangeably and that value can be a ticker, zero-padded CIK, or company name in either case — the schema only hints at this through enum descriptions. It also adds the resolved_from/resolved_to behavior when value is a name, which is not present in the input schema.

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

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

The description opens with multiple concrete example phrasings and a clear verb-resource pair: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups and lists the data sources it fans out across, so an agent can tell it apart from siblings like resolve_entity or deep_research without opening schemas.

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 trigger phrasing ('Tell me about X', 'research Acme', 'brief me on Tesla'), states ALWAYS PREFER over chaining single-pack lookups for holistic views, names the alternative pattern it displaces, and notes that private companies return resolved:false rather than failure. It also clarifies when an empty section is expected (e.g., FDA-licensed biologics absent for small-molecule-only companies), which prevents false-negative misrouting.

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 sparse annotations (all false), the description discloses key behaviors: anonymous filing returns a claim_token, claim_token can be used later to check resolution, rate limit of 5 per identifier per day, and that the team reads digests daily. It also notes the tool is free and doesn't count against quota, adding valuable 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?

Though longer than average, every sentence delivers new information without redundancy. It front-loads purpose, then usage guidelines, exclusions, claim-token behavior, rate limits, and resource impact. The structure is logical and well-organized, making the length justified.

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

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

The description covers all necessary context for a feedback tool: what to report, what not to report, how to handle anonymous submissions, how to retrieve status, rate limits, and the team's review cadence. Given the complexity and lack of an output schema, this description is fully complete.

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

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

The schema already covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds meaningful guidance for the `message` parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.') and reinforces the claim_token flow. This extra context justifies a slight bump above baseline but not a 5 since the schema already handles most 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 verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the tool's function and differentiates it from siblings by stating it only handles feedback for this Pipeworx connection, not other MCP servers.

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

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

The description gives explicit when-to-use guidance: for bug reports, feature requests, data gaps, and praise. It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It even offers a heuristic for identifying Pipeworx tools, strengthening the guidance.

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

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

Annotations already indicate read-only, idempotent, 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?

Given the annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes well beyond these by disclosing the matching algorithm's limitations ('matched by keyword and word overlap, not a shared resolution source'), the meaning of temporal alignment nulls, the fee modeling gap (Kalshi fees not modeled), and the fact that compatibility warnings may appear even when pairs are returned. It even warns that pre-mapped ≠ tradeable. This level of transparency far exceeds the minimum and adds real behavioral context that an agent needs to trust the output.

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 bold section headers (TWO MODES, RESPONSE, SAFETY FIELDS) and a logical flow from purpose to invocation to output to caveats. Every sentence carries meaningful information; there is minimal redundancy. However, it could be slightly tightened—for example, temporal_alignment_unknown is repeated in both the code list and the explanation. Given the tool's complexity, the length is justified, but it is not maximally concise, so a 4 is appropriate.

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

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

With no output schema provided, the description carries the full burden of explaining return values. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning and codes, temporal alignment fields, fees_note, skipped counters, and the conditions under which legs are excluded. It also warns about the rarity of real spreads. There is essentially nothing an agent needs to know before calling this tool that is missing. This is a complete and self-sufficient description for a complex tool.

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

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

Schema description coverage is 100%, but the tool description adds substantial semantic value beyond the one-line parameter descriptions. It explains what the topic shortcuts represent, how the explicit ticker/slug override works, and clarifies that both modes run the same matcher. It also details the response structure tied to parameters, such as the delivery of spreads and warnings. This goes well beyond the baseline of 3 for high schema coverage, earning a 5.

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

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

The description opens with a precise statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the tool's function and distinguishes it from nearby siblings like polymarket_arbitrage by focusing on the spread across two specific venues and detailing how bet-shape equivalence determines whether the delta is meaningful. The verb is implicit but the resource and action are unambiguous.

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

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

The description clearly explains the two invocation modes (topic vs. explicit ticker/slug) and how they work, including the override behavior. It provides strong context on when the tool is appropriate (e.g., comparing the same question across venues) and warns that pre-mapped topics often yield warnings. However, it does not explicitly state when NOT to use this tool compared to alternatives like polymarket_arbitrage or polymarket_edges, nor does it name alternative tools for single-venue analysis. The guidance is implicit rather than explicit, so a 4 is warranted.

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 (readOnlyHint, openWorldHint, idempotentHint) cover safety, but the description adds rich behavioral context: it explains the cascade through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguity handling via `figi_candidates`, and explicit `unresolved` lists. It also discloses that identifiers are sourced and labelled, adding transparency beyond what annotations provide.

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

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

Though long, every sentence carries critical information. The description is front-loaded with the most important guidance ('Use FIRST...') and then systematically covers types, edge cases, and failure modes. It avoids redundancy and wastes no words; the length is justified by the tool's complexity.

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

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

Given no output schema, the description exhaustively covers what the agent needs: accepted inputs, return values (identifiers, `unresolved`, `figi_candidates`), source labels, degradation behavior, and rationale for when it replaces manual lookups. It leaves no ambiguity about how to call the tool correctly or what to expect from the response.

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%, yet the description adds substantial semantic detail: it explains the meaning of `type` values, gives examples for `value` (ticker, CIK, name for company; brand/generic for drug), and crucially warns against passing trailing security-class words for bonds. It also clarifies that an ISIN resolves to the legal entity via GLEIF mapping, which is not evident from the schema alone.

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

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

The description states a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'). It distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID' and lists the exact types of queries it handles (ticker, CIK, LEI, RxCUI). It also contrasts with the sibling 'compare_entities' implicitly, as it produces identifiers rather than comparisons.

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

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

The description gives explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also clarifies when not to use it (e.g., when a name matches multiple instruments, it returns candidates rather than asserting, and it instructs the caller to pass only the entity name, not the full noun phrase). It differentiates between entity types and notes that non-equity instruments resolve here, which is a key decision point.

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?

Beyond annotations (readOnly, openWorld, idempotent), the description adds critical behavioral details: the specific verdicts returned, the meaning of 'could_not_verify' (failure of the check, NOT evidence), 'unsupported' (no source), and the warning not to treat could_not_verify as evidence. It also explains the tolerance_pct override semantics and default behavior, providing deep transparency.

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

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

The description is long but every sentence adds value. It front-loads with query examples, states the action, explains routing, lists return structure, and highlights critical caller warnings. It could be slightly tightened, but the density is justified given the complexity and the absence of an output schema.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: verdicts, actual value with citation, reasoning, and the special semantics of could_not_verify and unsupported. It also covers routing, tolerance behavior, and the tool's replacement of sequential calls, making it complete 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?

The input schema already fully describes both parameters (claim and tolerance_pct) with examples. The description adds meaningful extra semantics: tolerance_pct overrides the wording-implied tolerance, has a default cap of 5, and a specific use case (set 1–2 for hallucination detection). This goes beyond schema descriptions, but the schema already covers the basics.

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

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

The description opens with concrete natural-language trigger phrases and states the tool's precise function: 'natural-language claim verification against authoritative sources.' It clearly differentiates from siblings by noting it replaces 4-6 sequential calls (NL parsing → entity resolution → data lookup → comparison), 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes company-financial claims (SEC EDGAR fast path) from other factual claims (grounded pipeline), giving clear routing guidance. It doesn't name alternative tools or state when not to use it, but the context is strong.

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