Data Va

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral details: probes multiple LLMs, requires API key for Anthropic, returns per-model data with scores/confidence/signals. It does not contradict annotations and provides useful context beyond the structured fields.

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

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

The description is a single, well-structured paragraph that front-loads the main purpose and then adds details. It is concise with no redundant information, covering all key aspects without being verbose.

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

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

Given no output schema, the description adequately describes return values ('per-model {score, confidence, signals, raw_response} + a combined view'). It also addresses use cases and required vs optional fields, providing sufficient context for an AI agent to understand the tool's purpose and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining default model ('Workers AI Llama-3.3-70b free'), that _apiKey is needed only for Anthropic, and that context helps disambiguate. It also clarifies that models array can be omitted 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?

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It uses specific verbs and resources, and distinguishes from siblings like scan_competitor_ai_presence by focusing on visibility scoring and multi-model support.

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

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

The description provides explicit usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default vs. paid models. However, it does not explicitly state when not to use it or compare to sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns a structured answer with stable citation URIs and is 'one fast call'. No contradictions. However, it doesn't detail behavior on ambiguous questions or error handling, but given rich annotations, the description adds value.

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 key guidance ('PREFER OVER WEB SEARCH') and uses examples effectively. Each sentence adds value, though the length is somewhat substantial. It is well-organized and not verbose.

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

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

Given the complexity (6 params, no output schema, rich sibling list), the description is comprehensive. It covers purpose, usage, alternatives, parameter nature, output format (structured with citations), tier compatibility, and performance. No obvious gaps.

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

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

Schema coverage is 100% with all parameters described as aliases for question. The description reinforces that multiple aliases work (query, q, prompt, text, input). Baseline 3, and the description doesn't add significant new semantic meaning beyond what the schema provides, but it's consistent.

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 routes factual questions to authoritative sources and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded (for hallucination-resistant single answers) and deep_research (for broad multi-part questions). The verb 'routes' and resource '4,819 tools' are specific.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing clear when-to-use guidance. It also gives examples of questions and contrasts with alternative tools (ask_pipeworx_grounded, deep_research, news), covering when to step up.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: routing, extraction process, refusal reasons like not_in_source, no_tool_match, etc., without contradicting annotations.

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

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

Description is fairly long but every sentence adds value: purpose, routing, return format, refusal reasons, usage guidance. Well-structured and front-loaded.

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

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

Even without output schema, description fully explains return format and all possible refusal reasons. Covers complexity (single required param, aliases, extra cost) and provides complete guidance for agent invocation.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for question. Description adds 'Your question in natural language' which adds little beyond schema. Baseline 3 is appropriate.

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

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

Clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and specifies it returns {answer, evidence, ...} or explicit refusal. Distinguishes from sibling ask_pipeworx by noting extra cost and preference for casual lookups.

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

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

Explicitly advises use when answers will be quoted/cited/acted on and the agent must not invent facts (e.g., financial, legal, medical). Also advises preferring ask_pipeworx for casual lookups.

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?

Extremely detailed: explains internal logic, resolver contract, parent event extractor, news fields, safety short-circuits, wide-spread warnings, cancellation rule parsing. Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds substantial 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?

Packed with information, well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded main purpose. Every sentence adds value, though the fan-out examples are lengthy. Still appropriate given tool complexity.

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

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

Covers all aspects: input, process, output fields, edge cases (closed markets, illiquid spreads, low-confidence resolution), and cancellation rules. No output schema, but the description fully compensates. The agent has everything needed to use and interpret results correctly.

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

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

Schema description coverage is 100%, baseline 3. The description adds clarity beyond schema: e.g., depth values ('quick = 2-3 evidence sources, thorough = full fan-out'), market input examples, and include_raw semantics with context on response size and use cases.

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

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

The description states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and gives specific use cases ('should I bet on X', 'what does the data say about Y'). It distinguishes well from sibling tools like polymarket_edges or compare_entities.

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

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

Provides clear usage context ('Use for should I bet on X') but lacks explicit when-not-to-use or direct alternatives. The description implies differentiation from siblings but does not name them.

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 that company data comes from latest 10-K via SEC EDGAR/XBRL with correct fiscal year handling, drug data from FAERS, results sorted by primary metric, and includes citation URIs. Annotations already indicate safe read-only behavior, and description adds rich 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 front-loaded with intuitive example phrases and structured as a single dense paragraph. Every sentence adds value, though it is slightly verbose. A minor improvement would be a shorter lead-in, but overall effective.

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

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

