Data Energystar

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

Annotations provide read-only, idempotent, open-world hints. The description adds behavioral context: cost model (free default, BYO for Anthropic), return structure (per-model score, confidence, signals, raw_response + combined view), and that the API key is passed straight through. No contradictions.

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

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

The description is a single, well-structured paragraph of around 6 sentences. It front-loads the core action, then details defaults, optional behavior, return format, and use cases. 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?

Despite lacking an output schema, the description compensates by detailing the return structure. All 4 parameters are explained, purpose and usage are clear, and use cases are provided. The tool is not overly complex, and the description is sufficient for an agent to select and 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 description coverage is 100%, so baseline is 3. The description adds value by elaborating on entity (examples), models (omission defaults to workers-ai), _apiKey (direct pass-through), and context (disambiguation). It provides richer guidance than 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 probes one or more LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic, and lists use cases like AI-marketing audits, pre-launch checks, and competitive monitoring, distinguishing it from siblings.

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

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

The description explicitly states when to use the tool (e.g., AI-marketing audits, pre-launch brand checks) and mentions the optional Anthropic key requirement. It does not explicitly state when not to use it versus alternatives, but the context is sufficient for typical use cases.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it routes questions, fills arguments, returns structured answers with citation URIs, and is a fast one-call default entry point. 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 fairly long but well-structured with clear sections. It is front-loaded with the key preference statement. Some repetition of examples, but overall informative and earns its length.

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

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

Covers purpose, usage, behavior, and return format. Lacks details on error handling or rate limits, but given the complexity and presence of other structured fields, it is adequately complete.

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

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

Schema coverage is 100% with all parameters documented. The description lists examples and mentions that the question parameter accepts natural language, but this is already in the schema. No additional parameter-level detail 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 that the tool answers factual questions about real-world entities, events, or numbers by routing to 4,482 tools across 1129 sources. It provides specific examples and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete guidance on when to use this tool vs. alternatives (step up to ask_pipeworx_grounded for hallucination-resistant, deep_research for broad questions). It also lists typical user query patterns.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it costs one extra LLM call, returns a refusalReason for various failure modes, and uses only the tool result. No contradictions found.

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, front-loading purpose and behavior, then usage guidance, return format, and trade-offs. It is informative without being excessively verbose, though could be slightly more compact.

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 high-stakes tool with no output schema, the description fully explains the return format, refusal reasons, and cost trade-off. It also provides usage context and examples, making it complete for agent selection and invocation.

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

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

Schema coverage is 100% with each parameter having a description. The description adds that the question is in natural language and lists aliases, but this is minimal beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as 'Hallucination-resistant answer mode for high-stakes reads,' specifying its unique capability to extract answers only from tool results, and distinguishes it from the sibling ask_pipeworx by highlighting the extra cost and groundedness.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides concrete examples like financial verdicts, legal claims. Also advises preferring 'ask_pipeworx for casual lookups,' offering clear differentiation.

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 extensively discloses behavioral traits beyond annotations, including resolution confidence handling, fan-out logic, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread tradeability flags, and resolution-rule risk parsing. It adds significant context that annotations alone do not provide, and there is no contradiction with annotations.

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

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

The description is dense and front-loaded with core purpose, but it is quite long (multiple paragraphs). While all information is valuable, some details (e.g., exhaustive fan-out examples) could be summarized or placed in an output schema if one existed. It is not concise.

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

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

Given the tool's complexity (multiple data sources, safety logic, resolution risk) and lack of output schema, the description thoroughly explains return shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fields, and blocking paths. It is complete for an agent to understand behavior without ambiguity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining parameter semantics beyond the schema, such as what 'quick' vs 'thorough' depth means and the effect of include_raw on response size. It also provides examples of valid market_input values.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and differentiates from sibling tools like polymarket_edges by focusing on data retrieval and evidence packet 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 provides explicit use cases such as 'should I bet on X' and 'what does the data say about Y', and gives extensive examples. However, it does not explicitly state when not to use this tool or contrast with alternatives like polymarket_edges, which would improve guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: explains data sources (SEC EDGAR XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, and specifies result sorting by primary metric. No contradictions.

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

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

