7timer

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: default model (Workers AI Llama-3.3-70b, free), API key requirement for Anthropic (BYO key, direct billing), and return format (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond annotations without contradiction.

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

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

The description is concise (three sentences) and front-loaded with the main action and output. Every sentence adds distinct value: what it does, default behavior, return format, and use cases. No wasted words.

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

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

No output schema exists, so the description bears the burden of explaining return values. It mentions per-model {score, confidence, signals, raw_response} and combined view, but does not define the scoring scale, confidence interpretation, or what 'signals' contain. For a tool with 4 parameters and moderate complexity, this is adequate but leaves some gaps.

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

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

With 100% schema description coverage, baseline is 3. The description adds practical context: clarifies that 'models' defaults to workers-ai if omitted, that '_apiKey' is only needed for Anthropic and passed straight through, and that 'context' helps disambiguate. This exceeds 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's core function: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility per model (0-100). It specifies the default model and optional Anthropic integration, distinguishing it from sibling tools like 'scan_competitor_ai_presence' or 'ask_pipeworx' by focusing on multi-model visibility scoring.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It provides clear context for when to use the tool, though it does not explicitly mention when not to use it or compare directly with siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining it routes to 4,770 tools across 1241 sources, returns structured answers with citation URIs, and is fast. 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?

Description is front-loaded with key preference statement, followed by examples and step-up guidance. Some redundancy (e.g., multiple aliases) but overall well-organized and informative.

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 broad scope, the description covers when to use, what it does, how it works, and return format (structured with citations). No output schema, but description compensates. Examples cover diverse use 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 has 6 parameters but all are aliases for the single required 'question' parameter. Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific meaning beyond what schema provides, but gives context for what kind of questions to ask.

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 handles factual questions about current or historical data from many sources, distinguishing it from web search and sibling tools. Uses specific verbs like 'routes' and 'returns', and provides concrete examples.

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

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

Explicitly instructs to prefer this tool over web search, gives when to use (factual questions with specific patterns), and when to step up to alternatives (ask_pipeworx_grounded, deep_research). Lists question types and examples.

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 discloses that it costs one extra LLM call, explains the return structure with success and failure modes including specific refusal reasons. Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds further behavioral 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?

Description is fairly long but well-structured and front-loaded. Every sentence adds value, but could be slightly more concise. Still, it effectively communicates key information without redundancy.

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

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

Given the complexity (routing across 4770 tools, 1241 sources, return format details, refusal reasons, cost implication), the description is highly complete. No output schema exists, but the description sufficiently explains return values.

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

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

Schema coverage is 100% with all parameters being aliases for 'question' with descriptions. The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads', explains the process of routing, tool selection, fetching, and extracting answers using only tool results. It distinguishes from sibling 'ask_pipeworx' by specifying it is grounded and for high-stakes uses.

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: 'whenever an answer will be quoted, cited, or acted on', and provides concrete examples like financial verdicts, legal claims, medical lookups, public statements. Also advises to prefer 'ask_pipeworx' for casual lookups, giving clear when-not-to-use guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It details the resolution process (low-confidence short-circuit, closed market detection), fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback handling, and safety notes. Annotations already indicate safe reads, but the description adds extensive 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 over 500 words across multiple paragraphs. While detailed, it includes extensive information about response shapes and internal mechanisms that could be better placed in an output schema or separate documentation. It front-loads the purpose but becomes verbose, reducing conciseness.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, response shapes, safety conditions), the description is remarkably complete. It covers input flexibility, classification examples, output structure, resolver confidence, parent event extraction, news fallback, safety short-circuits, and cancellation rules. No output schema exists, so the description must cover return values, which it does thoroughly.

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 schema descriptions for 'market', 'depth', and 'include_raw' are already clear. The description restates the market input formats but does not add significant new meaning beyond the schema. Baseline 3 is appropriate given full schema coverage.

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

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

