Nsi Bg

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds valuable behavioral details: the return structure (per-model score, confidence, signals, raw_response plus combined view), and transparency about API key handling ('passed straight through to api.anthropic.com'). 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 (~100 words), front-loaded with the main purpose, and each sentence adds value without redundancy. It efficiently covers purpose, parameters, and use cases.

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

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

For a tool with 4 parameters and no output schema, the description adequately explains inputs and return structure. However, it could be slightly more detailed about the exact fields in the output (e.g., what 'signals' contains), but the provided summary is sufficient for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning for the 'models' and '_apiKey' parameters by explaining defaults, costs, and authentication flow, which enhances understanding beyond the schema.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It differentiates from sibling tools like 'ask_pipeworx' by specifying use cases for AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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 usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and parameter guidance (default model, optional API key). However, it does not explicitly state when not to use the tool or name alternative tools, which would elevate it to a 5.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds value by explaining routing across 4,819 tools and the return of pipeworx:// citation URIs. It also mentions 'one fast call' and 'works on every tier'. No contradictions. A slight gap: no mention of rate limits or error behavior.

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

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

The description is front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and organized with examples and escalation paths. It is somewhat long but each sentence contributes to clarity. A minor deduction for verbosity that could be trimmed.

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 (many siblings, many parameters, no output schema), the description covers purpose, usage, behavior, and examples well. Missing details on return format or error handling, but annotations cover safety aspects. Overall very complete for a general-purpose lookup 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% and includes descriptions. The description essentially repeats the alias information and provides examples, but doesn't add new semantic meaning beyond the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: to answer factual questions using authoritative structured data, with specific domain examples like SEC filings, FDA data, and economic statistics. It distinguishes itself from siblings ask_pipeworx_grounded, deep_research, and web search, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use this tool (factual questions, 'what is', 'look up', etc.) and when to escalate to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad queries). It declares this tool as the default entry point, offering clear decision criteria.

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

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

Annotations already indicate readOnly, openWorld, idempotent hints. Description adds beyond: extra LLM call cost, refusal reasons (not_in_source, no_tool_match, etc.), that it uses only tool result, and that it refuses when data doesn't directly answer. No contradiction with annotations.

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

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

Description is front-loaded with purpose, then explains behavior, return format, and usage trade-offs. It is concise for the complexity, though slightly lengthy. Each 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?

Without output schema, description fully explains return format including success and failure structures with all fields. Also covers cost trade-off with sibling and contexts where grounded mode is needed. Highly complete for agent selection and invocation.

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

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

All 6 parameters are aliases for 'question' and schema descriptions cover 100% with clear documentation of aliases. Description adds no extra parameter-specific semantics beyond what schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing, extracting answer from tool result only, and returning structured response with evidence. It distinguishes from sibling 'ask_pipeworx' by noting extra LLM call and intended use cases.

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 (financial verdicts, legal claims, medical lookups, public statements) and when to prefer 'ask_pipeworx' for casual lookups. Provides clear context about high-stakes reads where answers will be quoted or acted on.

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 comprehensively discloses behavioral traits beyond annotations. It explains the resolution contract (market_match_confidence, alternatives), parent event extractor, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution-rule risk. Annotations already indicate read-only and idempotent, and the description adds valuable context 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 well-structured with clear sections and examples, but it is excessively long and dense. While organized, it could be more concise without losing essential information. Every sentence serves a purpose, but the overall length may hinder quick comprehension for an AI agent.

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

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

Given the complexity of the tool (3 parameters, no output schema), the description is remarkably complete. It covers response shapes, edge cases (closed markets, low confidence), safety measures, and resolution rules. Despite the lack of an output schema, the description provides sufficient context for an AI agent to understand expected outputs and behaviors.

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%, providing a baseline of 3. The description does not significantly add meaning beyond what the schema already provides for the parameters. It mentions input types for 'market' (slug, URL, text) which is already in the schema. No additional parameter details are given that are not covered by the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains the input types (slug, URL, question text) and the output (evidence packet + comparison). Although sibling tools exist, the description implicitly differentiates by focusing on researching a specific bet, distinct from tools like 'polymarket_edges' or '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 states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed examples of category-specific fan-outs (e.g., BTC bet, Fed bet). While it does not explicitly state when not to use it or list alternatives, the use cases are well-defined and the context from sibling tools provides further 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 the tool read-only, idempotent, and non-destructive. The description adds rich behavioral context: parallel call execution, data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting by primary metric. 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 a single paragraph that front-loads the core purpose with multiple trigger examples. While denser than minimal, every sentence adds value (examples, data sources, sorting behavior, replacement of sequential lookups). Minor improvement could be structuring into bullet points.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citation URIs) and no output schema, the description covers all essential aspects: what it returns (paired data + URIs), how data is pulled, and the metric display. Agents have enough information 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?

