Data Norfolk

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds details about default model, optional Anthropic probing with BYO key, and return format, which are valuable beyond annotations.

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

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

Three sentences with clear front-loading: first sentence defines core purpose, second explains model options, third describes return format and use cases. No fluff, 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 no output schema, the description adequately details return values (per-model score, confidence, signals, raw_response + combined view). It covers parameters and use cases well, though minor constraints like model limits are omitted.

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

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

Schema coverage is 100%, but the description adds value by explaining default model behavior, when _apiKey is needed, and providing concrete examples for entity. This helps clarify usage beyond schema.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility 0-100, with specific verbs and resource. It distinguishes from siblings like `entity_profile` and `scan_competitor_ai_presence` by focusing on AI visibility scoring across models.

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

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

The description mentions use cases for AI-marketing audits, pre-launch brand checks, and competitive monitoring, providing context for when to use. However, it does not explicitly exclude alternatives or compare to related 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context about routing to many tools, filling arguments, and returning structured answers with citation URIs. 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 slightly long but well-structured with a clear hierarchy: preference instruction, what it does, when to use, examples, and step-up alternatives. Front-loaded with key guidance.

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 (many sources, no output schema), the description covers all needed context: purpose, scope, usage rules, examples, and fallback paths. It explains that results include citations, compensating for missing output schema.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by listing aliases and explaining the question parameter's role in natural language, though the schema already conveys the meaning.

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

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

The description clearly states the tool routes questions to 4,482 tools across 1,129 sources for structured data. It specifies the types of queries (SEC filings, FDA data, etc.) and gives concrete examples. It also distinguishes itself from sibling tools like web search and deep_research.

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

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

The description explicitly instructs to prefer this over web search and to start here for most questions. It provides clear when-to-use and when-not-to-use guidance, naming alternatives (ask_pipeworx_grounded, deep_research) and giving examples of appropriate queries.

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

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

The description discloses the full return format including fields like evidence, confidence, source, and refusal_reason, plus possible refusal values. It explains the extra cost ('one extra LLM call') and the mechanism of extracting answers only from tool results. Annotations are readOnly, idempotent, openWorld, non-destructive, and the description aligns without contradiction.

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

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

The description is dense and well-structured: it begins with the core purpose, then explains the mechanism, return format, and usage guidance. Every sentence adds value. It could be slightly more concise, but it is efficient for the amount of information provided.

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

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

Given the simple input schema (just a natural language question) and the rich annotations, the description fully covers return format, refusal cases, cost, and when to use. There is no output schema, so the description compensates completely. The agent has all information needed 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?

The input schema has 6 parameters (all aliases for 'question') with 100% description coverage. The description adds that the question is 'in natural language' and lists the aliases, but this adds minimal 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 states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from sibling 'ask_pipeworx' by highlighting the extra extraction step and refusal mechanism. The verb 'answer' and resource 'tool results' are well-defined.

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

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

The description explicitly tells when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples like financial verdicts and medical lookups. It also advises to prefer 'ask_pipeworx for casual lookups,' providing clear when-not-to-use guidance.

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

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

Annotations indicate idempotent, read-only, non-destructive behavior. The description adds extensive context: fan-out logic, response shapes, resolver contract (confidence levels, alternatives), parent_event extraction, news fallbacks, safety checks (low-confidence short-circuit, closed market detection, wide spread notes), and resolution-rule risk analysis. This far exceeds what annotations provide.

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

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

The description is lengthy but front-loaded with the core purpose. Every sentence adds value, covering classifiers, fan-out examples, response fields, and edge cases. While not minimal, the density of useful information justifies the length for a complex tool.

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, classifiers, resolver logic, safety checks, resolution rules) and the absence of an output schema, the description is extraordinarily complete. It explains all relevant aspects: inputs, fan-out, response shapes, confidence handling, parent events, news fields, and even resolution-rule risk.

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

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