The description is front-loaded with trigger phrases and remains focused. Each sentence adds value, though it is slightly verbose. It could be trimmed slightly without losing meaning.

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

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

Given the tool has only 2 parameters and no output schema, the description thoroughly explains input requirements, data sources, and output format (paired data, citation URIs, sorted results). No critical information is missing.

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

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

Schema coverage is 100%. The description adds meaning by explaining the enum values ('company' vs 'drug'), min/max items for values array, and provides examples (e.g., tickers for company, drug names). It goes beyond what the schema documents.

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

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

The description uses specific verbs like 'compare', 'side-by-side comparison', and specifies resources: companies (using SEC EDGAR data) or drugs (using FAERS data). It distinguishes itself from sequential lookups by explicitly recommending it over 8-15 sequential calls.

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

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

The description clearly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups') and provides usage patterns ('compare X and Y', 'which is bigger'). It explains data sources for each entity type but does not explicitly mention when not to use it or alternative tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the exact fields returned (resource_id, name, description, category, update date) and advising to pass resource_id to query/metadata for further details.

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

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

Two sentences with no waste: first states purpose, second describes output and follow-up action. Information is front-loaded and every sentence earns its place.

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

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

Given the absence of an output schema, the description adequately covers return fields and usage flow. Parameters are fully specified in schema, and annotations confirm safety. No gaps remain for an agent to use the tool correctly.

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

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

All three parameters are fully described in the input schema (100% coverage). The description only mentions 'by keyword' which aligns with the query parameter, but adds no significant meaning beyond what the schema provides.

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

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

The description clearly specifies the verb 'Search' and the exact resource 'ENERGY STAR Open Data catalog of open datasets'. It also lists the exact fields returned, distinguishing it from sibling tools that may search other domains.

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 use when searching for datasets by keyword in the ENERGY STAR catalog. It does not explicitly state when not to use or list alternative tools, but the context of sibling tools makes its use case clear.

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

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

Description adds significant behavioral context beyond annotations: decomposes question into facets, routes to 4,482 tools in parallel, returns findings packet with evidence, confidence, source, citations, and gaps[], with 15-60s expectation. No contradiction with annotations.

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

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

Description is lengthy but well-organized: critical account info first, then tool capability, usage guidance, output format, and limitations. Every sentence contributes, though slight redundancy could be trimmed.

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

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

Despite no output schema, description fully covers input meaning, behavioral steps (decomposition, parallel routing), output structure (findings packet with evidence, gaps), limitations, and expected duration. No gaps in understanding.

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% (2 params), so baseline is 3. Description adds value by explaining depth enum values (quick=3, standard=5, thorough=8 paid) and confirming question can be broad/multi-part. This elevates the score.

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

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

The description explicitly states the tool performs 'grounded multi-source research across Pipeworx's 1129 structured data sources' in one call, distinguishing it from open-web search and siblings like ask_pipeworx. It uses specific verbs and resources.

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?

Clear guidance: best for broad/multi-part structured-data questions; for single lookups or breaking news, prefer ask_pipeworx. Also notes account requirements and depth limitations.

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 idempotentHint=true. The description adds that results include names, descriptions, and full schemas with curated examples, and each result is ready to call directly. No contradictions; adds useful behavioral context.

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

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

Description is moderately long but each sentence adds unique information. It starts with the core purpose and then provides usage guidance, examples, and return details. Could be slightly shorter, but still 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?

Despite no output schema, the description sufficiently explains return value (top-N tools with schemas), mentions read-only/idempotent nature (consistent with annotations), and gives examples. For a discovery tool with simple parameters, this is comprehensive.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining aliases (e.g., query, q, task, search, description) and providing concrete examples, which helps agents understand how to phrase queries.

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 discovers available tools by describing a task/data, using verbs like 'find', 'browse', 'search', and 'look up'. It distinguishes from siblings by focusing on exploration of the toolset, while siblings like 'datasets', 'deep_research', and 'entity_profile' serve different specific purposes.

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

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