Schema coverage is 100% and the description adds significant meaning beyond the schema: it explains what each type pulls (LATEST 10-K data for companies, FAERS counts for drugs) and the expected format for values (tickers/CIKs vs drug names). This helps an agent select correct parameter values.

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

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

The description clearly defines the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases ('Compare X and Y', 'X vs Y', etc.) and distinguishes from sequential lookups, making it unambiguous.

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

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

The description explicitly states when to use this tool over alternatives ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and explains the efficiency gain (replaces 8-15 lookups). It does not specify exact when-not scenarios but the context is clear.

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

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

Description adds context beyond annotations: account requirement, that it is not open-web search, returns gaps[], expects 15-60s, and that it never invents answers. Annotations include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false; description aligns with these and adds useful behavioral 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 comprehensive but slightly verbose; however, it is well-structured with critical information front-loaded (account requirement, alternatives) and uses clear sections. Every sentence adds value, so it earns a high score despite length.

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

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

Given the complexity (1259 sources, 4819 tools, parallel decomposition, no output schema), the description thoroughly explains what the tool returns (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]), its scope, and timing. This 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 description adds meaning: explains the `depth` enum values as number of facets ('quick=3, standard=5 (default), thorough=8'), and reinforces that `question` should be broad/multi-part. This exceeds the schema's minimal descriptions.

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

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