Schema coverage is 100% (all 3 parameters have descriptions). The description adds examples for 'market' (slug, URL, question text), explains 'depth' (quick vs thorough) and 'include_raw' (when to use true for full payloads). It also provides fan-out examples, making parameter semantics exceptionally clear.

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 outputs (evidence packet + comparison). This distinguishes it from siblings like polymarket_edges, which focus on edge detection across multiple bets.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes guidance on when to inspect confidence fields and when results are suppressed. However, it does not explicitly say when not to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that company data comes from SEC EDGAR/XBRL with off-calendar fiscal year handling, and drug data from FAERS. It also mentions sorted results and citation URIs. 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 dense paragraph, but each sentence serves a purpose. It front-loads with example queries and uses short, clear phrases. Could be slightly more structured (e.g., bullet points) but remains effective and 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 tool with 2 parameters and no output schema, the description adequately explains what data is returned (paired data, citation URIs) and the sources. It covers both entity types and notes sorting. No major gaps given the annotations and schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: examples of values (tickers/CIKs for company, names for drug) and explains what each type retrieves. This goes beyond the schema's enum and descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It includes example queries that match natural language, and distinguishes from single-entity tools like entity_profile. The verb 'compare' and resource 'entities' 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?

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to use this tool instead of alternatives, which is rare and valuable. No exclusion criteria are needed.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the list of return fields but does not disclose additional traits like rate limits or authentication requirements.

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

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

Two sentences with zero waste. Front-loaded with the core action and resource, followed by return fields and next step.

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

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

For a simple search tool with rich annotations and full schema coverage, the description adequately covers return values and usage hint. No output schema is needed as return fields are explicitly listed.

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 three parameters. The description does not add new semantic meaning beyond the schema examples, so baseline score of 3 is appropriate.

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

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

Clearly states the verb 'Search', the specific resource 'Norfolk Open Data catalog of open datasets', and the purpose 'by keyword'. Distinguishes from sibling tools by specifying the source and return fields.

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?

Describes when to use (keyword search) and provides a hint for further action ('pass the resource_id to query/metadata'). However, lacks explicit guidance on when not to use or alternatives among siblings.

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

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

Beyond annotations (read-only, open-world, idempotent), the description reveals detailed behavior: returns verbatim evidence with confidence, source, fetched_at, and pipeworx:// citation; includes gaps[] for unanswered facets; mentions parallel execution of 4,482 tools; and expects 15-60 second runtime.

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: starts with account requirement, then purpose, usage guidance, and behavior. It is front-loaded with critical info and each sentence adds value. Minor redundancy could be trimmed, but overall efficient for the complexity.

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

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

Given no output schema and high complexity, the description covers all essential aspects: return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps[]), timing expectation, and data source scope. It leaves no critical gaps for an agent to understand the tool's output and behavior.

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

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

The description adds significant meaning to the depth parameter, explaining the number of facets for each setting (quick=3, standard=5, thorough=8) and noting default. For question, it clarifies that broad/multi-part questions are acceptable. Schema coverage is 100%, but the description enhances understanding.

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

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

The description clearly states that deep_research performs grounded multi-source research across structured data sources, decomposing questions into facets and routing to tools in parallel. It distinguishes itself from siblings like ask_pipeworx and provides specific use cases.

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

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

Explicit guidance is given: use ask_pipeworx for single lookups or current news, and note that 'thorough' depth requires a paid plan. Also advises using ask_pipeworx if not signed in, providing clear when-to-use and when-not-to-use criteria.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it returns top-N relevant tools with names, descriptions, and full input schemas, and emphasizes that no second schema lookup is needed. 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 purpose and usage. Each sentence adds value for an agent selecting this tool. It could be slightly more concise, but the level of detail is appropriate for the tool's complexity.

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

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

No output schema exists, but the description explains that the tool returns top-N results with names, descriptions, and full input schemas (with curated examples). This covers the main output expectations. Given the moderate complexity, it is complete enough.

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

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