Explicitly advises to call this tool FIRST when many tools are available, and lists many example use cases (SEC filings, financials, etc.). It does not explicitly state when not to use or provide alternatives, but the sibling list and context imply it's for discovery, not for specific 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds specific details: fans out across multiple sources, includes a patent soft-fail timeline, and describes fallback mechanisms. 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 well-structured with examples first, then purpose, then details. Every sentence adds value, and it's appropriately detailed for a complex tool 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?

Despite lacking an output schema, the description thoroughly itemizes return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and mentions limitations (patent soft-fail, name restriction). This is comprehensive for a profile 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%. The description enriches param meaning by explaining type must be 'company', value accepts ticker or CIK, and explicitly states that names are not supported, which is not in the schema.

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

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

The description clearly defines the tool as providing a holistic cross-source profile of a US public company in a single call, with examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from siblings like resolve_entity by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also instructs to use resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description doesn't need to restate them. The description adds value by explaining the purpose (clearing stale or sensitive data) and its role with sibling tools. 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 two sentences, front-loading the action, then providing usage context. Every sentence is essential, 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 one parameter, full annotation coverage, and no output schema, the description covers the purpose, usage context, and relationships to siblings. It is complete and self-contained.

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

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

The input schema has 100% coverage with a description for the required 'key' parameter. The description simply says 'by key' which adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and the context of 'key' distinguishes it from sibling tools like remember (store) and recall (retrieve).

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: '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, providing clear context for usage, though it does not explicitly list when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: fetching the page, extracting title/description/key links, and emitting standard markdown format. It explains the process and output, going beyond annotations without contradiction.

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

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

The description is concise: three sentences plus a bullet list. Every sentence adds value: purpose, behavior, output format, use cases. No wasted words, front-loaded with the core action.

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

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

Given no output schema, the description adequately explains the return format (single text blob ready to drop at site-root). It covers purpose, usage, behavior, and parameters, leaving no major gaps for a tool with low complexity.

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

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

Schema coverage is 100%, and the description adds meaningful details: for URL, it gives an example; for max_links, it states default (25) and max (50). This clarifies usage beyond the schema's basic descriptions.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the verb (generate), resource (llms.txt), target (any URL), and the purpose for AI crawlers. This is distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence, even though not explicitly compared.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. It tells when to use the tool but does not mention when not to use it or compare directly to alternatives. Still, the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds specific output fields and clarifies active vs inactive. 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?

Two sentences front-loaded with purpose, no waste, efficient.

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

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

Given simple tool with one optional param and no output schema, description covers purpose, output, and usage guidance fully.

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

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

Schema coverage is 100%, so baseline 3. Description doesn't elaborate on the parameter further, but schema is sufficient.

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

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

Clear verb 'List', resource 'subscriptions', and scope 'caller's active'. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing context for when to use. No explicit when-not but 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 cover read-only and idempotent behavior. The description adds useful output specifics (columns, types, etc.) and an example, but no additional behavioral traits like limitations are described.

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?

A single sentence of 20 words front-loads the core purpose and includes key details. Every word adds value, making it highly efficient.

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

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

For a simple metadata retrieval tool with one parameter and no output schema, the description adequately explains the return content. Minor gaps like error handling or pagination are not critical here.

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

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

Schema coverage is 100% with a clear description for the single parameter. The description's example mirrors the schema, adding no new semantic value beyond what the schema provides.

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

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

The description clearly states the tool gets schema and metadata for a dataset, with specific details like columns, types, row count, category, and last-updated. It includes an example resource_id, making the purpose unambiguous.

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

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

The description implies use when metadata is needed but does not explicitly state when not to use it or mention alternatives among siblings. No guidance on exclusions or 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?

Beyond the annotations (which indicate non-read-only, non-idempotent, non-destructive), the description adds valuable behavioral info: rate-limited, doesn't count against tool-call quota, team reads digests daily, feedback 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 clear and front-loaded with purpose, followed by usage guidelines and behavioral notes. It's reasonably concise, though it could be slightly more compact. Still, every sentence adds value.

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

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