The description specifies a clear verb ('research') and resource ('Pipeworx's structured data sources'), explains the tool decomposes questions into facets and routes to tools in parallel, and distinguishes it from siblings like ask_pipeworx by noting this is not open-web search and is best for broad/multi-part questions.

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 ('broad/multi-part questions over structured data') and when not to use (breaking news, colloquial current-news, directing to ask_pipeworx instead). Also mentions account requirements and that 'thorough' depth needs a paid plan.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable context: returns top-N tools with full schemas ready to call, no second lookup. It does not contradict annotations and provides additional behavioral clarity.

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

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

The description is front-loaded with purpose, then provides domain examples and return details. It is slightly long but efficient with no fluff. 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?

No output schema exists, but the description fully explains return values: names, descriptions, full input schemas with curated examples. The tool is a discovery tool, and the description covers what the agent needs to proceed.

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 well-documented in the schema. The description adds no new semantic info beyond summarizing alias relationships and limit defaults. 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 it finds tools by describing data or task, listing many domains. It distinguishes from sibling tools by explicitly saying 'Call this FIRST when you have many tools available' and explaining the return of tool schemas, making it unique among search tools.

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

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

The description provides explicit use cases ('when you need to browse, search, look up, or discover what tools exist for') and advises to call it first. While it doesn't list when not to use it, the context of sibling tools implies alternatives, and the guidance 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, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails for patents with sunset date, and lists exact return fields. No contradiction.

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

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

The description is fairly long but front-loaded with example queries and each sentence adds value. Could be slightly more concise but structure is good.

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

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

No output schema, so description must explain returns. It covers CIK, company name, recent filings with URIs, fundamentals, patents, news, LEI. However, fundamentals format is only partially described (LATEST 10-K fields). Adequate for a complex tool.

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

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

Schema coverage is 100%, baseline of 3. Description adds meaning beyond schema: explains value must be ticker or CIK (names not supported), and type is limited to 'company' with future plans. This provides useful context.

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

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

The description uses specific verbs like 'profile' and 'research' and lists example queries. It clearly identifies the resource as 'full cross-source profile of a US public company' and distinguishes from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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 explicates when to use (holistic view requests) and when not to use (names not supported). It provides an explicit alternative: 'use resolve_entity first if you only have a name.'

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. Description confirms 'Delete' but does not explain idempotent behavior or error handling when key doesn't exist. Adds context about use cases but lacks full behavioral 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?

Two clear sentences, front-loaded purpose, no extra words. Every sentence contributes value.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing. 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?

Only one parameter 'key' with schema description 'Memory key to delete' and an example. Schema coverage is 100%, so baseline is 3. Description adds no further meaning beyond the schema.

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

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

The description clearly states the action 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, implying alternatives.

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

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

The description details the fetching, extraction, and emission process, matching the readOnlyHint and idempotentHint annotations. It adds value by describing the output format and standard location, which annotations do not cover.

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 first sentence defines the action and result, the second lists use cases. Front-loaded and efficient.

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

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

Despite no output schema, the description explains the output format and deployment location. Parameters are fully documented, and use cases cover typical scenarios. Complete for a simple tool.

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

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

Schema coverage is 100%, so baseline is 3. The description restates param info from schema (URL, max_links) without adding significant new meaning. Acceptable but not additive.

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

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

The description specifies the verb 'generate', the resource 'llms.txt file', and the target 'any URL', clearly distinguishing the tool's function. It mentions specific AI crawlers (ChatGPT, Claude, Perplexity) and use cases, 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?

Three explicit use cases are provided (client site indexing, personal project drafting, competitor auditing). No explicit exclusions or alternatives among siblings are given, but the contexts are clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the output includes dimensions, categories, and flat value array, and that lang affects label language, providing additional behavioral context beyond annotations.

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

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

Two concise sentences that front-load the main action and output. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description covers how to get input ids, output format, and example usage. It is complete.

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

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

Schema coverage is 100% so baseline is 3. The description adds example values for id and notes lang defaults, but does not add substantial meaning beyond schema descriptions.

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

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

The description clearly states the verb 'Fetch', the resource 'single NSI Bulgaria dataset', and the output format 'JSON-stat 2.0 object'. It distinguishes from sibling tool list_datasets which lists datasets.

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

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

Explicitly tells the agent to get ids from list_datasets and provides example ids. While no when-not-to-use is given, the context is clear that this is for fetching one specific dataset by id.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds that output is parsed CSV rows, which is helpful but does not disclose additional behavioral traits like rate limits or auth requirements.

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 zero waste. First sentence states purpose, second provides usage context. 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 simple tool with 2 params, good annotations, and no output schema, the description is largely complete. It could optionally detail the output fields returned in CSV rows, but the purpose is clear enough.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds no significant meaning beyond what is in the schema, meeting the baseline but not exceeding it.

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 fetches field/dimension metadata for an NSI dataset, specifying column codes and Bulgarian/English names. It differentiates from siblings like 'get_dataset' by focusing on metadata rather than 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 includes a usage hint: 'Useful for interpreting the dimension codes in a get_dataset response.' This provides context but does not explicitly mention when not to use or list alternatives, though the sibling list makes alternatives discoverable.

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, non-destructive. Description adds detail about result structure (numeric id, English/Bulgarian name) and filter behavior (case-insensitive substring match), adding value beyond annotations.

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

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

Two sentences, no waste. Purpose first, then details. 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?

No output schema, but description explains that return includes numeric id and name. Covers filter functionality and links to get_dataset. Sufficient for the simple tool, especially with strong annotations.

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%, providing baseline 3. Description enriches parameters: lang is explained as 'English (or Bulgarian) name', and filter is clarified with examples ('population', 'export', 'inflation') and case-insensitive behavior.

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

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

Clear verb 'list' and resource 'NSI Bulgaria open-data datasets'. Distinguishes from sibling 'get_dataset' by stating that dataset ids can be passed to get_dataset for actual figures.

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: to list datasets, optionally with filter. Also mentions subsequent use of get_dataset. No explicit exclusion, but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. It adds the returned fields, which is helpful but not essential behavioral context beyond annotations.

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

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

The description is two sentences with no unnecessary words. It front-loads the core purpose and then adds usage guidance, all in a compact format.

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 simple input schema (one optional boolean), the annotation-rich safety profile, and no output schema, the description fully covers what an agent needs to know: what it does, what it returns, and when to use it.

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

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

The only parameter (include_inactive) is fully described in the schema with a clear description. The tool description does not add further detail about the parameter, so it provides no added value beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, etc.). It is a specific verb and resource, and the sibling list includes subscribe and unsubscribe, but no other listing tool, so it is well-distinguished.

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

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

The description advises using this tool to review monitoring before adding more subscriptions or to find an ID to cancel. This gives actionable guidance but does not explicitly exclude scenarios or compare to alternatives like subscribe.

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

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

Beyond annotations (all false), description reveals rate limit of 5 per identifier per day, that it's free and doesn't count against quota, and that team reads digests daily with roadmap impact. This gives full 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?