Schema coverage is 100%, but the description adds meaning by explaining that query accepts multiple aliases (task, q, description, search) and provides examples of natural language queries. This goes beyond the schema's property descriptions.

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

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

The description clearly states the verb ('Find'), the resource ('tools'), and the specific action ('by describing the data or task'). It distinguishes itself from siblings by emphasizing that it returns ready-to-call tools with full schemas and examples, and advises calling it first when many tools are available.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and lists many domains. It also advises 'Call this FIRST when you have many tools'. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral context: it fans out across multiple sources, returns specific data, handles patents with soft-fail, and executes in one parallel call. 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 well-structured with examples at the start. It is detailed but not overly verbose. However, it could be slightly more concise given 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?

Given the complexity (multiple data sources, no output schema), the description is comprehensive. It lists all return components (CIK, filings, fundamentals, patents, news, LEI) and mentions fallback behaviors (patents soft-fail, GDELT→GNews fallback). Covers both input constraints and output details.

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

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

Schema coverage is 100%, but description adds meaning: explains type enum (only 'company'), value as ticker or zero-padded CIK, explicitly notes names are not supported. This enhances the agent's understanding beyond the schema.

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

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

The description clearly states the purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs. It distinguishes from sibling tools by recommending this tool over chaining single-pack lookups.

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

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

Explicitly advises when to use: 'when the user asks for a holistic view.' States alternatives: 'ALWAYS PREFER over chaining' and 'use resolve_entity first' for name-based queries. Notes limitations like patents sunset and unsupported name input.

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 destructive and idempotent nature. Description adds context by framing deletion as clearing sensitive data, aligning with annotations without contradiction. Adds value beyond 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?

Two sentences, highly concise, front-loaded with the action. Every sentence serves a purpose without redundancy.

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

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

Given low complexity (single required param, no output schema), the description adequately covers purpose, usage, and parameter. Lacks details on return value or confirmation, but sufficient for a simple delete operation.

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

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

Schema coverage is 100% with a clear parameter description. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by its destructive action.

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

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

Provides clear when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with related tools, offering both usage context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context on what the tool does (fetch page, extract title/description/links, output standard markdown). No contradictions; the behavioral insight is adequate but could mention limitations (e.g., only works on public URLs).

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

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

The description is concise with two main sentences and a bullet list of use cases. It front-loads the core action and purpose, and every sentence provides value without unnecessary 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?

Given low parameter count (2), full schema coverage, and rich annotations, the description adequately covers the tool's functionality and output. It explains what the output looks like and where to use it. Minor gaps: no mention of error handling or edge cases like invalid URLs.

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 both parameters are documented. The description does not add new semantic information beyond what the schema provides; it only reinforces the purpose. No extra detail on parameter usage or constraints.

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 an llms.txt file for a given URL. It uses specific verbs ('generate', 'fetches', 'extracts') and identifies the resource ('llms.txt file'). No sibling tool performs the same function, so it distinguishes itself well.

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 concrete use cases: indexing client sites, drafting for own projects, auditing competitors. However, it does not explicitly state when not to use the tool or mention alternatives, slightly reducing guidance 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, idempotentHint, and destructiveHint. The description adds value by specifying the default behavior (active only), the optional include_inactive parameter, and the exact fields returned, which goes beyond the structured annotations.

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

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

Two sentences: first gives purpose and return fields, second gives usage guidance. No wasted words, front-loaded information. 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?

Simple tool with one optional boolean param, no nested objects. Description covers purpose, return fields, default behavior, and use cases. No gaps remain.

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

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

Schema coverage is 100% (include_inactive described). The description does not add new parameter semantics; it only implicitly mentions the default (active) but the schema already covers that. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, params, etc.), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context and implies when not to use (e.g., for subscribing/unsubscribing).

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds no further behavioral traits, such as response format details or error scenarios. It is adequate but does not exceed what annotations provide.

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

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