For a simple feedback tool, the description covers all necessary aspects: purpose, input types, usage guidelines, rate limits, and impact. No output schema is needed since the action is one-way, and the description explains what happens (team reads, affects roadmap).

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 parameters. The description adds value by explaining the type enum values (bug, feature, data_gap, praise) and reminding users to describe issues in terms of Pipeworx tools/packs, enhancing usability 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?

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about broken, missing, or needed items. It explicitly lists use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by focusing on feedback rather than queries or actions.

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

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

The description provides explicit when-to-use guidance (bug, feature/data_gap, praise) and what not to do (don't paste end-user's prompt). It also mentions rate limits (5 per identifier per day) and that it's free and doesn't count against quota, giving complete usage 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 declare readOnly, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h).

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

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

Concise and well-structured. Front-loaded with core function, then use cases, then technical details. Every sentence adds value.

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

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

For a simple read-only tool with one optional param and no output schema, the description covers purpose, use cases, caching, data source. 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%. Description adds semantic guidance for each enum value: 'Shorter windows surface what's hot right now; longer windows show 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?

Description clearly states it returns top tools, packs, and call volume over a window. Unique among sibling tools like discover_tools or ask_pipeworx.

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

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

Three explicit use cases provided (discovering hot data, confirming canonical choice, checking alignment). No explicit when-not-to-use but context is clear.

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

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

The description extensively details internal checks: monotonicity violations, partition-sum checks, Jaccard similarity filtering, placeholder filtering, and fill check against live CLOB depth. This goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), providing behavioral context.

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

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

The description is long but well-structured and front-loaded with the requirement. Every sentence adds value, though some minor trimming could improve conciseness without losing essential detail.

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 (two modes, multiple checks, fill check, no output schema), the description is thoroughly complete. It explains the output structure, internal filtering logic, and the fill check process, leaving no apparent gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond the schema, providing examples of event slugs and topic seeds, and explaining how each parameter affects behavior (single-event vs cross-event mode).

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

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

The description clearly identifies the tool as finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode and topic mode, and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states that one of 'event' or 'topic' is required, and explains when to use each mode (event for specific market, topic for cross-event scanning). It also references the sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: details on model families, caching (KV-level 1h), response structure with diagnostics, and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). 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 lengthy but well-structured, with clear sections and front-loaded purpose. Every sentence adds value, but the verbosity (especially in model family details) slightly reduces conciseness. It is appropriately sized for the complexity.

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

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

With no output schema, the description fully explains the response structure: by_segment, fed_candidates/fed_note, and _diagnostics. It lists key fields (edge_pp_net, etc.) and caching behavior. Given 9 parameters and complex output, the description is complete and self-contained.

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

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

Schema coverage is 100%, yet the description adds significant meaning: e.g., min_kelly 'Skips opportunities that are too small', min_edge_pp 'Edge is evaluated NET of slippage', slippage_pp provides context on Polymarket fees and adjustment advice. min_partition_leg_kelly clarifies its difference from min_kelly. Each parameter gains practical guidance.

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 and returns opportunities where Pipeworx data disagrees with market price. It specifies 'what should I bet on today' and distinguishes from siblings by detailing its unique segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its purpose unmistakable.

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

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

The description provides explicit context for when to use this tool: 'agents discover opportunities without paging hundreds of markets.' It details tradeable-edge knobs and filters but does not explicitly state when to use alternatives or when not to use this tool. The sibling list implies distinction but lacks direct exclusions.

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, etc., so the safety profile is known. The description adds behavioral details beyond annotations: it explains what the response contains (tracked, expired, snapshot_dates), limits (60-day TTL), and computation details (decay from daily closes). No contradiction.

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

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

The description is well-structured with clear sections for response details and limits. It front-loads the purpose and is appropriately sized given the complexity. Slightly verbose but efficient overall.

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?

Although there is no output schema, the description fully documents the response structure (tracked, expired, snapshot_dates) with field-level details. It also covers limitations and computation methods. Given the tool's complexity and lack of output schema, the description is complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates defaults and clamps but adds minimal new meaning beyond the schema (e.g., specifying max 30 for days). Baseline 3 is appropriate as the description does not significantly enhance 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 states the tool is for edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It uses specific verbs like 'track' and 'compute,' and distinguishes itself from siblings like polymarket_edges by focusing on historical time-series behavior rather than current snapshots.

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

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