Concise but comprehensive. Each sentence adds value: purpose, usage scenarios, writing advice, team context, rate limits. Well-structured with front-loaded 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?

Fully adequate given complexity (3 params, enum, nested object, no output schema). Covers feedback types, context usage, message format, rate limits, and team process. No gaps.

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

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

Schema coverage is 100% with descriptions. The description adds nuance: explains enum values for type (e.g., 'bug = something broke'), provides guidance on context object, and specifies message format (be specific, 1-2 sentences, 2000 chars max).

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

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

The description clearly states the tool is for sending feedback to Pipeworx team about bugs, features, data gaps, or praise. It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback submission.

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: for bug reports, feature requests, data gaps, or praise. Also advises not to paste user prompts but describe in terms of tools/packs, providing clear usage boundaries.

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 value by explaining the data source (CF analytics-engine), that no PII is included, and the caching behavior (5min-1h). This provides 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?

The description is four sentences with no wasted words. It front-loads the core function, then provides use cases, and ends with technical details. 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 low complexity (1 param, no nested objects, no output schema), the description is complete. It covers what is returned (top tools, top packs, total call volume), how it works (aggregation from CF analytics), caching, and use cases. No gaps.

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

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

Schema description coverage is 100% for the single parameter 'window' with an enum. The description adds semantic meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the appropriate window.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It specifies the verb 'returns' and the resource 'trending data from Pipeworx'. It distinguishes itself from siblings like 'discover_tools' by focusing on trending activity and call volume.

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

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

The description lists three specific use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. While it doesn't explicitly state when not to use or suggest alternatives, the provided contexts are clear and actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses detailed behavioral traits: monotonicity violations, partition-sum checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against CLOB depth, and conditions for not trading. This adds significant value beyond annotations.

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

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

The description is well-structured with capitalized sections and front-loaded purpose. Every sentence adds value, though it is somewhat lengthy. Given the tool's complexity, this is acceptable and efficient.

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

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

Given the tool's complexity (arbitrage detection) and no output schema, the description comprehensively explains algorithm, modes, edge cases, response structure, and fill check. It also references polymarket_fill_risk for custom sizing, making it contextually complete.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaning by explaining what each mode does, providing examples of event slugs and topic seeds, and detailing cross-event behavior. It enhances understanding beyond the schema descriptions.

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

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

The description begins with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its unique arbitrage detection methodology.

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

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

The description explicitly states when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. It recommends event mode for a specific market and directs users to polymarket_fill_risk for custom sizing, providing clear usage context and 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent and the description adds rich behavioral context: caching behavior (1h at KV level), detailed response structure (by_segment, diagnostics, fed_candidates), and edge calculation methodology. 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 verbose but well-structured with clear sections and front-loaded purpose. Every sentence adds value, though some technical details could be condensed for quicker scanning.

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 (9 parameters, no output schema), the description is exceptionally complete. It covers response structure, diagnostics, Fed bet exclusion, caching, and filter behaviors, leaving no gaps for an AI agent to safely invoke 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 coverage is 100% with detailed parameter descriptions. The description adds overarching context but doesn't significantly enhance individual parameter semantics beyond what the schema 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 states the tool's purpose: 'Scan top Polymarkets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets 'what should I bet on today' and distinguishes from siblings by emphasizing automated opportunity discovery without manual paging.

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

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

The description provides explicit usage context: for daily betting opportunities and discovery. It notes that Fed bets are excluded from ranking due to unreliable signals, offering a clear exclusion criterion. While it doesn't explicitly state when not to use, the purpose and limitations are well communicated.

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

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

Annotations declare read-only, idempotent, open-world, and non-destructive. The description adds behavioral details: snapshots with TTL, daily closes, data gaps, and output structure. It does not contradict annotations and provides useful extra 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 well-structured: purpose statement, parameter explanation, output description, and limitations. Every sentence adds value, though moderately long. Could be slightly more concise but overall 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?

Given complexity (time-series telemetry) and no output schema, the description thoroughly explains output fields (tracked, expired, snapshot_dates) and limitations (TTL, daily closes). It provides complete context for the AI to understand results.

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

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