The description is a single clear sentence, front-loaded with the verb 'Get', and includes a concrete example. 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 one-parameter tool with good annotations and no output schema, the description sufficiently informs what the tool returns (specific metadata fields) and how to use it (resource_id format and example). It is complete enough 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 coverage is 100% and includes description for parameter 'resource_id'. The description repeats the example but adds no new semantic meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns a dataset's schema and specific metadata fields (columns, types, row count, category, last-updated) by resource_id, with an example. This distinguishes it from siblings like 'datasets' which lists available datasets, and 'query' which runs 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 provides no explicit guidance on when to use this tool vs alternatives. While the purpose is clear enough to infer usage context, there is no mention of when not to use or which sibling tools to consider instead, which would improve decision-making.

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?

Since annotations are all false (readOnlyHint, openWorldHint, etc.), the description carries the full burden. It discloses rate limits (5 per identifier per day), that it's free, and that the team reads digests daily. 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 five sentences, front-loaded with purpose, and every sentence adds value. No redundant or unclear phrasing.

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

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

Given the simple nature of the tool (sending feedback) and the fully described input schema, the description is complete. It covers usage, constraints, and format. No output schema needed.

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 reiterating enum meanings in a narrative form and providing context on how to write the message (be specific, 1-2 sentences, 2000 chars). This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team. It lists specific use cases (bug, feature, data_gap, praise) and contrasts with sibling tools that are primarily for querying or research.

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

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

The description provides explicit guidance on when to use the tool (bug, feature, data_gap, praise) and what not to do (do not paste end-user prompt). It also mentions rate limits, free usage, and that it doesn't count against quota.

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, etc.), the description discloses the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and computation method. Adds significant 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?

Three sentences, each earning its place: first defines what it returns, second lists use cases, third explains derivation and caching. Front-loaded and efficient.

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

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

Given the simple schema (1 optional param) and rich annotations, the description fully covers behavior, use cases, and implementation details. 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?

The schema covers 100% but the description adds value by explaining the semantics of window choices ('surface what's hot' vs 'steady-state demand') and mentions the default value.

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

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

The description states a specific verb ('Returns') and a clear resource ('top tools, top packs, and total call volume over a recent window'), which distinguishes it from siblings like 'ask_pipeworx' or 'discover_tools'.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming popular tool, aligning use case) and mentions caching durations. Missing explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true. The description adds rich behavioral detail: response structure (opportunities[] with fields), semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs), and fill check logic (theoretical vs realizable edge). 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 lengthy but well-structured: starts with a bold requirement, then explains two modes, details on filters, response, and fill check. Every sentence adds value. Some redundancy (e.g., fill check explanation could be tighter) but overall efficient for the complexity.

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

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

Given the tool's complexity (multiple modes, complex logic with monotonicity, partition checks, fill checks), the description covers all critical aspects: input requirements, behavior, response structure, special filters, and integration with polymarket_fill_risk. No gaps identified.

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: explains the behavioral difference between event and topic modes, gives example slugs, and describes the internal operations (walking child markets, searching related events). Adds value beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes two distinct modes (event vs topic) with specific use cases and examples. This differentiates it from sibling tools like 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 requires one of `event` or `topic` and warns that calling with no args fails. Guides when to use each mode with examples (event for specific market, topic for cross-event scanning). Recommends polymarket_fill_risk for custom sizing. Lacks explicit 'do not use when X' but overall strong 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, and idempotentHint=true. The description adds substantial behavioral context, such as caching at KV level keyed on knobs for 1 hour, response structure with diagnostics explaining empty segments, and disclosure that Fed bets are excluded from ranking due to unreliable signals without paid data.

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

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

The description is very long and detailed, which is necessary for a complex tool, but it could be more concise by consolidating some technical explanations. It uses bold headers and lists, which helps structure, but the overall length is high.

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

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

Given no output schema, the description fully explains the return values, including top-level fields like by_segment, fed_candidates/fed_note, and _diagnostics, as well as per-opportunity details like edge_pp_net, kelly_fraction, and market metadata. It covers all model families and filtering knobs, making it complete for an agent to use.

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

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