The description starts with a specific verb ('Research') and resource ('Polymarket bet'), clearly stating it pulls Pipeworx data. It accepts multiple input formats (slug, URL, question text) and describes the output (evidence packet + comparison). It distinguishes itself from siblings like polymarket_edges by focusing on general research rather than specific edge calculations.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides examples. However, it does not mention when not to use the tool or suggest alternatives (e.g., polymarket_edges for edge-specific queries), which would make it 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 mark it as read-only, open world, idempotent, non-destructive. Description adds detailed behavioral traits: for companies, pulls latest 10-K financials from SEC EDGAR/XBRL with correct off-calendar fiscal year handling; for drugs, pulls FAERS data. Also notes sorting by primary metric and citation URI return.

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 a single paragraph with front-loaded examples. It efficiently packs multiple details (type-specific data, sorting, citations) without unnecessary words. Slightly long 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?

Despite no output schema, the description explains return format (paired data + citation URIs per entity), covers both entity types, and mentions sorting. Provides sufficient context for the agent to understand behavior and 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%, but description adds significant meaning: explains that 'type' parameter values map to specific data sources (company→SEC 10-K, drug→FAERS), and 'values' parameter has examples and constraint details. This provides context 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 performs side-by-side comparison of 2-5 entities (companies or drugs) in one call, with examples like 'X vs Y' and 'compare these companies'. It distinguishes from sibling tools like entity_profile which handles single entities.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and mentions it replaces 8-15 sequential lookups. Also clarifies behavior for company vs drug types.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint. Description adds critical behavioral traits: account required, paid plan for thorough depth, 15-60s timeout, returns gaps[] with explicit missing data, never invents, not open-web search. 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?

Description is well-structured with clear sections, front-loaded with account requirement. Though lengthy, every sentence adds value. Slightly verbose but appropriate for complexity.

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

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

Despite no output schema, description fully explains return format (findings packet with evidence, confidence, source, citation, gaps[]). Covers all necessary behavioral context, parameter defaults, and time expectations.

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 value by explaining the depth enum values (quick=3, standard=5, thorough=8 paid) and clarifying question accepts broad/multi-part.

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

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

Description clearly states it performs 'grounded multi-source research' across structured data, decomposes questions, and returns a findings packet. It distinguishes from sibling ask_pipeworx and defines best 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 (broad/multi-part questions over structured data) and when not (breaking news, colloquial topics). Explicitly names alternative ask_pipeworx for single lookups and news.

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 say readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is valuable 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 multi-sentence but each sentence adds value. It is front-loaded with the verb. The list of domains is thorough but somewhat lengthy; could be slightly more concise without losing key information.

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?

Explains what the output contains (tool names, descriptions, schemas) and emphasizes readiness to call. No output schema exists, so description compensates well. Lacks details on pagination or sorting of results, but overall complete for discovery tool.

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

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

Schema description coverage is 100% and includes examples. The description mentions aliases for query parameters, but this is already in the schema. No additional semantic detail 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 starts with 'Find tools by describing the data or task' which clearly states the purpose. It lists many specific domains (SEC filings, financials, FDA drugs, etc.) making it distinct from sibling tools which are specific actions like bet_research or weather_forecast. No ambiguity.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use. However, it does not mention when not to use it or alternatives, but the context is clear enough.

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

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

Discloses internal behavior: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specifies return fields with URI format; notes USPTO PatentsView API sunset and soft-fail; mentions GDELT→GNews fallback. Adds context beyond readOnly and idempotent annotations.

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

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

Well-structured: starts with example queries, then preferred usage, then detailed output listing. Though dense with information, it is organized and front-loaded. Slightly verbose but effectively communicates needed 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?

For a complex tool with no output schema, the description comprehensively covers inputs, outputs, failure modes (patents), source diversity, and link formats. All necessary context for correct invocation is present.

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 parameter descriptions already providing type and value details. The description reinforces name limitation and examples but does not add significant new semantic information beyond what the schema provides.

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

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