Schema coverage is 100% for both parameters. Description adds defaults (14 days, '1wk'), constraints (max 30 days), and interpretation of 'window' as snapshot family. This adds 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 it measures 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. It specifies the tool's purpose with a clear verb (track) and resource (edge persistence/decay), differentiating it from sibling polymarket_edges which likely provides current edges only.

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 strong context for when to use it (comparing edge longevity) and implies alternative polymarket_edges for current edges. It does not explicitly state when not to use, but the purpose is clear enough for AI to infer usage boundaries.

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 behavioral traits beyond annotations: it details the ladder-walking process, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), verdicts, and risk warnings (thin_legs, forced_directional_risk). Annotations already indicate read-only and idempotent; the description adds functional behavior 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 dense but well-structured, with mode breakdowns and key phrases in uppercase. Every sentence adds value, and the purpose is front-loaded. Minor conciseness could be gained, but overall efficient for the information conveyed.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete: it lists all return fields for both modes, explains verdicts, warns about thin legs and directional risk, and provides usage context. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains that market and event are mutually exclusive, describes side and size_usd semantics per mode, and specifies default value (1000) and clamp range (10–1,000,000). This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly recommending its use before acting on their signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the reasoning (theoretical overround on thin books is not capturable, partial baskets cause unhedged positions), offering clear context and alternatives.

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

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

The description adds significant behavioral context beyond annotations: it explains compatibility warnings (non-equivalent bet shapes, no semantic overlap), temporal alignment, and skipped comparison counters. Annotations already indicate safe read-only idempotent behavior, and the description aligns 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 well-structured with clear sections and front-loaded purpose. It is verbose but each sentence adds value given the tool's complexity. Could be slightly more concise, but not overly wordy.

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

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

Without an output schema, the description thoroughly covers the response structure (leg-by-leg prices, spread array, safety fields) and edge cases. It also explains when spreads are meaningless (temporal mismatch, non-equivalent shapes), making it complete for effective use.

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

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

Although schema coverage is 100%, the description greatly enriches parameter meaning: it explains the two modes, gives examples, and clarifies how topic maps to events vs explicit tickers override the mapping. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb 'compute' and resource 'spread', and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly outlines two modes (topic shortcuts and explicit tickers) and provides safety fields detailing when not to use the tool (compatibility_warning, temporal_alignment:false). It also warns that most pre-mapped topics currently return compatibility warnings, guiding appropriate use.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. Description adds scoping detail (anonymous IP, BYO key hash, account ID) beyond the structured fields.

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

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

Three sentences with no filler. Front-loaded with the main action and optional behavior. 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?

Complete for a simple tool with one optional parameter and no output schema. Covers both retrieval and listing, scoping, and sibling relationships.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. Description reiterates the omit-to-list behavior, adding no new 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?

Clearly states the verb (retrieve/list) and resource (saved keys/values). Distinguishes from siblings 'remember' and 'forget' by specifying the operation and the optional key argument for listing.

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: use to look up previously stored information without re-deriving. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use but sufficiently guides the agent.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the effect of 'mark_read' on subsequent calls, the returned data structure (source, citation_uri, payload), and that polling is safe. No contradictions with annotations.

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

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

The description is concise with four sentences. The first sentence states the main purpose, followed by details on returned data, filtering options, and an alternative access method. Every sentence adds value with no 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 read tool with 5 parameters and no output schema, the description covers key aspects: what is returned, filtering options, the effect of mark_read, and polling suitability. It mentions an HTTP alternative. Minor omission: does not explain 'unread_only' or 'limit' in description, but those are in schema.

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

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

The schema has 100% coverage with descriptions for all parameters. The description adds context by providing an example for 'type' ('sec_8k'), clarifying 'since' as ISO timestamp, and explaining the effect of 'mark_read' on future calls. This enhances understanding beyond the schema.

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

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

The description clearly states it pulls fired events from subscription feeds and returns recent alerts with specific fields. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on alert content rather than subscription management.

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

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

The description implies usage for polling and mentions an HTTP endpoint for scripts, but does not explicitly provide when-to-use or when-not-to-use guidance compared to similar tools like 'ask_pipeworx' or 'get_dataset'. No exclusions are mentioned.

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, open-world, non-destructive. Description adds valuable behavioral details: fans out to multiple sources, fallback logic, date formats, return structure with grouped changes and citation URIs. Goes well beyond annotations.

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

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

Description is moderately dense but well-organized: opens with example queries, explains functionality, notes fallbacks, date formats, return structure, and explicit alternative. Could streamline slightly, but 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?