Schema coverage is 100%, so every parameter has a description. The description adds extra context beyond the schema, such as why min_partition_leg_kelly exists versus min_kelly for partitions, and practical advice on slippage_pp and max_spread_pp. This adds meaningful meaning beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific verb ('scan') and resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by emphasizing it is the primary discovery tool for daily betting decisions.

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 strong context by stating it is 'built for 'what should I bet on today'' and explains parameter knobs like min_liquidity, max_spread_pp, and max_spread_pp with usage advice. However, it does not explicitly mention when not to use this tool versus alternatives, though the sibling context implies 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, destructiveHint false. The description adds significant context: data comes from daily snapshots, limits (60-day TTL, snapshot start date), decay computed from daily closes not intraday, and explanation of expired opportunities. 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 clear sections (purpose, args, response, limits) and front-loads the core purpose. It is slightly verbose but every sentence adds value. Could be trimmed for brevity.

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

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

Despite no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and limitations (60-day TTL, snapshot start, decay calculation). This gives the agent a complete picture of what to expect and constraints.

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 default values and clamps for 'days' and explains the 'window' parameter (snapshot family). This is helpful but not extensive beyond what the schema already 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses specific verbs ('answers how long has this edge existed') and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis 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 explicitly explains the tool's value ('a fresh wide edge and a 3-week-old wide edge are different trades') and implies when to use it. It provides response structure details (tracked, expired, snapshot_dates) which guide the agent in interpreting results. However, it does not explicitly state when not to use this tool vs alternatives like polymarket_edges.

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. The description adds behavioral context beyond annotations, such as explaining that it walks the ladder, returns fill quality metrics, and warns that theoretical overround on thin books is not capturable. 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 well-structured with sections, but somewhat verbose. It packs necessary detail for a complex tool but could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description fully covers return fields, edge cases (thin books, partial fills), and warnings. It leaves no major gaps for an agent to understand what the tool returns and when to use it.

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

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

Schema description coverage is 100% (baseline 3). The description adds value by explaining parameter meanings in both modes (e.g., size_usd as 'max spend on buys, target proceeds on sells' for single-market, and 'settlement notional – shares per leg' for basket), defaults, and the required relationship between market and event parameters.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields like top_of_book, vwap_fill_price, etc., and explicitly differentiates itself from siblings like polymarket_arbitrage by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal'.

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: before acting on arbitrage signals or trades above ~$500. It explains the two modes (market vs event) and when each applies, including default behavior and warnings about partial basket fills converting arb into unhedged positions.

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 adds substantial behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the reality that pre-mapped topics often yield no tradeable spread. 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 longer than ideal but well-structured: main purpose, mode details, response format, and safety fields. Every sentence adds value, though some redundancy (e.g., re-explaining compatibility_warning) could be trimmed. Front-loaded with key purpose.

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

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

Despite no output schema, the description fully explains the response structure: leg-by-leg prices, spread output (top_spreads_pp), compatibility_warning, temporal_alignment, and counters. This compensates for missing output schema, making the tool self-contained. Complexity is high and description addresses it.

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

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

Schema coverage is 100% with each parameter described. The description adds meaning beyond schema by explaining the dual-mode overrides (topic vs explicit), listing topic shortcuts, and describing how explicit parameters override topic-mapped values. The safety fields provide additional context for interpreting parameters.

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

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

The description clearly defines the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage which focus on single-venue arbitrage. 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?

Describes two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility_warning, guiding the agent when results may be unreliable. It lacks explicit 'when not to use' but the sibling list provides context; default mode and fallback are clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by confirming it returns JSON, noting the default limit of 1000, and explaining SoQL clause syntax (without leading $). This enriches the behavioral context beyond annotations.

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

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