The description clearly states that the tool creates a holistic cross-source profile for a US public company in one parallel call, listing specific outputs and sources. It distinguishes from chaining individual lookups and provides example queries like 'Tell me about X' or 'company profile for Microsoft'.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity first if only a name is available, and states that names are not supported.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds 'clear sensitive data' but doesn't reveal new behavioral traits beyond annotations.

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

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

Two sentences, no wasted words, front-loaded with key purpose and usage context.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, and relationship to siblings.

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 repeats the schema description for 'key' without adding new meaning, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', distinguishing it from sibling tools 'remember' and 'recall'.

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

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

Provides explicit use cases (stale context, task done, clear sensitive data) and mentions pairing with siblings, but does not include explicit when-not-to-use 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, non-destructive operation. The description adds value by detailing the behavioral steps: fetches the page, extracts title/description/key links, and emits markdown. There is 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 concise at three sentences: first sentence states the core function, second details the process, third lists use cases. It is front-loaded with the primary action and avoids unnecessary words, making it efficient for an agent to parse.

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 parameters, no output schema, nested objects), the description covers all essential context: input, process, output format, and practical use cases. The lack of an output schema is mitigated by referencing the standard llms.txt format. The description is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with well-described parameters (url and max_links). The description adds minimal extra meaning beyond the schema, mentioning that the tool fetches the page and extracts info, which implicitly relates to the url parameter, but doesn't elaborate on max_links 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 generates a production-ready llms.txt file for AI crawlers, specifying the action (generate, fetch, extract, emit), the resource (any URL), and the output format (standard llms.txt markdown). It differentiates from siblings by its unique purpose of producing llms.txt files, distinct from tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor indexing. While it doesn't include negative cases or alternative tools by name, the positive guidance is clear and actionable, making it easy to decide when to use this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by listing the return fields, which helps the agent understand the response structure.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

The description effectively covers the return fields and usage context. It does not mention potential pagination or rate limits, but these are not critical given the tool's simplicity and the annotations provided.

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

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

Schema coverage is 100% and describes the include_inactive parameter well. The description does not add extra meaning beyond hinting that active subscriptions are returned by default, but this is sufficient for a simple boolean.

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

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

Description clearly states it lists the caller's active subscriptions and specifies the fields returned (id, type, params, etc.). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using the tool before adding more subscriptions or to find an id to cancel, referencing sibling tools. It provides clear context but doesn't explicitly state when not to use it.

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

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

Annotations are neutral (no readOnlyHint etc.), but the description adds valuable behavioral context: rate-limited to 5 per day, free, and that feedback is read daily and influences roadmap. This goes beyond what annotations provide, though the description could mention if feedback is stored or visible to others.

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, covering all necessary aspects in a few sentences. It starts with the core purpose, then usage guidelines, then additional notes. Every sentence provides value, and there is 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 feedback tool with 3 parameters and no output schema, the description is remarkably complete. It covers input types, constraints (rate limit, free), and even what not to include. The agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaningful guidance on how to use each parameter, such as clarifying the 'type' enum values and instructing to be specific in 'message'. It also explains the optional 'context' object, which goes beyond 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 clearly states the tool's purpose: sending feedback about bugs, missing features, or praise. It uses specific verbs ('tell the Pipeworx team') and resource ('feedback') and distinguishes from sibling tools by focusing on reporting issues or praise, not querying or manipulating 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?

Explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. Also provides a clear negative instruction: 'don't paste the end-user's prompt.' Mentions rate limits and free usage, guiding appropriate invocation.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate a safe, read-only operation. The description adds value by revealing that data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h depending on window. This provides behavioral context beyond annotations without contradiction.

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

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