Covers purpose, usage guidance, parameter details, behavioral traits (data sources, sorting, citation URIs), and numbers of entities. No output schema exists, but the description adequately indicates what kind of data is returned, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, and description adds significant meaning: explains data sources for each type enum and specifies tickers/CIKs for company and names for drug in the values parameter, 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?

Description explicitly states 'side-by-side comparison of 2–5 companies or drugs' with concrete example phrases. It clearly distinguishes from sibling tools like entity_profile by specifying it replaces multiple sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups, providing clear when-to-use guidance relative 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?

Annotations already indicate safe, idempotent, read-only behavior. The description adds behavioral context by stating it returns specific fields and suggests downstream usage, which aligns 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?

Two concise sentences with no fluff. Front-loaded with action and resource.

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 search tool with no output schema, the description adequately explains purpose, input, and output. Could mention pagination specifics but not essential.

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

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

Schema coverage is 100%, so the schema already explains parameters. The description does not add parameter-specific meaning but provides output context, meeting the baseline.

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 searches the Virginia Open Data catalog by keyword and lists returned fields. It distinguishes from siblings by specifying a unique data source and use case.

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

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

The description implies when to use (to find datasets) and provides chaining guidance (pass resource_id to another tool). Could explicitly state when not to use, but current clarity is sufficient.

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 significant context beyond annotations: account requirement, depth levels, parallel decomposition, result format (findings packet with evidence/gaps), expected latency (15-60s), and that topics outside structured catalog yield empty gaps. No contradiction with readOnlyHint/idempotentHint.

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

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

Long but front-loaded with critical info (account, alternative tool). Every sentence adds value. Could be slightly more concise 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?

Covers all necessary aspects: purpose, usage context, behavioral nuances, parameter meanings, and expected outputs. No output schema exists, but description compensates by describing return format. Complete 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% and description adds clarity: explains depth enum values (quick=3, standard=5, thorough=8) and notes that questions can be multi-part. This provides 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?

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1259 STRUCTURED data sources' in one call, distinguishing it from open-web search. It also contrasts with sibling ask_pipeworx for single lookups.

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

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

Explicit guidance: best for broad/multi-part questions over structured data; use ask_pipeworx for single lookups or breaking news. Also mentions account requirements and paid plan for 'thorough' depth.

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 that returns top-N tools with names, descriptions, and full input schemas (curated examples), ready to call directly. Annotations already declare read-only, idempotent, non-destructive; description adds rich context beyond annotations.

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

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

Well-structured, front-loaded with purpose, and efficiently covers usage and return. A small reduction for slight redundancy in listing aliases which are also in schema.

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

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

Given no output schema, the description fully explains the return (top-N tools with schemas and examples). Parameter count and schema coverage are complete, and usage guidance is sufficient.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. Description mentions query aliases but adds little beyond schema for parameters. The curated examples mentioned are for results, not parameters.

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 discovers tools by describing a data or task, listing many domains. It distinguishes from sibling tools by positioning itself as the first call to browse available tools.

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

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

Explicitly states when to use ('browse, search, look up, or discover') and advises to call this first before other tools. No explicit when-not or alternatives, but context is strong.

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

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

Description details fan-out across SEC, XBRL, USPTO, news, GLEIF with specific return fields and limitations (soft-fail for patents). Annotations already indicate readOnly, idempotent, non-destructive; description adds substantial 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 comprehensive but well-structured with example queries up front. Slightly long but each sentence provides necessary detail for a complex tool. Minor redundancy possible but overall concise.

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

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

Despite no output schema, description clearly explains all return components and edge cases (patent sunset, name vs ticker). Covers input, behavior, output, and limitations thoroughly for a complex multi-source 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 2 parameters. Description adds meaning by explaining valid values for 'value' (ticker or CIK), format examples, and explicitly noting that names are not supported. Exceeds baseline 3.

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

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

Description clearly states tool profiles a US public company using multiple sources in one call. It uses specific verbs ('profile', 'tell me about') and resources ('company', 'cross-source profile'). Distinguishes from sibling tools like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and directs to resolve_entity for names. Provides clear when/not-to-use 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 provide destructiveHint=true and idempotentHint=true. The description adds context about stored memories and sensitive data but does not disclose additional behavioral traits like error handling for missing keys.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value with no fluff.

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

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