The description provides context on when to use (to differentiate fresh vs. old wide edges) and explains the response structure. However, it does not explicitly state when not to use it or compare to alternatives like polymarket_edges, though the sibling names imply a difference. Still, usage context is clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral details: walks the ladder, returns verdict (clean|degraded|cannot_fill), explains basket fill risks like thin_legs and forced_directional_risk. 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?

Long but well-structured with bold headings, mode sections, and a clear usage exhortation at the end. Each sentence adds value given the tool's complexity. Slightly verbose but justified by the need to explain two modes and multiple return fields.

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

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

Despite no output schema, the description thoroughly explains all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), prerequisites (market or event required), default behaviors, and usage advice. Covers all necessary context 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%, baseline 3. The description adds extra meaning: explains the two modes (market vs event) with parameter usage, default values for side and size_usd, and basket-specific interpretation of size_usd as settlement notional. This exceeds the schema.

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

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

The description clearly states it checks 'realizable-vs-theoretical edge against live CLOB order-book depth' with two distinct modes (single-market and basket), and lists specific return fields. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why (theoretical overround not capturable on thin books, partial fills convert arb to directional position), providing clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description significantly expands on these by detailing compatibility_warning conditions (bet shape mismatches, semantic mismatches), temporal_alignment constraints, and counters for skipped comparisons. It fully discloses the tool's behavioral traits and limitations, going well beyond the annotations.

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

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

The description is well-structured with clear sections (TWO MODES, SAFETY FIELDS) and uses bullet-like formatting. While comprehensive, it is slightly dense and could be trimmed without losing essential information. It earns its length by providing critical context for understanding tool behavior.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and warns that most pre-mapped topics may return warnings. The description is self-sufficient for an agent to understand inputs, outputs, and caveats.

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

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

The input schema has 100% coverage with descriptions for all 3 parameters. The description adds substantial value by explaining the two operational modes (topic vs. explicit) and how explicit parameters override topic mappings. This provides semantic understanding beyond the raw schema definitions.

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

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

The description clearly states it computes the cross-venue spread between Polymarket and Kalshi for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by explicitly comparing two venues and detailing two distinct modes (topic shortcuts and explicit event tickers). The verb 'spread' and resource 'Polymarket–Kalshi' are specific and unambiguous.

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

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

The description explains when to use the tool (to compare spreads between venues) and provides detailed safety warnings about compatibility and temporal alignment, implicitly indicating when not to trust results. It does not explicitly mention alternative tools, but the context of sibling tools suggests polymarket_arbitrage might be an alternative for single-venue analysis. The guidelines are clear and context-rich.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details: returns matching rows as JSON, note about no leading $ in SoQL clauses, and implies data retrieval without side effects. No contradiction with annotations; the description complements them well.

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

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

Two concise sentences: the first states the main purpose with an example, the second details filtering and output format. Every sentence adds essential information with no fluff. Structure is front-loaded with the most critical information.

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

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

Given no output schema, the description mentions JSON output. It covers the key elements: dataset, filtering via SoQL, pagination. However, it omits potential error handling, rate limits, or behavior when no results are found. For a read-only query tool with rich annotations, this is nearly complete.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing an example for 'resource_id' and clarifying that SoQL parameters should omit the leading $. This helps the agent understand the syntax beyond the schema's 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 clearly states the tool runs a Socrata SoQL query against an ENERGY STAR Open Data dataset, identifies the resource_id format with an example, and explains the filtering options (where, select, group, order, limit, offset) and output format (JSON). This distinguishes it from siblings like 'datasets' which likely return dataset listings.

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 mentions the tool is for running queries with specific SoQL clauses (no leading $) and pagination. While it doesn't list alternatives or exclusions, the context of sibling tools (e.g., 'datasets' for discovery) implies appropriate usage. A more explicit 'when to use vs. other tools' statement would improve clarity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key (listing all keys). 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 sentences plus one additional sentence for scoping and pairing. Every sentence is informative and necessary; no wasted words. Front-loaded with the primary action.

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

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