The description is two sentences, efficiently conveying the main action, parameters, and syntax. No extraneous words, and the most critical information is front-loaded.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers the query syntax, parameter roles, default limit, and return format. It is sufficient for typical use, though it could mention pagination interaction between offset and limit.

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

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

Schema coverage is 100% with descriptions. The description adds practical examples for where, select, order, and group, and clarifies that limit defaults to 1000. 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?

Description clearly states it runs a Socrata SoQL query against a Norfolk Open Data dataset by resource_id. It specifies the action and resource, but does not explicitly differentiate from sibling tools like 'datasets' or 'search_within'.

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

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

The description implies usage for querying datasets with filtering, but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Description adds scoping detail (anonymous IP, BYO key hash, account ID) and behavior of omitting key, beyond what annotations (readOnly, idempotent, non-destructive) provide. No contradictions.

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

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

Two sentences: first sentence states core function, second adds context and pairing. Front-loaded, 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 simple tool (1 optional param, no output schema), description covers input, behavior, scoping, and relationships to siblings. Complete for an agent to use correctly.

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

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

Only one parameter 'key' with schema description 'Memory key to retrieve (omit to list all keys)'. Description adds context with examples of key usage (ticker, address), enhancing meaning beyond schema.

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

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

Description clearly states the tool retrieves a value saved via remember, or lists all keys when key is omitted. It specifies the resource (saved memories) and action, differentiating from siblings remember and forget.

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

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

Description provides explicit when to use (look up context stored earlier), with examples (ticker, address, notes), scoping info, and pairing with remember/forget. No exclusions needed.

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 valuable context: events carry source, citation_uri, and raw payload; setting mark_read:true flags events as read to exclude them in subsequent calls; polls are fine. 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?

Four sentences with clear front-loading: purpose first, then return fields, then filtering and mark_read, then polling and alternative. No wasted words; every sentence adds value.

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

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

Given no output schema, the description sufficiently describes return fields (source, citation_uri, raw payload) and filtering behavior. It addresses polling and provides an alternative access method. Missing details on persistence duration or pagination beyond limit, but overall complete for a read-only feed retrieval 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?

100% schema description coverage means baseline is 3. The description adds an example for type ('sec_8k') and explains mark_read effect, but doesn't significantly enhance understanding beyond schema descriptions. Meets minimum but doesn't excel.

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

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

The description starts with a specific verb+resource ('Pull fired events from your subscription feed') and distinguishes itself from siblings like 'query', 'recall', and 'subscribe' by targeting recent subscription feed events. It clearly enumerates return fields and filtering options.

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 notes 'Polls work fine' and provides an alternative GET URL for scripts/dashboards, giving clear context for when to use this tool. It doesn't explicitly exclude other tools but implies usage for recent alert retrieval. Could be more thorough on when not to use.

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

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

Annotations already indicate safe, idempotent, open-world behavior. The description adds context: fans out to multiple sources, GDELT→GNews fallback, USPTO soft-fail due to API sunset. 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?

A single dense paragraph that front-loads example queries. Each sentence adds value, but it is slightly verbose. Structure is logical but could be broken into bullet points for clarity.

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

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

Despite no output schema, the description explains the return structure (changes[], total_changes, URIs). It also covers source behaviors, date parsing, and fallback, making it complete for a complex tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds meaning: explains `since` accepts ISO date or relative shorthand and recommends '30d' or '1m', and `value` accepts ticker or CIK.

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 aggregates recent changes (SEC, news, patents) for a company, and distinguishes itself from entity_profile by specifying when to use each. The purpose is clear and 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?

Provides explicit when-to-use examples like 'What's new with X' and an explicit alternative: 'Use entity_profile instead when you want the static profile'. Also explains fallback behavior and date formats.

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 detail beyond annotations: key-value scoping, persistent vs. temporary storage, and pairing. 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?

Single paragraph with purpose first, then usage and behavior; every sentence is informative and non-redundant.

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?

Lacks mention of overwrite behavior or return value, but for a simple write tool with idempotent hint, this is acceptable.

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

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