For a simple delete tool with one parameter and annotations covering safety and idempotency, the description provides sufficient context including usage guidelines and sibling pairing.

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

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

Schema coverage is 100% and the description does not add extra meaning beyond what the schema provides for the key parameter. 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 states 'Delete a previously stored memory by key' which is a specific verb and resource. It also distinguishes from siblings by saying 'Pair with 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?

The description explicitly says when to use it: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, which are sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds process details (fetching, extracting, emitting) without contradicting annotations, providing useful behavioral context beyond the structured fields.

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

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

The description is two short sentences followed by a bullet list of use cases. It is front-loaded with the core action and every sentence adds unique value. No wasted words.

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

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

For a simple tool with 2 parameters, no output schema, and comprehensive annotations, the description fully covers the tool's purpose, output format ('single text blob'), and common scenarios. It requires no additional explanation.

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 mentions 'any URL' aligning with the required url parameter but does not add detail about max_links beyond its schema description. It does not significantly enhance understanding of parameters.

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

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

The description clearly states the verb 'generate' and resource 'llms.txt file', specifies the purpose (AI crawler indexing), and lists concrete steps (fetch, extract, emit). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists three explicit use cases: client indexing, personal project drafting, and competitor auditing. While it doesn't exclude alternatives, the examples provide strong context for 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 mark read-only and idempotent. Description adds that it returns specific fields (id, type, params, timestamps, fire_count) and uses 'active' to imply default filter. 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?

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. No unnecessary words.

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

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

For a simple list tool, description covers what it returns and when to use. No output schema needed as fields are listed. Adequately complements sibling tools like subscribe and unsubscribe.

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

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

Only parameter include_inactive is fully described in schema. Description implicitly refers to it via 'active subscriptions' but does not elaborate further. Schema coverage is 100%, achieving baseline.

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 lists the caller's active subscriptions and enumerates returned fields. It distinguishes from sibling tools subscribe/unsubscribe by focusing on reading existing 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?

Explicitly advises use before adding more subscriptions or to find an id to cancel, providing clear context for when to invoke. Does not explicitly exclude other uses, but context is sufficient.

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 is read-only, idempotent, and non-destructive. The description adds the source (Virginia Open Data) and mentions the return contents, but does not contradict annotations.

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

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

The description is a single sentence with an example, containing no fluff. Every word is 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?

The description lists the returned metadata fields (columns, types, row count, category, last-updated), which is sufficient for a metadata retrieval tool without an output schema. It could mention whether results are paginated or limited, but it is adequate.

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

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

Schema coverage is 100%, and the description provides an example value for resource_id, adding meaning beyond the schema itself.

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 retrieves schema and metadata for a Virginia Open Data dataset by resource_id, with a specific example. It is distinct from sibling tools, which are mostly unrelated.

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

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

The description implies when to use the tool—when schema/metadata is needed—but does not explicitly state when not to use it or provide alternatives. However, the context is clear given sibling tool names.

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

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