No output schema, but description details return format (grouped changes, total_changes, citation URIs) and edge cases (GDELT fallback, USPTO soft-fail). Explicitly differentiates from sibling 'entity_profile'. Fully sufficient for an agent to select and 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%, baseline 3. Description adds specific detail for 'since' (ISO/relative shorthand, typical '30d'), clarifies 'value' (ticker or CIK), and provides typical usage. This extra context justifies a 4.

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

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

Description clearly states the tool returns a change feed for a company, including SEC filings, news, and patents, and distinguishes it from sibling tool 'entity_profile'. Specific verb+resource: 'change feed for a company'.

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 common queries as usage signals ('What's new with X'), details fallback behavior (GDELT→GNews), soft-fail for USPTO, and directs to 'entity_profile' for static profile. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations provide idempotentHint and destructiveHint. The description adds context beyond annotations: persistence duration (24 hours for anonymous), scoping by identifier, and storage as key-value pairs. 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?

Description is four sentences, front-loaded with core purpose, and every sentence adds value. No wasted words.

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

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

For a simple key-value save tool, the description covers usage, persistence, pairing with recall/forget, and examples. No output schema needed; complete for 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?

Input schema covers both parameters with descriptions. The description adds example keys but no additional meaning beyond schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse later, specifying the verb 'save' and the resource 'data'. It distinguishes from siblings 'recall' and 'forget' by mentioning them, and provides concrete examples of use cases.

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 discover something worth carrying forward' and gives examples like resolved tickers and user preferences. It also explains persistence differences between authenticated and anonymous sessions, and pairs with recall and forget.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups, and mentions auto-disambiguation and citation URIs. No contradiction with annotations.

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

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

The description is moderately long but well-structured with clear sections for supported types. Every sentence adds value, though it could be slightly more concise without losing key details.

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

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

Despite no output schema, the description thoroughly explains return values for each type (ticker, CIK, company name, citation for company; RxCUI, ingredient, brand, citation for drug). It covers the main functionality but could mention potential limitations or error cases.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description enriches by explaining acceptable inputs per type (e.g., ticker, CIK, or name for company; brand or generic for drug) and notes auto-disambiguation, adding value beyond bare 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 resolves names to canonical IDs, provides concrete examples like 'What's the ticker for…', and explicitly lists supported types (company, drug). It differentiates from sibling tools by noting that other tools require the ID from this tool.

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 FIRST whenever you have a name but need an ID,' giving a clear usage directive. However, it does not directly state when not to use it or name alternatives, though the context implies it's the primary name-to-id 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 readOnly, idempotent, and non-destructive. The description adds that it sends probes to each entity using ai_visibility_check and returns a ranked list with specific fields (score, confidence, signal density). 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-loading the action and outcome. Every sentence adds value, no redundancy, and it's 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?

Given the tool's moderate complexity (multi-entity aggregation), complete schema coverage, and no output schema, the description explains the process (probes each, ranks), output fields, and use case. It is sufficient for a read-only tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add new information beyond the schema; it only mentions probing entities, which is already implied. 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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks results, and outputs a ranked list. It distinguishes itself from the sibling ai_visibility_check by being a multi-entity comparator.

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 frames the tool for competitive AI-marketing audits with an example question. It implies when to use but does not explicitly state when not to use or mention alternatives, though the contrast with ai_visibility_check 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?

Beyond annotations (readOnly, idempotent, not destructive), the description adds critical behavioral context: partial failure handling, timing nuance for bundlephobia's first measurement (5-30s), and the graceful degradation with sources_failed field. No contradiction with annotations.

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

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

The description is information-dense yet concise, front-loading purpose and scope, then detailing behavior, limitations, and error handling. Every sentence is purposeful, with no fluff.

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

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

Despite no output schema, the description fully explains the return value structure (summary block, per-advisory detail, links, alternatives) and handles edge cases (partial failure, timing). The tool is complex but the description covers all necessary aspects.

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

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

With 100% schema description coverage, the description adds value by clarifying package parameter accepts scoped packages and version parameter defaults to latest. This enriches the schema definitions.

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

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

The description clearly states the tool's composite nature and specific use case ('should I add this npm package'), and distinguishes from sibling tools by explicitly noting the NPM-only scope in v1 and pointing to alternatives for other ecosystems.

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

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

Provides explicit guidance on when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to (non-NPM ecosystems, directing to deps.dev:version directly), making the decision clear for an AI agent.

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

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

Discloses embedding model (BGE-base-en), window size (500 chars), similarity metric (cosine), and character cap (200K with truncation flag). No contradiction with annotations (all idempotent/read-only hints).

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

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

Front-loaded with key info, each sentence serves a purpose. Slightly long but packed with useful detail; 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, description explains return value structure (passages, offsets, scores). Covers limitations, pairing, and typical use cases. Full context for the 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% but description adds value with examples for query parameter and clarification of text max length. Could mention limit default from schema (already present) but still beneficial.

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 performs semantic search inside a fetched record. Distinguishes from sibling tool 'ask_pipeworx_grounded' by explaining the workflow: fetch first, then search within.

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

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

Explicitly says when to use (record too large for prompt), provides example queries, and describes pairing with ask_pipeworx_grounded. Offers clear alternatives and context.

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

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

The description discloses behavioral details beyond annotations: it returns a new subscription id (non-readOnly), requires authentication (OAuth account), persistence of subscriptions, rate limits (10 SMS/day), and webhook signing secret returned once. These complement the annotations effectively.

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

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

The description is well-structured and appropriate in length. It front-loads the core purpose and prerequisites, then elaborates on types and delivery channels. Every sentence adds value without being verbose.

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

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

Given the tool's complexity (3 parameters with nested objects, multiple subscription types, delivery options), the description is comprehensive. It covers all parameters, prerequisites, constraints, and return value. No output schema exists, but the description adequately indicates what is returned.

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

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

The description adds significant meaning beyond the input schema: it provides concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic), validation rules (phone must be verified), and delivery channel specifics (email pattern, webhook HMAC signature). This compensates for any abstraction in the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (Create) and resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool (to create a subscription) and includes prerequisites (Pipeworx OAuth account, phone verification for SMS). However, it does not explicitly mention when not to use it or compare with 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 mark it as readOnly, openWorld, idempotent, non-destructive. The description adds context about the output (category-bucketed questions with tool+argument shapes) and behavior variation with 'topic', going beyond the annotations.

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

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