The description is concise, using three sentences plus bullets. It front-loads the core purpose and immediately lists use cases. Every sentence provides essential information without redundancy or verbosity.

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 one-parameter tool and no output schema, the description adequately explains the return structure (top tools, top packs, total call volume). It covers the behavior, caching, and data origin. While it could be slightly more explicit about the output format, it is sufficient for an agent to understand and 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%: one parameter 'window' with enum and description. The description repeats the enum values and adds usage nuance (shorter windows for hot right now, longer for steady-state). This adds marginal meaning beyond the schema description, meeting the baseline expectation for a well-covered 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 that the tool returns top tools, top packs, and total call volume over configurable windows. It specifies the data source (Pipeworx) and the action (returns). This distinguishes it from siblings that are about asking questions or searching, as it focuses on aggregated trending 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 provides three explicit use cases, guiding when to use the tool (e.g., discovering hot data sources, confirming canonical tools). It also explains the different window options and their implications. However, it does not explicitly state when not to use the tool or offer direct alternatives, though the context is clear enough.

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

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

Annotations declare safety (readOnly, idempotent, non-destructive). Description adds deep behavioral context: how monotonicity and partition checks work, fill check mechanics (theoretical vs realizable edge), semantic anchor, partition filter, and why not to trade thin legs. 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 long but densely packed with valuable information. Front-loaded with the main purpose. Could be slightly more structured (e.g., bullet points for modes), but every sentence earns its place given complexity.

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

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

No output schema, but description fully explains return values: opportunities array with fields and partition_check details. Also covers fill check conditions and when not to trade. Complete for a complex arbitrage detection tool.

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

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

Schema covers 100% of parameters. Description adds meaning: event mode accepts slugs or full URLs and walks child markets; topic mode uses a seed question to search related events. Explains what each mode does beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and the no-arg scan, making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly describes when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event for specific markets and explains cross-event catches patterns missed by single-event. Also advises using polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds extensive behavioral detail: model families (e.g., structural arbitrage with per-sport α), tradeable-edge knobs (min_liquidity, max_spread_pp), response structure including diagnostics ('so callers can see WHY a segment is empty'), and caching behavior ('Cached 1h at the KV level'). This far exceeds what annotations provide, making the tool's behavior fully transparent.

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

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

The description is comprehensive but not overly verbose; it front-loads the core purpose and then details models, knobs, and response structure. Every sentence provides useful information, though it could be slightly more concise by grouping related details. Given the tool's complexity, the length is justified.

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

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

The tool is complex with 9 parameters, no output schema, and multiple model families. The description covers the response top-level structure (by_segment, fed_candidates, _diagnostics), edge properties (edge_pp_net, kelly_fraction, etc.), filtering knobs, and caching. It even explains why some segments might be empty. This is as complete as one could expect for such a 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%; all 9 parameters have descriptions. The description adds significant value beyond the schema: e.g., for 'slippage_pp' it explains Polymarket's fee structure and bid/ask depth context; for 'min_partition_leg_kelly' it clarifies why min_kelly doesn't filter partition arbs. Some parameters like 'limit' and 'window' add less, but overall the description enriches understanding of how parameters affect behavior.

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

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

The description clearly states the verb ('Scan top Polymarket markets') and the unique resource ('opportunities where Pipeworx data disagrees with market price'). It distinguishes itself from siblings like 'polymarket_arbitrage' by detailing model families and segments, making the purpose specific and 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 includes usage context ('Built for "what should I bet on today"') and mentions tradeable-edge knobs for filtering, which guides when to use. However, it does not explicitly contrast with alternatives like 'polymarket_edge_tracker' or state when not to use this tool, leaving some room for ambiguity.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds value by detailing response structure (tracked, expired, snapshot_dates), decay computation, trend classification, and limitations (no intraday data, TTL). 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?

Front-loaded with purpose, then covers args, response, and limitations in logical order. Some redundancy (e.g., re-lists defaults) but overall efficient for the detail provided. A trim could improve score.

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 compensates by enumerating all response fields (tracked, expired, snapshot_dates) and their subfields (first_seen, trend, decay_pp_per_day). Includes limitations (TTL, snapshot gaps). Complete and self-contained.

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

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