Annotations provide minimal safety profile (all false). The description fully compensates by disclosing that the tool sends data to the team (mutation), is rate-limited (5 per identifier per day), and is free (doesn't count against tool-call quota). It also explains the impact ('signal directly affects roadmap'). 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 a single, well-structured paragraph that front-loads the core purpose, then provides usage guidelines and behavioral details. Every sentence adds necessary information without redundancy or fluff. It is concise yet comprehensive.

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 feedback tool without an output schema, the description covers input requirements, usage context, rate limits, and behavioral details. It does not describe the response after submission, but that is not critical for tool selection. The description is adequately complete for an agent to use correctly.

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

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

Schema coverage is 100%, so descriptions of parameters are already present. The tool's description adds value by elaborating on the enum values for 'type' (e.g., 'bug = something broke'), specifying that 'context' is optional, and providing guidance for 'message' ('Be specific... 1-2 sentences typical, 2000 chars max'). This enhances understanding beyond the schema.

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

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

The description starts with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly specifying the action (send feedback) and resource (Pipeworx team). It enumerates specific use cases (bug, feature/data_gap, praise) and implicitly distinguishes from sibling tools like 'ask_pipeworx' or 'query' by stating it's for reporting issues, not asking questions.

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

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

The description provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells what not to do ('don't paste the end-user's prompt') and explains how to describe issues ('in terms of Pipeworx tools/packs'). Additional details like rate limits and quota are included.

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 crucial behavioral context beyond annotations: self-aggregating from CF analytics engine, no PII, caching behavior (5min-1h). Annotations already indicate read-only, idempotent, non-destructive.

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

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

Three sentences, front-loaded with core purpose, no redundant phrasing, 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?

Fully covers what the tool returns, source, caching, and parameter semantics. No gaps given the single optional parameter and 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?

Only one parameter 'window' with 100% schema coverage. Description adds interpretive guidance: shorter windows for hot topics, longer for steady-state demand.

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?

States verb 'Returns' with specific resources: top tools, top packs, total call volume over a window. Distinguishes from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing on trending usage 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 lists three use cases, providing clear when-to-use guidance. Does not explicitly mention when not to use or compare to siblings, but context implies it's the go-to for trending signals.

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

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

The description adds substantial behavioral context beyond annotations. It details the trending scan scope, partition check logic, Jaccard similarity threshold for cross-event pairing, placeholder filtering, and fill check mechanics. Annotations only indicate read-only, idempotent, open-world behaviors; the description enriches with concrete constraints and signals like skipped_low_similarity and placeholders_filtered.

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

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

The description is long but well-structured with capitalized sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that chunk information logically. Every sentence adds value; however, some repetitive phrasing (e.g., 'cross-event mode' explained twice) could be trimmed slightly for improved 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?

Without an output schema, the description thoroughly covers return values including opportunities array fields and partition_check object. It also describes fill check outputs and links to sibling tools for next steps. Given the tool's complexity, the description is remarkably complete, leaving no critical gaps about behavior or output.

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

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

Parameter schema coverage is 100%, so baseline is 3. The description adds significant meaning by providing examples of event slugs and full URLs, explaining the difference between event and topic modes, and describing internal logic each mode triggers. This goes beyond the schema's simple parameter descriptions.

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

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

The description opens with a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states what the tool does and distinguishes it from sibling tools like polymarket_edges (edge-focused) or polymarket_fill_risk (fill risk focused).

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 when to use each parameter: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan.' It also advises when to use sibling tools like polymarket_fill_risk for custom sizing and references fill_check for pricing verification, providing clear guidance on alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds significant behavioral context, including caching details (1h at KV level, keyed on all knobs), diagnostic outputs, and rare-by-design segments. While it does not contradict annotations, it provides valuable depth beyond them.

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

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

The description is very long and dense, but it is well-structured with clear sections for purpose, segments, output fields, knobs, and response format. It is front-loaded with the main goal. However, it could be more concise without losing essential 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?

Given the complexity of the tool (9 parameters, no output schema, rich response), the description is remarkably comprehensive. It explains the three model families, output fields including diagnostics, and all knob behaviors. The absence of an output schema is fully compensated by the detailed description.

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 semantics beyond the schema, e.g., 'Bump for very thin partitions' for slippage_pp and explaining that min_partition_leg_kelly applies inside partition legs. This enriches the parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings by focusing on edge discovery across multiple model families, unlike polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly says the tool is built for agents to discover opportunities without paging hundreds of markets, and it details tradeable-edge knobs for filtering. However, it does not explicitly name sibling tools for comparison or state when not to use this tool versus alternatives like polymarket_arbitrage.

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. Description adds limits (60-day TTL, snapshot dependencies, gaps on no scan) and decay calculation details (daily closes, not intraday), providing useful behavioral context beyond annotations.

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

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

Description is front-loaded with purpose, then parameters, then detailed response format, then limits. Slightly verbose but each section adds value; no wasted sentences.

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 thoroughly explains the response structure: tracked[], expired[], snapshot_dates[] with field details. Also covers limits and derivation, making it self-contained for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. Description adds defaults (14 days, '1wk'), maximum (30 days), and clarifications for 'window' families, enhancing understanding of parameters.

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 provides edge persistence and decay telemetry from daily snapshots, answering how long edges exist and if they are shrinking. It contrasts fresh vs old edges, but does not explicitly differentiate from sibling tool 'polymarket_edges'.

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

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

Implied usage context: the tool is for assessing edge aging, with the example that an old wide edge is different from a fresh one. No explicit when-to-use/when-not-to-use or alternative tools mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the tool is safe. The description adds valuable behavioral details: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and highlights forced directional risk. This goes well 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 comprehensive and well-structured, front-loading purpose and modes. It is longer than average but every sentence contributes meaningful information. Some redundancy in explaining side defaults across description and schema, but overall efficient for the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains all return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers usage context, limitations, and risk warnings, making it fully self-contained for an agent to understand behavior and outputs.

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

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

Schema coverage is 100% with descriptions for all 4 parameters, but the tool description adds global context: it explains the REQUIRES relationship between market/event, interprets size_usd differently for single-market vs basket, and clarifies side defaults. This adds value 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market vs basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, telling the agent to use this before those.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills create directional risk), effectively telling 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 declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral context: response format with leg-by-leg prices, safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions when spreads are meaningless.

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

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