Schema covers 100% of parameters with descriptions; description reinforces key-value concept but adds no new technical detail.

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?

Verb 'Save' and resource 'data' clearly stated; distinguishes from sibling tools recall and forget by pairing.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and references alternatives (recall, forget). Provides scoping and persistence 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds value by revealing internal behavior: 'Each call cascades through several lookup endpoints internally' and 'auto-disambiguated' for company input. This provides useful context beyond the annotations without contradicting them.

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

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

The description is concise and well-structured. It front-loads with example queries, clarifies the primary use case, and then details supported types. Every sentence adds value without repetition or unnecessary fluff, earning a perfect score.

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

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

Given the tool has no output schema, the description compensates by explaining return values for each type (e.g., 'returns ticker + 10-digit CIK + company_name from SEC EDGAR + citation URI'). This is fairly complete, though it could be more explicit about error handling or ambiguous inputs beyond 'auto-disambiguated'.

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 examples and context (e.g., 'accepts ticker, CIK, or company name as input — auto-disambiguated'), but the schema already provides adequate descriptions for both parameters. The description's extra detail is helpful but not essential for understanding the parameters.

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

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

The description explicitly states the tool's purpose: resolve a user-spoken name to a canonical/official identifier. It provides query examples ('What's the ticker for...') and specifies it should be used first when a name is given but an ID is needed. This clearly differentiates it from sibling tools like entity_profile.

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

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

The description gives clear usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it (e.g., if an ID is already known) or mention alternative tools for specific scenarios.

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

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

Annotations already declare readOnly, idempotent. Description adds that it probes with ai_visibility_check, ranks, and returns score, confidence, signal density. 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?

Concise, front-loaded with main purpose, then details. 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?

Covers purpose, usage, parameters, output format. Mentions underlying probe and output fields. Lacks output schema but description compensates well.

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 coverage, baseline 3. Description adds meaning: first entity is subject, context disambiguates, models array specifies default and API key requirement. Enhances schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using probes and ranking. It distinguishes itself from sibling tool ai_visibility_check by focusing on multiple entities.

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

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

Explicitly says when to use: for competitive AI-marketing audits, e.g., 'does Claude know about us as well as our competitors?'. Provides context for multi-entity comparison.

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 readOnly, idempotent, non-destructive. Description adds behavioral context beyond annotations: partial failure handling (bundlephobia can take 5-30s, sources_failed listed), composite nature, and graceful degradation. 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 dense but front-loaded with the core value proposition. Every sentence adds useful information, though it is somewhat lengthy. Could be slightly more concise but remains well-structured.

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

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

Given the tool's complexity (composite, multiple sources, partial failures, ecosystem scope), the description covers all necessary aspects: output fields, failure modes, performance caveats, and limitations. No output schema exists, so description fully compensates.

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

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

Schema description coverage is 100%, with clear descriptions for both parameters. The description does not add new meaning to parameters; it only reinforces their purpose. Baseline of 3 is appropriate as schema already handles parameter meaning.

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

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

Description starts with a specific verb phrase 'Composite should I add this npm package to my project check in ONE call', clearly stating the tool's purpose and the resource (npm package). It distinguishes from siblings by specifying ecosystem scope (NPM only, other ecosystems have separate tools).

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

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

Explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me', and when not to: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Provides clear alternatives.

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

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

Annotations are already rich, but the description adds significant behavioral details: embeddings model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and output format (passages with offsets and similarity scores). No contradictions with annotations.

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

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

The description is concise for the amount of information provided, with each sentence adding value. It could be slightly more structured (e.g., bullet points), but overall it is well-organized and front-loaded with the core purpose.

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

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