The description is slightly lengthy but well-structured and front-loaded with the purpose. Each sentence contributes meaningful information, though a bit of redundancy exists (e.g., repeating 'what can I ask').

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers all necessary aspects: purpose, usage, parameter behavior, and typical follow-up actions. It is complete for effective agent 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% and the description adds meaning by explaining the 'topic' parameter values and the effect of omitting it ('full spread'). This enriches the schema beyond just listing properties.

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 specifies the verb 'suggest' and resource 'questions' for Pipeworx. It distinguishes itself from sibling tools like 'discover_tools' by framing itself as an onboarding entry point that returns example questions, not a tool list.

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

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

Explicitly states '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 clarifies when to omit or use the 'topic' parameter, providing direct usage scenarios.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the row is deactivated (not deleted) and historical events persist, which goes beyond annotations and clarifies the non-destructive nature.

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 the purpose, second explains behavioral traits. No wasted words, well front-loaded.

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

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

For a single-parameter tool with no output schema, the description covers the action, ownership constraint, and data disposition. Missing error handling details (e.g., id not found) but acceptable given low 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 a clear description for the 'id' parameter. The tool description reinforces that the id comes from subscribe but does not add significant new semantic details beyond the schema.

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

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

The description clearly states the action (cancel/unsubscribe) and the resource (subscription), with additional context about ownership enforcement. It distinguishes 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?

The description explicitly specifies that ownership is enforced, telling the agent when to use the tool (own subscriptions) and implying when not to. It also mentions that historical events remain via recent_alerts, but could be improved by suggesting to list subscriptions first to get the id.

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, idempotent, openWorld, non-destructive), the description adds critical behavioral details: returns verdict types, extracted structured form, actual value with citation, percent delta, and domain limitation to company-financial claims. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with key examples and usage context. Every sentence adds value, though it 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?

Given the single parameter and absence of output schema, the description fully covers purpose, usage, behavioral traits, and limitations. No gaps remain for an agent to understand 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 has 100% coverage for the single 'claim' parameter, including a description. The description adds no additional parameter-level information, so it is adequate but not additive beyond the schema.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, with explicit examples like 'fact check' and 'verify the claim that...'. It specifies the domain (company-financial claims) and distinguishes from siblings by highlighting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides clear context but does not explicitly exclude other scenarios or mention alternatives among the many sibling tools.

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