Schema coverage is 100%; both parameters described in schema. Description restates defaults and clamps, adding minimal extra context (e.g., 'snapshot family', 'max 30'). Does not significantly deepen understanding beyond schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from snapshots, distinguishing it from sibling tools like polymarket_edges (raw edges) and polymarket_arbitrage by focusing on temporal decay rather than current values.

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?

Answers when to use: compares fresh vs old edges, implying context. Explicitly mentions lookback bounds (max 30 days) and snapshot TTL (60-day). Does not explicitly name alternatives but the context is clear enough.

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

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

Adds value beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing behavior: walking the ladder, returning specific fields, and disclosing that partial basket fills convert arb into unhedged directional position. 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 thorough but somewhat lengthy; however, every sentence adds value and it is well-structured with clear mode breakdowns and front-loaded purpose. Slightly verbose but 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?

For a complex tool with two modes and multiple return fields (no output schema), the description covers all essential aspects: mode behavior, parameter interpretation, return fields, and risk warnings. Complete for an AI 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% with descriptions, and the tool description adds meaning: explains mode-dependent interpretation of side and size_usd, default values, and usage constraints. Provides context not present in schema alone.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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 advises to use before acting on polymarket_arbitrage signals or trade above ~$500, explaining the risks of partial fills and uncapturable overround. Provides clear when-to-use and why.

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 and non-destructive behavior. The description goes far beyond by detailing response structure (leg-by-leg prices, spreads), safety fields (compatibility_warning, temporal_alignment), and edge cases (non-equivalent bet shapes, temporal misalignment). This fully informs the agent of the tool's behavior and limitations.

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

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

The description is longer than average (~150 words) but every sentence contributes to understanding. It is front-loaded with the purpose and progressively details modes, response, and safety. Could be slightly tightened but remains efficient and well-organized.

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 cross-venue spread analysis with potential shape mismatches and temporal issues, the description comprehensively covers all necessary aspects: modes, response fields, safety warnings, and edge cases. Even without an output schema, the textual description is complete enough for an agent to interpret results.

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

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

Input schema has 100% coverage with parameter descriptions, but the description adds significant value by explaining the two modes, listing the 10 topic shortcuts, and stating that explicit parameters override the topic-mapped side. This goes beyond the schema alone.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating the tool's core function. It specifically identifies the two venues and the concept of a spread, distinguishing it from sibling tools like polymarket_arbitrage which focus on internal 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 explains two modes ('topic' shortcuts and explicit event codes) and provides context on when spreads are meaningful via safety fields. However, it does not explicitly compare this tool to other siblings like polymarket_arbitrage or state when not to use it, missing explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail (identifier-based) and usage pairing, which adds 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?

Three sentences with no waste. Front-loaded with primary action, each sentence provides distinct 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?

Simple tool with one optional parameter, no output schema. Description fully covers behavior, scope, and usage context.

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

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

Schema coverage is 100% for the single parameter 'key'. Description adds that omitting key lists all keys, which is useful additional meaning.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', with a specific verb and resource. It distinguishes itself from siblings 'remember' and 'forget'.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and mentions pairing with remember/forget. Does not explicitly state when not to use, 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 declare readOnlyHint=true and idempotentHint=true, but the description's mark_read:true behavior implies a state change (non-idempotent). The description adds useful context about mark_read but contradicts the idempotency annotation.

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

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

The description is front-loaded with the core purpose, then details filters and mark_read, and ends with alternative access. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description covers return fields, filter parameters, mark_read behavior, and polling suitability. It is complete for a feed retrieval tool with 5 optional parameters.

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 extra meaning by explaining how to filter ('Filter by type (e.g. sec_8k) and/or since'), elaborates on mark_read flag behavior, and mentions unread_only implicitly.

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 'Pull fired events from your subscription feed' and lists key attributes returned (source, citation_uri, payload). It is specific verb+resource, but does not explicitly distinguish from sibling tools like 'subscribe' or '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 includes filter options (type, since), mark_read behavior, and notes that polling works and the same feed is available via a REST endpoint. It provides good context for usage but does not explicitly state when not to use or compare to 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 transparently discloses the tool's fan-out behavior to multiple sources (SEC, GDELT/GNews, USPTO), fallback mechanisms, and soft-failure for patents. It also mentions the return structure (changes grouped by source, total_changes, citation URIs). Annotations already indicate read-only and idempotent behavior, which aligns with the description.

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

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