Given the tool's complexity (semantic search, 3 parameters, no output schema), the description is remarkably complete. It covers input requirements, internal processing, output characteristics, and use-case guidance, leaving no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'text' should come from a fetched record, gives example queries for 'query', and contextualizes 'limit' as max passages. This exceeds basic schema info.

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 'Semantic search INSIDE a fetched record,' with a specific verb and resource. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and implying it handles large records.

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: 'when the record is too big to cram into the prompt.' It also mentions a complementary tool (ask_pipeworx_grounded) but lacks explicit when-not-to-use instructions 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 indicate idempotent and non-destructive; description adds behavioral details such as account requirement, one-time webhook secret, auto-disable after 10 failures, and delivery caps. This goes beyond annotations but could mention idempotency explicitly.

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, starting with main action, then requirements, types, and delivery. It is informative without being verbose. Minor redundancy with schema could be trimmed, but overall 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 tool complexity (nested objects, multiple types, optional delivery), the description leaves no critical gaps: it covers account prerequisites, type-specific parameter formats, delivery channel options with constraints, and webhook behavior. Absence of output schema is mitigated by stating return value.

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

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

Schema coverage is 100% with detailed descriptions. The tool description enhances parameter meaning by providing concrete examples (e.g., items codes for sec_8k, topics for polymarket_edge) and clarifying defaults or requirements, adding 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 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, type specification, and return of subscription ID.

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

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

The description provides clear context on when to use (proactive monitoring), requirements (Pipeworx OAuth account), and constraints (delivery caps, phone verification). However, it lacks explicit comparison to alternative tools like recent_alerts or query, so usage guidelines are strong but not exhaustive.

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 rich behavioral context beyond annotations: describes return format (category-bucketed examples with tool shapes), live catalog source, and call variants (no args vs. topic). Annotations already cover idempotency and non-destructive nature, so the description adds complementary detail.

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 query patterns and is well-structured, but slightly verbose due to listing all categories. Still earns its place with useful 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 sufficiently explains return values. It also provides guidance on first use and topic focusing, making it complete for an onboarding 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%, but the description adds significant value by explaining the topic parameter's purpose with multiple example values (finance, pharma, etc.) and clarifying that omitting it returns a full spread.

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 category-bucketed example questions and serves as an onboarding entry point. It distinguishes from siblings like ask_pipeworx by focusing on suggestion generation rather than answering.

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 FIRST when you do not yet know what Pipeworx can do for you' but does not explicitly state when not to use it. The context is clear, but a direct exclusion would improve 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?

The description goes beyond annotations by clarifying the ownership enforcement, the deactivation (not deletion) behavior, and the preservation of historical events via recent_alerts. It adds value beyond the idempotentHint and destructiveHint annotations, providing full behavioral transparency.

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

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

Two concise sentences with no fluff. The action is front-loaded, and every sentence adds essential detail (ownership, deactivation, history preservation).

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

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

For a simple tool with one parameter and good annotations, the description is complete. It explains the side effect (history stays), the idempotent nature, and the non-destructive behavior, leaving 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% with a clear description for the single 'id' parameter. The description only says 'by id' which adds minimal value beyond the schema's description ('Subscription id (uuid) returned by subscribe'). Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes from siblings like subscribe and list_subscriptions by specifying the resource and behavior (deactivation, not deletion). The verb 'cancel' and resource 'subscription' 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 includes an important usage constraint ('Ownership is enforced — you can only cancel your own subscriptions') and explains the deactivation behavior, guiding when to use this tool. However, it does not explicitly state when not to use it or name alternatives beyond implied context from sibling tool names.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the returned verdict, extracted form, actual value with citation, and percent delta, as well as the supported domain and sources.

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

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

The description is slightly long but each sentence adds value: trigger phrases, usage guidance, and technical details. It is front-loaded with examples for clarity.

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

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

Given the tool has only one parameter and no output schema, the description provides sufficient context including supported claim types, output structure, and efficiency improvement over multiple calls.

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 provides additional context by giving examples of natural-language claims, but does not add significantly to the schema's parameter 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: natural-language claim verification against authoritative sources. It provides concrete trigger phrases and distinguishes itself from siblings by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims) and sources, giving clear context for when to use.

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