The description is detailed and front-loaded with purpose, but it is lengthy and could be slightly more concise. However, all information is relevant 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 no output schema, the description comprehensively explains the response structure, safety fields, and interpretation of warnings. It covers all necessary context for correct usage.

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 three parameters described. The description adds meaning by explaining the two modes, listing valid topics, and describing how explicit tickers override the topic-mapped side.

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

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

The description clearly states the tool computes spread between Kalshi and Polymarket for the same resolving question, and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The two modes (topic shortcuts and explicit tickers) are clearly defined.

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 topic shortcuts vs explicit tickers, and warns that most pre-mapped topics are not tradeable due to compatibility issues. Provides clear guidance on when not to use (when compatibility_warning fires).

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, and non-destructive behavior. The description adds value by specifying that SoQL clauses should be provided without the leading '$' and that results are returned as JSON, which is not covered by annotations. 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 two concise sentences that front-load the main action and key details (SoQL clauses, output format). Every part is informative and there is no wasted text.

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 states the return format (JSON). It also mentions the data source (Virginia Open Data) and the syntax constraints. Missing details like pagination limits are covered by parameters (limit/offset). Slightly more context about typical use cases could improve completeness.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining how parameters map to SoQL clauses and providing concrete examples (e.g., resource_id 'rdpw-mtbs', where filter syntax, order clause). This helps the agent understand the parameter semantics.

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

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

The description clearly specifies the action (run a SoQL query), the target resource (Virginia Open Data dataset by resource_id), and the capabilities (clauses like where, select, group, order, plus limit/offset). It also distinguishes from sibling 'datasets' tool by referencing resource_id as obtained from datasets.

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

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

The description implies usage context (querying a dataset) and provides syntax hints for SoQL clauses, but does not explicitly state when to use this tool versus alternatives like 'datasets' for metadata or 'search_within' for different search types. No exclusions or when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds scoping behavior and the dual retrieval/list functionality. No contradiction.

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

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

Three sentences, each substantive: action definition, usage context, scope and tool ecosystem. No redundant or extraneous text.

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 fully covers input behavior, use cases, and tool lifecycle. Sufficient for 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 already describes the one parameter (key) with equivalent phrasing ('omit to list all keys'). Description adds no new detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a saved value (by key) or lists all keys (omit key). It distinguishes from sibling tools 'remember' and 'forget' by specifying the operation and pairing instructions.

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: to look up context stored earlier, with examples (ticker, address, notes). Also notes scoping to identifier and pairs with remember/forget for lifecycle management.

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 reveals a mutation side effect (mark_read:true flags events as read), contradicting the annotations' readOnlyHint=true. This is a serious inconsistency, disqualifying the description's transparency despite other good details.

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

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

The description is a single paragraph, front-loaded with the main purpose, and covers multiple aspects efficiently without unnecessary words.

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

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

For a tool with 5 optional params and no output schema, the description sufficiently covers purpose, parameter behavior, return fields, polling usage, and alternative access, leaving no major gaps.

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

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

Though schema coverage is 100%, the description adds value by explaining the purpose of mark_read, filtering by type and since, and mentioning returned fields, going beyond schema descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed, specifies returned fields, and mentions filtering options. However, it does not explicitly distinguish itself from sibling tools like 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 context on when to use the tool (polling, filtering by type/since, mark_read behavior) and mentions an alternative access method. It does not explicitly state when not to use it among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds fan-out to multiple sources (SEC, GDELT→GNews fallback, USPTO), sunset note for PatentsView, and output structure. 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?

Single paragraph but front-loaded with examples. Covers a lot of information efficiently. Slightly dense but appropriate for the complexity. Not overly verbose.

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

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