Given one optional parameter, no output schema, and annotations, the description fully explains behavior (with key and without), scoping, and relationship to sibling tools. 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% and the description's explanation of the key parameter ('Memory key to retrieve (omit to list all keys)') closely mirrors the schema description. Adds no new meaning beyond the schema.

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

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

The description clearly states the verb ('Retrieve' or 'list') and the resource ('a value previously saved via remember' or 'all saved keys'). It distinguishes itself from sibling tools like remember and forget by explicitly pairing with them.

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 examples of when to use ('look up context... user's target ticker, an address, prior research notes') and explains the scoping mechanism. Does not explicitly state when not to use, but the use case is well-defined.

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 annotations declare readOnlyHint:true, indicating no modifications. However, the description states that setting mark_read:true flags events as read and affects subsequent calls, which is a write side effect. This contradicts the annotation, resulting in a score of 1 per instructions.

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 (6 sentences) and front-loaded with the purpose. It includes necessary details without being verbose. Minor improvement could be structuring parameter explanations more consistently.

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 parameters and no output schema, the description covers the return structure (source, citation_uri, raw payload), explains key parameter behavior (mark_read), and provides usage context (polling, alternative URL). This is comprehensive 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%, so baseline is 3. The description adds value by explaining the effect of mark_read (changes future calls) and mentions type and since parameters. It does not cover limit or unread_only, but the schema already documents them. The additional context raises the score slightly.

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 pulls fired events from a subscription feed and returns recent alerts. It specifies the resource (fired events/subscription feed) and the action (pull). The description also distinguishes it from sibling tools by focusing on alert retrieval with filtering and marking read.

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 this tool (for interactive polling of alerts) and mentions an alternative endpoint for scripts/dashboards. It does not explicitly state when not to use it or compare to other sibling tools like 'subscribe' or 'list_subscriptions', but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral details: fans out to three source types, explains fallback behavior, notes USPTO soft-fail until May 2025, and specifies the return format (changes[] grouped by source, total_changes count, and citation URIs). This adds significant context beyond the annotations.

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

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

The description is lengthy but well-structured, front-loaded with query examples. Every sentence provides value, though some redundancy exists (e.g., explaining fallback twice). It balances detail with readability, earning a 4 rather than 5 due to minor verbosity.

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

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

Given the tool's complexity (multiple sources, fallback logic, no output schema), the description is comprehensive. It explains the return structure (changes[], total_changes, citation URIs) and lifecycle details (USPTO sunset). No output schema means the description must carry return format information, which it does thoroughly.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description adds extra usage guidance: explains `since` accepts ISO date or relative shorthand with typical monitoring value ('30d' or '1m'), and clarifies that `value` can be ticker or CIK. It also reinforces that `type` currently only supports 'company'. This goes beyond the schema alone.

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

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

The description clearly states the tool returns a change feed for a company across SEC filings, news (with fallback), and patents. It distinguishes itself from the sibling tool 'entity_profile' by noting that uses the static profile. The verb 'returns structured changes' and resource 'company change feed' 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 provides explicit example queries ('What's new with X', 'latest on Y') and explains when to use the alternative tool ('Use entity_profile instead when you want the static profile'). It also details the fallback logic for news sources (GDELT preferred, GNews on rate limit/5xx).

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 details beyond annotations: scoping by identifier, persistence duration for authenticated vs anonymous users, and idempotency implication. 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?

Highly concise with 4 sentences, front-loaded with main purpose, and no fluff. Every sentence provides value.

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

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

For a simple tool with 2 parameters and no output schema, the description covers all necessary aspects: purpose, usage, behavior, and parameter context.

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

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

Schema coverage is 100% with well-described parameters. The description adds context for use (e.g., 'Memory key') but does not significantly enhance semantics 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 action ('Save data') and resource ('data the agent will need to reuse later'), with specific examples. It distinguishes itself from siblings by mentioning 'recall' and 'forget' 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?

Explicit guidance on when to use ('when you discover something worth carrying forward') and pairing with alternative tools ('Pair with recall to retrieve later, forget to delete') provides clear context for selection.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant context: it internally cascades through several lookup endpoints, replaces 2-3 manual lookups, and details exact return fields (ticker + CIK + company_name + citation URI for company; RxCUI + ingredient + brand + citation for drug). No contradiction with annotations.

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

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

The description is concise yet comprehensive: three sentences plus a structured list of supported types. It front-loads common use queries, uses bullet-like formatting for clarity, and every sentence adds value. No wasted words.

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

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

Despite no output schema, the description fully compensates by detailing the exact return values for each entity type, including citation URIs. It covers usage, input formats, internal behavior, and the tool's role relative to siblings. For a two-parameter lookup tool, this is complete and actionable.

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 enriches both parameters: for 'type' it explains the return differences (SEC EDGAR vs RxNorm) and for 'value' it specifies accepted input formats (ticker, CIK, name for company; brand/generic for drug) with examples. This goes well beyond the schema's basic 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 starts with specific example queries ('What's the ticker for…', 'find the CIK for…') and clearly states the tool resolves a name to a canonical/official identifier. It explicitly distinguishes itself by noting that other tools require these IDs as input, aligning with the sibling list.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types (company, drug) with input examples. While it doesn't explicitly mention when not to use it, the guidance is strong and contextually sufficient given the 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 readOnly/openWorld/idempotent/destructive, so no contradiction. Description adds value by explaining internal behavior (probes each entity with ai_visibility_check, ranks by score) and return format (ranked list with score, confidence, signal density).

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

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

Four sentences, front-loaded with primary purpose, examples, and return format. No extraneous information.

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

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

Covers main return structure (ranked list with score, confidence, signal density) even without output schema. Missing details on error handling or max entities limit, but sufficient for 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?

100% schema description coverage, so baseline 3. Description mentions parameters indirectly (entities, models, context) but adds minimal new detail beyond schema. For example, 'context' is described as 'shared context applied to every probe' which matches schema description.

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

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

Description clearly states the verb 'compare' and resource 'AI visibility across multiple entities', distinguishing it from sibling 'ai_visibility_check' which is single-entity. Examples like 'does Claude know about us as well as our competitors?' reinforce purpose.

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

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

Description provides context for use ('competitive AI-marketing audits') and implies comparison of multiple entities. However, it does not explicitly state when to use alternative 'ai_visibility_check' for single entities.

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

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

Discloses fan-out to two external services, partial failure behavior (5-30s delay for first bundlephobia measurement), and that sources_failed lists timeouts. Annotations (readOnly, idempotent, not destructive) are consistent and description adds valuable operational context.

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

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

Two sentences, front-loaded with purpose. Contains necessary detail but could be slightly more concise. Still efficient for the amount of information conveyed.

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

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

Since output schema is absent, description fully covers return values: summary block fields, per-advisory details, links, and recent versions. Also addresses partial failures, making it complete for a complex composite tool.

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

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

Schema coverage is 100% with clear descriptions. The tool description does not add significant meaning beyond the schema (e.g., 'npm package name' and 'specific version' are already documented). 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?

Describes a composite check for adding npm packages, fans out to deps.dev and bundlephobia. Clear verb (scan/check), resource (npm dependency), and distinguishes from siblings by noting NPM-only scope in v1 and alternatives for other ecosystems.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost. Mentions NPM ecosystem only and fallback for other ecosystems. No explicit when-not, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Description adds significant context: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', 'cap is 200K chars (longer inputs are truncated and flagged)', and 'every passage carries an offset so the agent can verify a verbatim quote.' 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?

Description is concise (approx. 120 words) and well-structured: starts with core purpose, then usage guidance, then technical details. Every sentence adds value; no redundancy or fluff.

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

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

Despite no output schema, the description clearly explains return values (passages, character offsets, similarity scores). It covers input constraints (200K char cap), processing details (500-char windows, BGE embeddings), and error handling (truncation flagged). Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds value beyond: for 'text' it gives examples of what to pass (SEC 10-K body, article), for 'query' it provides natural-language examples (supply-chain risk, fiscal year 2024 revenue), and for 'limit' it mentions default 5. This enriches understanding beyond the schema descriptions.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb (search) and resource (text/record). It explains what the tool returns (top-N passages with offsets and scores) and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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 provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant behavioral details beyond annotations: requires OAuth, always-on feed with optional email/sms/webhook channels, SMS phone verification and daily cap, webhook auto-disable after 10 failures, and HMAC signing for webhooks. Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, which are consistent. No contradiction.

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

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

The description is a single paragraph with multiple lines, front-loading the core purpose and prerequisites. Every sentence adds value, though it is slightly verbose (e.g., including full examples). It is structured logically: purpose, prerequisite, types, delivery.

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 (3 params, nested objects, no output schema), the description covers prerequisites, parameter examples, delivery behavior, and return value ('Returns the new subscription id'). It could mention the response structure more explicitly and whether duplicate subscriptions are prevented, but overall is thorough.

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

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

Schema description coverage is 100%, but the description adds concrete JSON examples for each subscription type (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and explains delivery channels with constraints (SMS cap, webhook auto-disable, HMAC secret). This adds substantial value beyond the schema.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions returning a new subscription ID. The verb 'create' and resource 'subscription' are clear. It distinguishes from sibling tools like list_subscriptions, recent_alerts, and unsubscribe, which are for management and retrieval.

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

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

The description specifies a prerequisite: requires a Pipeworx OAuth account; anonymous/BYO cannot persist subscriptions. It implies use for persistent live-event monitoring. It does not explicitly contrast with sibling query tools like ask_pipeworx or query, but the context of subscription creation vs. one-time queries is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context by explaining that the tool returns category-bucketed example questions and describes the structure of the response. It does not contradict annotations and provides meaningful behavioral detail 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 relatively long but well-structured, with a clear listing of categories. Every sentence contributes value. It could be slightly more concise, but the detail aids understanding.

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

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

Given the single optional parameter, no output schema, and rich annotations, the description is fully complete. It explains purpose, usage, parameter semantics, and the nature of the response. No gaps are apparent.

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

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

Schema coverage is 100% with a single optional 'topic' parameter. The description adds significant meaning by listing the allowed values and explaining that omitting it returns a full cross-category spread. This clarifies the parameter's purpose beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It uses specific verbs and resources, and distinguishes itself from sibling tools like 'discover_tools' and 'ask_pipeworx' by its focus on generating example queries.

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

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

The description explicitly says to '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 also explains when to pass the optional 'topic' argument. However, it does not explicitly state when not to use it, though the context is clear.

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

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

The description adds significant transparency beyond annotations: it states ownership enforcement, deactivation rather than deletion, and preservation of historical events. Annotations already indicate non-destructive and idempotent behavior, and the description complements them effectively.

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

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

The description is two sentences, front-loads the main action, and includes all necessary context with no wasted words. It is perfectly 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?

For a simple single-parameter tool with no output schema and informative annotations, the description provides complete context: purpose, ownership, effect (deactivate vs. delete), and links to a sibling for historical data. No gaps remain.

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

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

With 100% schema coverage and a parameter description that already states 'Subscription id (uuid) returned by subscribe', the description's mention of 'by id' adds minimal extra meaning. Baseline is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id.') with a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation and ownership enforcement.

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 the tool (cancel a subscription) and notes ownership enforcement, implying you cannot cancel others' subscriptions. It also mentions historical events stay available via 'recent_alerts', providing context on an alternative. However, it lacks explicit 'when not to use' or direct sibling comparisons.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses return values (verdict types, structured form, citation, delta) and the data source (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is moderately concise, front-loading use-case examples. Every sentence adds value, but it could be slightly tightened. Still 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?

Lacking output schema, the description fully explains the return types and sources. It also mentions limitations (v1 supports company-financial claims only), making it complete for the tool's complexity.

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

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

The single parameter 'claim' is well described in both schema and description. Schema coverage is 100%, and the description adds clarifying examples and domain context, providing added value beyond the schema.

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

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

The description clearly states it is for natural-language claim verification against authoritative sources. It specifies the verb 'validate claim' and distinguishes from siblings by noting it replaces multiple sequential calls and focuses on company-financial claims.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and mentions the supported domain. While it doesn't list alternatives, the context suggests it is optimized for financial claims and is more efficient than sequential calls.

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