The description is well-structured with examples and clear explanations, but it is somewhat lengthy. However, every sentence adds value, and the key information is front-loaded with example queries. It could be slightly more concise, but remains 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 the tool's complexity (multiple data sources, fallbacks, parameter options), the description covers all necessary aspects: what inputs are accepted, what the tool does internally, and what the output looks like (structured changes, total_changes, citation URIs). It also mentions alternatives. No output schema exists, so the description adequately fills that gap.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining that 'since' accepts ISO dates or relative shorthand (with examples like '7d', '30d', '3m', '1y'), and that 'value' can be a ticker or zero-padded CIK. This extra context justifies a score above the baseline of 3.

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

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

The description explicitly states the tool provides a change feed for a company covering SEC filings, news, and patents. It includes example queries ('What's new with X', 'latest on Y') and clearly distinguishes itself from the sibling tool entity_profile by stating when to use each.

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 entity_profile instead when you want the static profile...'. It also gives examples of acceptable inputs and explains the fallback behavior between GDELT and GNews, which helps an agent decide when to use this tool.

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

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

Annotations indicate it's not read-only, not destructive, and idempotent. Description adds persistence details (persistent for auth users, 24h for anonymous) and scoping by identifier, which adds 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?

Concise with front-loaded purpose and usage. Every sentence adds value. Slightly wordy but still effective; could be tightened slightly.

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

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

Given only 2 simple params, no output schema, and good annotations, the description fully covers purpose, usage, persistence, and sibling relationships. Complete and well-rounded.

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

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

Schema coverage is 100% with good descriptions. Description adds example keys and value type, but doesn't significantly enhance schema-provided meaning. 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, specifying the resource (key-value store) and verb (save). It distinguishes from siblings recall and forget, making the purpose unambiguous.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget. Could be improved by stating when not to use, but 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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. Description adds that each call cascades through multiple internal endpoints, and details return values per type including citation URIs. 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?

Description is informative and front-loaded with usage examples and guidance. Slightly verbose but every sentence adds value; could be trimmed marginally.

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 return values for each type, including citation URIs. Covers internal cascading logic and positions the tool as a replacement for manual lookups. Complete for a 2-param tool with rich 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%. Description expands on each parameter: for 'company' explains accepted formats (ticker, CIK, name) and auto-disambiguation; for 'drug' explains brand or generic names. This adds significant 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 tool resolves user-spoken names to canonical identifiers, with specific examples ('What's the ticker for…'). It differentiates from sibling tools by positioning itself as the first step when an ID is needed.

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 advises 'Use FIRST whenever you have a name but need an ID.' Provides context that each call replaces multiple manual lookups, but does not explicitly list when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it probes each entity and returns a ranked list with score, confidence, and signal density, which is useful but does not significantly extend beyond the safety profile provided by 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?

Three sentences with clear front-loading of purpose, followed by how it works and a practical use case. Every sentence is informative 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?

Given the absence of an output schema, description adequately describes the returned structure (ranked list with score, confidence, signal density). However, it does not explain terms like 'signal density' or score range, which could be helpful. Overall sufficient for an agent to understand the tool's capability.

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

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

Schema coverage is 100% with good descriptions. Description adds value beyond schema by noting that 'First entry treated as the 'subject' for narrative; rest are competitors' and provides usage guidance for the 'models' parameter ('Omit for just workers-ai').

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 'Compare AI visibility across multiple entities side-by-side'. It specifies internal mechanism (ai_visibility_check) and output (ranked list). However, it does not explicitly differentiate from sibling tool 'compare_entities', which could lead to confusion.

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

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

Description provides a use case ('competitive AI-marketing audits') and an example question. It implies usage for multi-entity comparison but does not specify when not to use or list alternatives, leaving the agent to infer context.

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

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

Annotations already indicate read-only and idempotent; description adds key behavioral details: bundlephobia first measurement delay (5-30s), graceful degradation with sources_failed list, and NPM-only scope.

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

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

Single dense paragraph effectively communicates complexity, but could benefit from structure (e.g., bullet points for returned fields). Slightly long but 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, description fully enumerates return fields, error handling, and version listing. Complete for a composite tool with multiple data sources.

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

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

Schema already covers both parameters with descriptions (100% coverage). Description adds minor context about scoped packages and version default, but not much beyond schema.

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

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

The description clearly states it is a composite check for adding an npm package, combining deps.dev and bundlephobia data. It distinguishes from sibling tools like deps.dev:version 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?

Explicitly tells when to use ('is X safe / popular / small') and when not (other ecosystems via deps.dev:version directly). Covers partial failure behavior.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and output details (offsets and scores). 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 at 5 sentences, each serving a purpose: defining the tool, explaining usage, pairing, limitations, and technical details. It is front-loaded with the main action and avoids redundancies.

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

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

Given no output schema, the description adequately explains return values (top-N passages with offsets and scores). It also covers constraints and pairing, making it sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for the query parameter with natural-language examples, and hints at limit behavior (top-N). This exceeds baseline expectations.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs and resources. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded, indicating a different use case.

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

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

The description explicitly advises use when the record is too large for the prompt and explains benefits like saving context and providing offsets for verification. It also mentions pairing with ask_pipeworx_grounded, but does not explicitly state when NOT to use it.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the output structure (human-readable label, observing_quality verdict, best_window summary) and noting 'Keyless' (no authentication). 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 very concise, using three sentences that front-load the purpose and key details. Every sentence adds value, and there is no redundant or extraneous information.

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

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

With no output schema, the description adequately describes the return format (labels, verdict, summary) and resolution. It covers the essential information for a weather-like tool, though it could optionally detail label values or time range specifics.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description mentions 'Returned at 3-hour steps' for the hours parameter, but that is already in the schema description. No additional parameter semantics are added.

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 tool's purpose: providing an astronomy observing forecast with metrics (cloud cover, seeing, transparency) at 3-hour resolution out to 72 hours. It distinguishes itself from the sibling 'weather_forecast' by focusing on stargazing and astrophotography needs.

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

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

The description implies usage context by naming astronomy-specific metrics, but does not explicitly state when to use this tool versus alternatives like 'weather_forecast'. The mention of 'Keyless' provides a usage hint. Lacks explicit when-not or alternative guidance.

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

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

Annotations indicate readOnlyHint=false and no destructive action, but the description adds critical behavioral details: requires OAuth account, returns subscription ID, delivery limitations (SMS 10/day cap, phone verification, webhook signing secret, auto-disable after 10 failures). 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 long but densely packed with essential information. It is well-structured: purpose, requirement, types, delivery channels. However, it could be slightly more concise without losing clarity.

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

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

Despite no output schema, the description explains the return (subscription ID) and covers all aspects: purpose, prerequisites, parameter semantics, delivery details, and error/limitation notes. It provides a complete understanding 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 coverage is 100%, but the description enriches each parameter: 'type' with enum examples, 'params' with complete JSON structures per type, and 'delivery' with detailed constraints (phone verification, cap, webhook secret). This significantly aids correct parameter selection.

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.' It provides specific examples of supported types (sec_8k, polymarket_edge, etc.) and distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description specifies that a Pipeworx OAuth account is required and lists supported subscription types with usage examples. It implicitly guides usage by detailing the required parameters and delivery options, but does not explicitly contrast with tools like 'recent_alerts' for pulling alerts.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behaviors. The description adds that it returns example questions drawn from a live catalog, and that calling without arguments gives a full spread. This provides additional context on the output structure, though it doesn't discuss edge cases or potential delays.

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, starting with multiple example questions and a long list of categories. While front-loaded with key phrases, it could be more concise by stating the purpose and usage in fewer sentences. It earns a 3 because it is still readable and complete, but not optimally tight.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, when to use, parameter semantics, and expected output. It provides enough context for an agent to know exactly when and how to invoke it.

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

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

Schema coverage is 100% with a clear parameter description. The description goes beyond by explaining the effect of omitting the topic (cross-category spread) and listing possible values with examples, adding practical guidance that the schema lacks.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by specifying it should be used FIRST to learn what Pipeworx can do, and by mentioning meta-tools like ask_pipeworx, making the purpose unique.

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

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

The description explicitly advises to use this tool FIRST when clueless about Pipeworx's capabilities or to learn how to call meta-tools. It also explains when to pass the topic parameter versus omitting it, providing clear context compared to sibling tools that answer questions or perform searches.

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 false, destructiveHint false, idempotentHint true), the description adds that ownership is enforced and that the row is deactivated, providing behavioral context about mutation behavior and permanence.

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 succinct sentences, front-loaded with the core action, and no extraneous information. 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?

Given the simple input (one required param) and no output schema, the description adequately explains the effect (deactivation). However, it does not specify return values or error handling, so it is nearly complete.

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

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

The single parameter 'id' is already well-described in the schema ('Subscription id (uuid) returned by subscribe'). The description adds minimal extra meaning beyond 'by id', so a baseline score of 3 is appropriate given 100% 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 'Cancel a subscription by id,' using a specific verb and resource. This distinguishes it 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 provides important usage context: ownership enforcement and that the row is deactivated, not deleted. It implies when to use but does not explicitly mention alternatives or exclusion criteria.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the return structure (verdict types, extracted form, actual value with citation, percent delta) and explaining that it replaces multiple sequential calls. This contextualizes behavior beyond the annotations without contradiction.

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

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

The description is well-structured with initial examples, a clear use case statement, and then technical details. It is concise but comprehensive; every sentence adds value. Minor redundancy (listing example phrasings) could be trimmed, but overall it balances clarity and brevity.

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 required parameter and absence of output schema, the description fully covers what the agent needs: input format, supported claim types, and output structure. It even explains operational benefits (replacing multiple calls). No gaps remain for effective 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?

The single parameter 'claim' has 100% schema description coverage, so the baseline is 3. The description enriches this by specifying the type of claims supported (company-financial) and providing natural-language examples, making it clearer what constitutes a valid input.

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 for natural-language claim verification, provides example phrasings ("Is it true that…", "fact check", etc.), and explicitly distinguishes it from general research tools by focusing on claims against authoritative sources. It also specifies the domain (company-financial claims via SEC EDGAR + XBRL), leaving no ambiguity about purpose.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' While it provides strong guidance on when to use, it lacks explicit 'when not to use' or alternatives. However, the domain restriction (company-financial claims) implicitly guides agents away from other topics.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context about the data source, resolution (3-hour), range (72 hours), and keyless access, which supplements the annotations well.

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, information-dense sentence with no wasted words. It efficiently conveys source, parameters, output format, and constraints.

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

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

Given no output schema, the description thoroughly explains return values (temperature, humidity, condition code, cloud cover, wind, precipitation), resolution, and range. With annotations covering safety, it is complete 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 descriptions for each parameter. The description adds minimal extra meaning beyond the schema, only reiterating hours range and resolution. 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 provides a 'General weather forecast from 7Timer! CIVIL' and lists specific data points (temperature, humidity, condition code, cloud cover, wind, precipitation type), with resolution and range. It implicitly distinguishes from sibling 'stargazing_forecast' by being for general weather.

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 mentions 'Keyless' indicating no authentication needed, but does not explicitly state when to use this tool versus alternatives like 'stargazing_forecast'. It lacks explicit when-not or alternative guidance.

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