Given the complexity (multiple sources, fallback, parameter formats, sunset status), the description is very complete. Even without an output schema, it explains the return structure. No gaps.

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

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

Schema coverage is 100%, but description adds meaning: explains since accepts ISO date or relative shorthand with examples, clarifies value can be ticker or CIK, and notes type is only 'company' for now. Goes 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?

Description starts with clear examples like "What's new with X" and states it is a change feed for a company. It distinguishes from the sibling tool entity_profile by contrasting dynamic vs static profile. The verb+resource+scope is 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?

Provides explicit usage examples and contrast with entity_profile. Recommends parameter values (e.g., '30d' for monitoring). Lacks explicit when-not-to-use but positive guidance is strong.

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

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

Disclosure beyond annotations: key-value scoping, persistence duration (24 hours for anonymous, persistent for authenticated). 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?

Four sentences, each serving a distinct purpose: purpose, when to use, storage details, pairing with other tools. No unnecessary 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?

Covers all essential aspects for a write operation: purpose, usage context, persistence behavior, and related tools. No output schema needed for this tool.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds context with example usage patterns (e.g., 'subject_property', 'target_ticker'), which enhances understanding beyond 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?

Clearly states 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from siblings recall and forget by mentioning them explicitly.

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 ('discover something worth carrying forward') and provides examples. Mentions alternative tools recall and forget for retrieval and deletion.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds behavioral context: internal cascading through multiple endpoints and specific return formats (e.g., ticker + CIK + company_name + citation URI for company). 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 front-loaded with user-facing examples, then explains behavior and supported types. It is concise yet covers necessary detail. Slightly longer than minimal, 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?

Given no output schema, the description adequately explains return values for both entity types (company and drug). It covers disambiguation and citation URIs. Could mention error cases (no match found), but is complete enough for typical use.

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

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

Schema coverage is 100%, but the description adds extensive meaning: for the 'type' parameter, it lists supported types with detailed examples; for 'value', it provides concrete examples (ticker, CIK, brand/generic name) and explains auto-disambiguation. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical identifier, with examples like 'what's the ticker for...' and explicit mention that it outputs identifiers required by other tools. It distinguishes itself from sibling tools like entity_profile or compare_entities by focusing on resolution.

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

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

The description includes explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing safety and non-destructiveness. The description adds behavioral context: it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

The description is concise with 4 sentences, each adding value: purpose, process, use case, and output. Front-loaded with the main action. No redundant or unnecessary words.

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

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

Given moderate complexity, no output schema, and 4 parameters, the description explains the process, output structure, and use case. It mentions the constraint of 2-8 entities (from schema) and adds the subject treatment. Adequate for correct tool invocation.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds extra meaning: the first entity is treated as the 'subject' for narrative, providing context beyond the schema. This improves usability.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by explicitly mentioning AI visibility and multi-entity side-by-side comparison.

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

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

The description gives a concrete use case: competitive AI-marketing audits. It implies use when comparing multiple entities and suggests ai_visibility_check for single entities, but does not explicitly exclude alternatives like compare_entities or provide when-not-to-use guidelines.

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 significant behavioral context beyond annotations: describes fan-out across services, partial failure graceful degradation, and timing caveat for bundlephobia's first measurement.

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 core purpose and concise given complexity; though lengthy, every sentence adds value. Could be slightly more structured but still effective.

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

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

Despite no output schema, description fully specifies return format including summary block fields, advisory details, links, and alternative versions, plus failure behavior.

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

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

Schema covers both parameters with descriptions; description adds usage nuance (scoped packages accepted, version defaults to latest) and clarifies behavior 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 checks whether to add an npm package to a project, specifying the resource (npm package) and action (composite check). It distinguishes from siblings by noting other ecosystems fall under a different tool.

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

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

Explicitly says to use when agent asks about safety, popularity, or cost, and gives exclusion for non-npm ecosystems, directing users to deps.dev:version.

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

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

Annotations already provide readOnlyHint, etc., and description adds value beyond: details on embeddings (BGE-base-en), similarity (cosine), windowing (500-char overlapping), cap (200K chars), truncation flagging, and offset 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?

Single coherent paragraph, front-loaded with purpose, each sentence contributes. Slightly dense but not overly verbose.

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

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

Despite no output schema, the description covers algorithm, constraints, use case, and integration with sibling tool, making it complete 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%, and description adds meaning: explains text as 'document text to search inside', query examples, limit default, and semantic nature of search.

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

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

Clearly states it performs 'semantic search INSIDE a fetched record', specifies action and resource, and distinguishes from siblings like ask_pipeworx_grounded by highlighting offset return and pairing.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes how it pairs with ask_pipeworx_grounded, providing clear when-to-use and alternative.

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

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

Annotations are present (readOnlyHint=false, idempotentHint=true, etc.) and the description adds significant behavioral context: requires a Pipeworx OAuth account, phone verification for SMS, 10/day SMS cap, webhook auto-disable after 10 failures, signing secret returned only once. No annotation contradictions. The description enhances transparency beyond annotations.

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

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

The description is well-structured and front-loaded: first states purpose and auth requirement, then lists types with examples, then delivery channels. Every sentence adds value without unnecessary repetition. It is concise yet comprehensive.

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

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

Given no output schema, the description covers prerequisites (OAuth account), type-specific params, delivery options with constraints, and notes return value (subscription id). It is complete for a subscription creation tool with no obvious gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds substantial meaning beyond the schema: concrete examples for each type (e.g., items codes for sec_8k, topics for polymarket_edge), detailed param structures, and delivery constraints like phone verification and HMAC signing. This makes the parameters far more understandable.

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 'Create' and the resource 'proactive monitoring subscription to a live-data event stream,' and specifies it returns the new subscription id. It distinguishes from sibling tools like `list_subscriptions`, `unsubscribe`, and `recent_alerts` by focusing on creation.

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

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

The description provides clear context on when to use the tool (for live-data event streams) and includes supported types and delivery channels. However, it does not explicitly state when not to use it or compare directly to alternatives, e.g., 'use list_subscriptions to view existing ones.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds value by explaining the output format (category-bucketed questions with tool+argument shape) and behavior regarding the optional topic argument. 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 front-loaded with alternative phrasings and structured with a list of categories. It is slightly verbose but every sentence adds value. Could be more concise, but it's 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 simple schema and annotations, the description fully covers purpose, usage, and output format. It explains what the tool returns and when to use it, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the description adds that omitting topic gives a full spread and passing a topic focuses the results. This adds some context but does not significantly expand beyond the schema's description. 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 is the onboarding entry point, returning category-bucketed example questions. It specifies the verb 'returns' and defines the resource ('example questions with exact tool + argument shape'). It distinguishes from siblings by positioning itself as the first-use tool for learning Pipeworx's capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides clear context for when to use the tool but does not explicitly state when not to use it or highlight alternatives, though the context implies it's for initial exploration.

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 meaningful context beyond annotations: ownership enforcement (security) and soft deactivation with side effect on historical events via recent_alerts. Consistent with idempotentHint and destructiveHint.

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

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

Two efficient sentences with front-loaded purpose. Every sentence adds value; no wasted words.

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

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

Single-parameter tool with good annotations. Description explains side effects, ownership, and ties to sibling tools. Sufficient for correct usage.

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

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

Schema covers 100% of parameters with clear description. Description doesn't add extra parameter context but reinforces the use of 'id'. 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?

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and soft deactivation.

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?

Ownership enforcement ('only cancel your own subscriptions') provides a clear usage constraint. Lacks explicit when-not-to-use or alternative tools, but context is sufficient for correct invocation.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds: returns verdict types, structured form, actual value with citation, percent delta, and underlying data source (SEC EDGAR + XBRL). 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?

Single paragraph, front-loaded with examples and usage context. Every sentence adds value. Slightly dense but well-organized. Could be split for readability but not penalized.

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 one parameter and no output schema, description covers return values (verdict, structured form, value, citation, delta), domain, and efficiency. Minor lack on citation format details, but overall 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?

Only one parameter 'claim' with 100% schema description coverage. Description provides two realistic examples ('Apple's FY2024 revenue was $400 billion', 'Microsoft made about $100B in profit last year'), adding practical 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's purpose as 'natural-language claim verification against authoritative sources' with specific examples ('Is it true that…', 'fact check') and domain restrictions (company-financial claims). It distinguishes from siblings by mentioning it replaces 4-6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Also implies scope (company-financial claims for public US companies) and efficiency over alternatives. Lacks explicit 'when not to use' but strong implicit guidance.

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