Data Boston

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

Annotations already indicate safe operation (read-only, idempotent). The description adds transparency about cost implications (free default model, BYO key for Anthropic) and the multi-model probing behavior, which is valuable beyond annotations.

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

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

The description is two sentences plus a short return structure note, which is concise. It front-loads the core purpose and usage conditions, though the return details are somewhat buried.

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

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

With no output schema, the description adequately explains the return format (per-model and combined view). It covers all parameters and provides enough context for effective use, though it could include example entities or outputs for completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the default model (Workers AI Llama-3.3-70b free), the purpose of _apiKey (type and billing), and how context disambiguates entities, enriching the schema's minimal descriptions.

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

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

The description clearly states the tool's action ('Probe one or more LLMs') and resource ('business / brand / product / topic'), with a specific output (score 0-100). It distinguishes itself from siblings by focusing on AI visibility scoring, unlike scan_competitor_ai_presence which is more specialized.

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

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

The description lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use this tool compared to alternative sibling tools like scan_competitor_ai_presence.

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=false, so the description adds context like routing to 4,552 tools, returning structured answers with pipeworx:// citation URIs, and being the default entry point. No contradictions.

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

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

The description is long but front-loaded with the key instruction. It efficiently covers purpose, scope, examples, and sibling differentiation. While every sentence adds value, slight trimming could improve conciseness.

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

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

Given the tool's complexity, the description covers purpose, usage, parameter guidance, output format (structured answer with citation URIs), and contextual notes (works on every tier, one fast call). No output schema exists, but the description explains return value sufficiently.

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 6 aliases, but they are minimal ('Alias for question.'). The description compensates by providing natural language guidance, examples, and accepted formats, adding significant meaning beyond the schema.

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

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

The description clearly states the tool routes questions to a large set of tools (4,552) and returns structured answers with citations. It explicitly distinguishes from siblings by specifying when to use ask_pipeworx versus ask_pipeworx_grounded and deep_research, and provides extensive examples of use cases.

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

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

Explicitly instructs to prefer over web search, gives patterns for when to use (e.g., 'what is', 'look up'), and provides clear step-up guidance for siblings. Examples illustrate appropriate usage.

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, non-destructive. Description adds extra cost (one extra LLM call), refusal reasons, and return structure. No contradictions, and description provides meaningful context beyond annotations.

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

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

Description is front-loaded with purpose and usage, then details. Slightly long but each sentence adds value. Could be tightened but remains clear and 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 complexity (orchestrating 4,552 tools across 1,160 sources, refusal modes), the description is thorough. No output schema, but return structure is described in detail, making it complete for high-stakes 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% with clear descriptions of aliases. Description mentions 'same routing as ask_pipeworx' and 'fills arguments' but does not add significant meaning beyond schema. 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?

Description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers using only tool results, distinct from ask_pipeworx. This differentiates it from sibling 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 says when to use: 'whenever an answer will be quoted, cited, or acted on' and gives examples like financial verdicts. Also advises to prefer ask_pipeworx for casual lookups, covering 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?

The description adds significant behavioral context beyond annotations: it details resolution, classification, fan-out, safety mechanisms (low-confidence short-circuit, closed markets skip, wide spread note), and resolution-rule risk. Annotations (readOnlyHint, etc.) are not contradicted.

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 (4 paragraphs) and covers extensive detail. While every sentence is informative, it lacks conciseness and could be structured more clearly. For a complex tool, this is acceptable but not optimal.

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, no output schema, and 3 parameters, the description thoroughly covers response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. It is fully complete for an agent to use effectively.

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

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

Schema coverage is 100%, and the description adds value for all three parameters: explains market input types (slug, URL, question), depth options (quick vs thorough), and include_raw (default false, with reasoning for full payloads). This enhances schema information.

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 researches Polymarket bets by pulling Pipeworx data, with specific use cases ('should I bet on X'). It distinguishes from siblings like 'polymarket_edges' and 'polymarket_arbitrage' by focusing on research rather than edge detection or arbitrage.

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

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

The description explicitly says when to use the tool (e.g., 'should I bet on X') and provides extensive detail on its operation. However, it does not explicitly mention when not to use it or suggest alternatives like sibling tools, leaving some ambiguity for agents.

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 the return format (title and resource ids) and the source platform, which provides useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with the action and resource. No unnecessary 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?

With no output schema, the description explains the return values (title and resource ids) and how to use them (with boston_query). The parameters are simple and well-described. The tool's purpose and usage are fully covered.

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 both parameters described. The description adds value by explaining the purpose of the query parameter ('keyword') and implying the limit parameter's role, but the schema already covers this adequately.

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 tool searches the City of Boston open-data catalogue (data.boston.gov, CKAN) by keyword, which is a specific verb and resource. It distinguishes itself from siblings by mentioning the specific platform and hinting at the use of boston_query for further data access.

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

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

Provides clear context for use: searching by keyword. Implicitly suggests when to use boston_query for querying data. Does not explicitly mention when not to use it or alternative tools like boston_recent, but the sibling list is provided for context.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds that it supports free-text search, exact-match filters, sort, limit, and offset, and notes default limit (100) and max (1000). This goes beyond annotations without contradiction.

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

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

The description is two sentences. The first sentence states purpose and core capabilities. The second sentence provides essential usage guidance. No fluff. Information is front-loaded and every sentence serves a 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 simplicity (querying a CKAN datastore), the rich annotations, and full parameter schema, the description is sufficient. It covers usage, supported operations, and links to related tools. Missing details like pagination behavior or error handling, but adequate for this complexity.

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

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

Schema coverage is 100% (all parameters described). The description lists the key parameters (q, filters, sort, limit, offset) but adds value by stating the default limit and maximum, and clarifying that filters are field→value pairs. This provides marginal extra meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Query any City of Boston datastore resource by its resource id'. It specifies the verb (query) and resource type (CKAN datastore). It also distinguishes from siblings by mentioning boston_datasets and boston_recent as ways to find resource IDs.

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 and directs to alternatives: 'Use boston_datasets to find a resource id, or boston_recent for the common ones.' This provides clear context. It doesn't explicitly say when not to use, but the guidance is strong.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds that results are newest-first and mentions the free-text filter. No contradictions; adds useful behavioral context beyond annotations.

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

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

Four sentences with no redundancy. Front-loaded with main purpose, then usage guidance, then parameter hints. Every sentence contributes essential 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?

Tool is simple with 3 parameters fully documented. Description covers purpose, usage, and return ordering. No output schema, but behavior is straightforward. Could mention data freshness or limitations, but adequate for an open dataset reader.

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

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

Schema coverage is 100% with descriptions for all parameters. Description reinforces 'q' usage and provides examples for dataset enum. Adds value by suggesting alternative tool for control, but schema already documents each parameter well.

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 returns recent records from a specific open dataset using friendly names, avoiding CKAN IDs. It effectively distinguishes itself from siblings like boston_query and web search by specifying the scope and convenience.

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

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

Explicitly instructs to prefer over web search for specific queries ('recent crime in Boston', etc.) and directs to boston_query for full control. Provides clear when-to-use and alternative.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details that it pulls latest 10-K data with correct handling of off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. 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 front-loaded with common query patterns and packs many details, but is slightly verbose. However, every sentence contributes value, so it is still well-structured.

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

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

Given the tool has no output schema, the description thoroughly explains the returned data (financial metrics for companies, adverse-event counts for drugs), sorting, and citation URIs, making it complete for an agent's decision-making.

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

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

With 100% schema coverage, the description adds significant meaning: for 'type' it explains data sources (SEC EDGAR vs. FAERS) and behavior; for 'values' it provides specific examples (tickers/CIKs for companies, drug names) and constraints. This surpasses schema alone.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, with specific data sources and a strong usage directive to prefer over sequential lookups. It distinguishes from siblings by emphasizing efficiency and parallel execution.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries like 'which is bigger' or 'rank these companies', making the intended context and alternatives clear.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds critical behavioral context: account/plan requirements, 15-60s expected time, parallel execution, returns evidence with confidence/source/citations and explicit gaps array. No contradiction with annotations.

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

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

The description is long but efficient, front-loading critical usage warnings (account required, free tier capabilities). Every sentence adds value—no redundancy. Slightly verbose but earned.

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

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

Given complexity and no output schema, the description fully explains what the tool returns (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]) and expected timing. Covers auth, plan limits, and limitations relative to siblings.

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

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

Schema covers both parameters with full descriptions. The description adds practical context about depth enumeration values and paid plan requirement for 'thorough', but does not substantially expand beyond schema meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: grounded multi-source research across 1160 structured data sources with parallel decomposition. It uses specific verbs like 'decomposes' and 'routes' and distinguishes itself from sibling tools like ask_pipeworx by being for broad/multi-part questions over structured data.

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

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

Explicitly provides when-to-use (broad/multi-part structured data questions) and when-not-to-use (not signed in, single lookup, breaking/current news), with specific alternatives: ask_pipeworx for those cases. Also mentions account requirement and paid plan for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by explaining what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' No contradictions.

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

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

The description is three sentences, front-loaded with the purpose. The second sentence is somewhat lengthy due to the list of examples, but it is still efficient and informative. 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 the tool's role as a discovery tool with 6 parameters (1 required) and no output schema, the description is thorough. It explains what the tool does, when to use it, what it returns (top-N tools with schemas), and the nature of the query input. It is complete enough for an agent to understand how 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 coverage is 100%, so the schema already documents all parameters. The description adds that 'query' accepts natural language and mentions aliases, but this is largely redundant with the schema's description. No additional semantic 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 states a specific verb+resource: 'Find tools by describing the data or task.' It lists numerous use cases (SEC filings, financials, etc.) and distinguishes itself from sibling tools by explicitly saying 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description clearly states when to use: 'when you need to browse, search, look up, or discover what tools exist.' It also advises to call this tool first when exploring options. While it doesn't name specific alternatives, it provides clear context that this is for discovery, not for executing specific tasks.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent. Description adds transparency about USPTO PatentsView API sunset ('soft-fails until reactivated') and details parallel fan-out across sources. No contradiction.

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

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

The description is front-loaded with purpose and example prompts. It is detailed but every sentence adds value. Could be slightly more concise, but structure is clear and well-organized.

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

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

No output schema, but the description explains return values: cik, company_name, recent_filings (with URIs), fundamentals, patents (with caveat), news, LEI. Covers complexity thoroughly.

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

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

Schema coverage is 100% with descriptions. The description adds context: type only supports 'company', value can be ticker or CIK, and names are not supported. This goes beyond the schema alone.

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

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

The description clearly states the tool provides a '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 return fields, distinguishing it from siblings like resolve_entity (needed for names) and search tools.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies input requirements: 'Pass ticker or CIK — names not supported (use resolve_entity first if you only have a name).'

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

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

Description discloses destructive action ('Delete') consistent with annotations (destructiveHint=true). Adds context about clearing sensitive data, but annotations already convey mutation.

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 front-loaded action verb. No redundant information; each 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 simple single-param tool with no output schema, description fully covers purpose, usage context, and pairing with related tools.

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

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

Schema description coverage is 100% and description merely restates 'by key'. No additional parameter 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 explicitly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from siblings by pairing with remember and recall, clarifying its unique role.

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 conditions: context stale, task done, clear sensitive data. Implicitly contrasts with remember and recall, but doesn't explicitly state 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details (fetches page, extracts title/description/key links, emits standard markdown) beyond what annotations offer. No contradictions.

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

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

The description is a single, well-structured paragraph that efficiently conveys purpose, behavior, output, and use cases without unnecessary words or repetition.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers the output format and use cases adequately. It could mention error handling but is complete enough for an agent to understand its function.

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 well-described in the schema. The description does not add new information about the parameters (e.g., defaults are already in the schema). Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the verb (generate), resource (llms.txt file), and output format. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation for AI crawlers.

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

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

The description includes explicit use cases ('Useful for:') and implies when to use the tool. While it doesn't explicitly state when not to use or name alternatives, the context is clear enough for an agent to differentiate from siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field names and parameter existence, which is modest extra value.

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

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

Two concise, front-loaded sentences with zero waste. Purpose and usage are immediately clear.

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 param, no output schema, and full annotations. Description covers purpose, return fields, usage, and enough context for selection.

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 already describes include_inactive parameter. Description does not enhance parameter understanding beyond schema.

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

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

Description clearly states the verb (list) and resource (subscriptions), specifying returned fields. Distinct from siblings subscribe/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?

Provides explicit guidance: use before adding subscriptions or to find an id for cancellation. Lacks explicit when-not-to-use but context is clear.

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

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

The description discloses rate limits (5 per identifier per day), cost (free, no quota usage), and impact (team reads daily, affects roadmap). This adds value beyond the empty annotations, providing a complete behavioral picture.

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

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

The description is a single, well-structured paragraph. It leads with purpose, then usage, then behavioral details. Every sentence adds value with no repetition or filler.

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

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

Given no output schema, the description adequately explains the outcome (team reads it, roadmap impact) and constraints (rate limit, free). The tool is simple and the description covers all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds nuanced guidance: it explains the enum values for 'type' in more detail, gives context on message length (1-2 sentences, 2000 chars max), and advises against pasting end-user prompts. This exceeds baseline.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories and distinguishes from sibling tools (which are query/research tools) by being a feedback mechanism.

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

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

The description explicitly states when to use this tool (bug, feature/data_gap, praise) and provides a negative guideline ('don't paste the end-user's prompt'). It does not name sibling alternatives but the context makes it clear this is for feedback, not for inquiries.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('5min-1h'). 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?

Concise, well-structured, front-loaded with purpose. Every sentence adds value. No wasted words; efficient use of formatting (bullet-like enumeration).

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

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

Despite no output schema, description fully explains return values (top tools, top packs, call volume), source, caching, and use cases. Complete for a simple analytics 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 enum description. Description adds semantic context about window behavior ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing agent understanding beyond schema.

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

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

Description clearly states verb ('Returns') and resource ('top tools, top packs, total call volume') with specific scope ('over a recent window'). Distinguishes from siblings by describing a unique aggregate analytics function not covered by other 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?

Three explicit use cases listed ('discovering...', 'confirming...', 'seeing...'), providing clear context for when to use. Lacks explicit when-not-to-use or alternative tool names, but the use cases are sufficient for an agent to decide.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds substantial behavioral context: explains Jaccard similarity threshold (0.30), partition filter (placeholder fraction >20% returns null), fill check (theoretical vs realizable edge), and edge cases like skipped_low_similarity. 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 verbose, containing multiple paragraphs with technical details. While the information is valuable, conciseness suffers. It is front-loaded with the main purpose but could be trimmed. For a complex tool, the verbosity is somewhat justified, but there is room for improvement in brevity.

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

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

Given no output schema, the description thoroughly describes the response structure: opportunities array with fields (gap_pp, suggested_trade, reasoning, etc.), partition_check details, and fill check outputs. It also covers edge cases like skipped_low_similarity, placeholders filtered, and trade feasibility checks. This ensures an AI agent understands the complete behavior and return values.

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

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

Input schema has 2 parameters with descriptions, achieving 100% coverage. Description adds significant value beyond schema: explains each mode's behavior, provides example values, and clarifies the difference between event and topic modes. It gives context on what the parameters control, which is helpful for an AI agent.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) each with specific resources and operations. The verb 'find arbitrage opportunities' combined with 'monotonicity violations + partition-sum checks' provides a specific and unique purpose that differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit usage guidance is provided for each mode: no args for trending scan, event for a specific market (recommended with example slugs), topic for cross-event scanning (with seed question examples). It explains why cross-event mode catches patterns single-event misses. It also mentions using fill_check and polymarket_fill_risk for trade execution, effectively guiding when to use 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=true, idempotentHint=true, and destructiveHint=false. The description significantly adds behavioral detail: model formulas (lognormal barrier, GDELT ratio, partition overround with corrections), output fields (edge_pp_net, kelly_fraction, etc.), 24h-move warning logic, tradeable-edge knobs and their effects, and caching at KV level for 1 hour. No contradictions found.

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

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

The description is very long (~500 words) and densely packed with model details, which hurts conciseness. However, it is well-structured: starts with purpose, then segments, then output fields, then knobs, then response structure. Front-loading is decent. Length is justified by complexity, but could be more concise.

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

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

Given 9 parameters, no output schema, and high domain complexity, the description is extremely thorough. It explains the three opportunity segments, the output fields, the diagnostics section, caching behavior, and tradeable-edge knobs. An agent has all necessary context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly interact with edge filtering and Kelly sizing, and provides usage advice (e.g., 'Bump for very thin partitions'). This goes beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and verb (scan and return), and distinguishes from generic market browsing by focusing on model-driven opportunities. The purpose is very specific and actionable.

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 frames the tool as 'built for what should I bet on today' and mentions saving agents from paging hundreds of markets, implying a discovery use case. However, it does not explicitly state when to use this tool versus sibling tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it provide exclusion criteria. Guidance is implied but not explicit.

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 true, and destructiveHint false. The description adds detailed behavioral traits: data sources, response structure (tracked[], expired[], snapshot_dates[]), and explains that gaps mean no scan that day. No contradiction with annotations.

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

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

The description is moderately long but well-structured: a main sentence, a clarifying parenthetical, then a detailed breakdown of the response. It is front-loaded with the core purpose. While every sentence adds value, it could be slightly more concise.

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

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

Despite no output schema, the description fully explains the response structure and key fields. Parameters are fully covered. Context about data limitations (TTL, snapshotting) is provided. For a tool with 2 optional parameters and no output schema, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions for days and window. The description adds context: default values, clamping for days, and clarifies window as snapshot family. This adds meaning beyond the schema, earning a score above baseline 3.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis and opportunity lifecycle, answering 'how long has this edge existed and is it shrinking?'

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

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

The description implies when to use by highlighting the difference between a fresh wide edge and a 3-week-old wide edge, suggesting the tool is for assessing edge longevity. It also mentions limits like 60-day snapshot TTL, but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which are consistent with a safe read operation. The description adds behavioral context: checks order book depth, returns verdict and slippage, and warns of forced directional risk in basket mode. No contradiction.

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

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

The description is dense but well-structured with bold headings for modes and bullet points for return values. It front-loads the purpose and is informative, though slightly lengthy. Every sentence adds value, earning a score of 4.

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

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

Given the tool's complexity (two modes, multiple return fields) and no output schema, the description comprehensively lists return values for both modes, explains risks, and covers edge cases. It is complete enough for an agent to understand inputs, outputs, 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?

Schema description coverage is 100% (baseline 3), but the description adds significant meaning: explains the two modes, default values, interpretation of size_usd for buys vs sells, and basket-specific behavior. It provides context beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists specific return fields, making it distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround not capturable, partial fills create unhedged directional risk), helping the agent decide when to call this tool.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details response fields, compatibility warnings, temporal alignment, and skipped counters, giving comprehensive behavioral insight.

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 structured logically (purpose, modes, response, safety, warnings) but is verbose; every sentence adds value, yet could be more concise.

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

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

Given the tool's complexity and no output schema, the description covers return values, safety fields, temporal alignment, and caveats, making it fully informative.

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

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

Although schema coverage is 100%, the description adds meaning by explaining the two modes and the override behavior of explicit parameters over topic-mapped ones.

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

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

The description clearly states the tool computes spreads between Kalshi and Polymarket for similar questions, distinguishing it from sibling tools like polymarket_arbitrage which focus solely on Polymarket.

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

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

The description explains two usage modes (topic shortcuts vs explicit identifiers) and warns that pre-mapped topics often yield non-tradeable results, providing clear context but not explicitly excluding 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 provide readOnly/ idempotent hints. Description adds key behaviors: omitting key lists all, scoping to identifier, and pairing with siblings. No contradictions. Adds useful context beyond annotations.

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

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

Three focused sentences: first states core action, second explains when to use and scope, third references sibling tools. No wasted words. Front-loaded with essential 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?

Without an output schema, the description clarifies that retrieving a key returns a value and omitting returns key list. Could specify return type, but overall sufficient for correct tool invocation. Pairing with remember/forget provides full context.

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

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

Schema covers the single parameter fully with description. Description goes further by explaining the dual behavior of omission (list all keys) and providing usage examples, adding significant 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?

Specifically states it retrieves a value saved via remember or lists all keys. Provides concrete examples (ticker, address, research notes) and distinguishes from remember/forget by naming them. Clear verb+resource+scope.

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 (look up context stored earlier without re-deriving) and how (omit key to list all). Mentions pairing with remember/forget. Lacks explicit exclusions but gives clear context.

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

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

Annotations already mark safe and idempotent; description adds details on return fields, polling suitability, and side effect of mark_read. 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?

Three well-structured sentences with front-loaded purpose. Each sentence adds information without redundancy. No wasted words.

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

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

Given no output schema, description adequately describes return fields (source, citation_uri, raw payload). Covers parameters, usage patterns, and alternative access. Complete for a read-only polling 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 all 5 parameters; description adds practical context: type example, since format, mark_read behavior, unread_only clarification, and default limit. 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?

Starts with clear verb 'Pull fired events' plus resource 'subscription feed'. Explicitly distinguishes from siblings by focusing on reading alerts vs subscribing or other actions.

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

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

Provides filtering guidance (type, since) and side effect of mark_read. Mentions alternative access via direct GET endpoint. Lacks explicit when-not or comparison to sibling tools, but sufficient for common 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond these, including the multi-source fan-out, fallback logic, USPTO soft-fail, and return structure (changes[] grouped by source, total_changes, citation URIs). There is no contradiction with annotations.

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

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

The description is a single paragraph that efficiently conveys use cases, behavior, parameter details, and alternative tools. It is front-loaded with example queries and every sentence adds value. Despite the density of information, it remains readable and well-structured.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, parameter options), the description covers all necessary aspects: the window parameter format, entity input format, the list of sources with their behaviors, and the return structure. It also provides a clear alternative (entity_profile). No output schema exists, but the description outlines the return structure sufficiently.

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 substantial meaning: it explains the 'since' parameter with both ISO date and relative shorthand examples, recommends '30d' or '1m' for monitoring, and clarifies that 'value' can be a ticker or zero-padded CIK. This goes well beyond the parameter descriptions in the schema.

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

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

The description clearly states that the tool provides a change feed for a company over a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It includes explicit example queries ('What's new with X', 'latest on Y') and distinguishes itself from the sibling tool 'entity_profile', which provides static profiles.

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

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

The description provides explicit usage scenarios and alternatives: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains fallback behavior (GDELT→GNews, USPTO soft-fail). This gives clear guidance on when 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?

Adds context beyond annotations: memory scoped by identifier, persistence details (24 hours for anonymous, persistent for authenticated), and key-value storage. Annotations already provide idempotent and non-destructive hints, so the description enriches understanding. Could mention overwrite behavior 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?

Four concise sentences, front-loaded with the core purpose. Every sentence adds necessary detail without redundancy. No wasted words.

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

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

Given the tool's simplicity (two required string parameters, no output schema), the description fully covers purpose, usage, storage behavior, persistence, and pairing with related tools. It is complete and actionable.

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

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

Schema coverage is 100% with useful examples for key and value. Description adds scoping context and emphasizes the value can be any text (findings, addresses, etc.), supplementing the schema. The combination effectively clarifies parameter usage.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, with specific examples like tickers, addresses, and preferences. It distinguishes itself from sibling tools recall and forget by explicitly pairing with them.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) and when not to use (implicitly by pairing with recall/forget). It gives concrete scenarios and alternatives, making it easy for an agent to decide.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that each call cascades through multiple internal endpoints and auto-disambiguates companies, providing behavioral context beyond the annotations.

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

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

The description is concise yet comprehensive, front-loading the core purpose with concrete example queries. It efficiently covers both supported types and their specifics without extraneous information.

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

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

Given the absence of an output schema, the description sufficiently explains return values for both entity types, including citation URIs. It provides enough detail for an agent to understand what the tool outputs and how to use the results with other tools.

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 covers 100% of parameters, so baseline is 3. The description enhances understanding by detailing what each type returns (e.g., ticker + CIK for company, RxCUI for drug) and acceptable input formats, adding meaningful context beyond the schema.

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

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

The description clearly identifies the tool's purpose: resolving a name to a canonical identifier. It provides specific examples like ticker, CIK, RxCUI, and distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an 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?

Explicitly recommends using this tool first when a name is given but an ID is needed. It lists supported entity types and their handling. However, it does not explicitly state when not to use this tool or mention alternatives beyond the implicit instruction to use it first.

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, idempotentHint, etc. Description adds valuable context: it internally probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Three sentences, front-loaded with primary purpose. Every sentence provides unique value: purpose, method, use case, output. No redundancy or fluff.

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

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

No output schema, but description explains return: ranked list with score, confidence, signal density per entity. Covers all parameters with purpose and constraints. Could mention pagination or limits, but 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 coverage is 100%, baseline 3. Description enriches all parameters: entities' first entry is subject, rest competitors; models defaults to workers-ai; context disambiguates; _apiKey needed only if anthropic model used. Adds meaning beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and highlighting most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 'Useful for competitive AI-marketing audits' with an example question. Implicitly guides when not to use by contrasting with sibling ai_visibility_check. Could explicitly state 'Use ai_visibility_check for a single entity', but the context is strong.

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

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

Annotations indicate safe, non-destructive, idempotent. Description adds critical context: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully (sources_failed listed).

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 packed with information, front-loaded with core purpose. Slightly dense; could benefit from structure but remains concise and readable.

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

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

Covers all important context: ecosystem scope, partial failure behavior, return structure, and version handling. No output schema, but description provides comprehensive field list and edge cases.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds nuance: scoped packages accepted for 'package', default version is latest. Since no output schema, description compensates by detailing return fields.

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's a composite check for npm package evaluation covering license, advisories, version history, and bundlephobia data. It is distinct from all sibling tools, which are unrelated.

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

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

Explicitly specifies when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also clarifies NPM-only in v1 and notes fallback for other ecosystems.

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 technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage guidelines, then technical details. It is appropriately sized for the tool's complexity, though slightly longer than minimal. Every sentence adds value.

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

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

Given no output schema, the description adequately describes return values (top-N passages with offsets and similarity scores), constraints (200K char limit), and pairing with other tools. Rich annotations cover safety.

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 semantic context by providing real-world examples for the 'query' parameter and clarifying 'text' input expectations, justifying a score of 4.

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

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

The description clearly states 'semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from sibling tools like ask_pipeworx_grounded by noting that search_within is for searching inside a retrieved document.

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

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

The description explicitly says when to use ('when the record is too big to cram into the prompt') and provides alternatives ('Pairs with ask_pipeworx_grounded'), giving clear context and exclusions.

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

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

Annotations (idempotentHint=true) are complemented by details: requires OAuth, types with parameters, delivery constraints (phone verification, 10/day SMS cap, webhook signing, auto-disable after failures), and return of subscription id.

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-organized, but slightly long. It front-loads purpose and return, then details requirements and options. Every sentence adds value, but could be tightened.

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, it fully explains return (subscription id). It covers all aspects: account requirement, all subscription types with parameters, all delivery channels with constraints, and mentions auto-disable for webhooks.

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 context: provides specific examples for each type (e.g., sec_8k items codes, polymarket_edge topic), and for delivery explains webhook HMAC signing and auto-disable behavior.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinguishes it from sibling tools like list_subscriptions, recent_alerts, 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?

It explains account requirements (Pipeworx OAuth), supported types with examples, and delivery options. However, it does not explicitly mention when not to use or compare to alternatives like list_subscriptions or unsubscribe, though it references recent_alerts for the feed.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: returns category-bucketed examples, can be called with no arguments or with topic, and teaches meta-tool usage. 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 somewhat lengthy but front-loaded with common queries. Each sentence adds value, covering purpose, usage, and return type. It is appropriately sized 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?

The description fully covers purpose, usage, parameter semantics, and return type. It explains the absence of output schema and provides comprehensive guidance. 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% with description for the optional 'topic' parameter. The description adds additional context by listing possible values and explaining the behavior when omitted. This goes beyond the schema.

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

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

The description clearly states that the tool returns category-bucketed example questions with exact tool and argument shapes, and it distinguishes itself from siblings by being the onboarding entry point.

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

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

The description explicitly says to use this FIRST when you do not yet know what Pipeworx can do, or to learn how to call meta-tools. It provides clear context for when to use and implies alternatives.

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

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

The description clarifies that the row is deactivated (not deleted) and historical events remain available, adding context beyond the annotations (readOnlyHint, destructiveHint, idempotentHint). 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 concise sentences with no wasted words, directly conveying the essential 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?

For a simple one-parameter tool with no output schema, the description covers ownership, effect, and historical availability completely.

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 the parameter 'id' well-described. The description adds minimal extra value beyond reinforcing that the id comes from 'subscribe', meeting the baseline for full schema coverage.

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

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

The description clearly states the action 'cancel a subscription by id', specifying the verb and resource distinctly from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a usage constraint, but does not explicitly state when to use this tool over 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=false. The description adds significant behavioral context: it returns a verdict, structured form, actual value with citation, percent delta, and uses SEC EDGAR + XBRL as data sources. 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: it opens with trigger phrases, states usage, specifies scope, and lists return values. It is slightly lengthy but every sentence adds value, and the structure aids readability.

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 (natural-language claim verification with structured output and no output schema), the description covers purpose, usage, supported claims, return values, and even mentions efficiency gains. It is complete and leaves 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?

The input schema has 100% description coverage for the single parameter 'claim'. The description adds value by providing examples and clarifying the supported claim types (company-financial), which helps the agent craft appropriate inputs.

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

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

The description clearly defines the tool's purpose: verifying natural-language claims against authoritative sources. It provides specific trigger phrases ('Is it true that...', 'fact check') and explicitly states it replaces 4-6 sequential calls, distinguishing it from sibling tools.

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

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

The description explicitly states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported domain (company-financial claims for US public companies). While it does not explicitly state when not to use it, the context is clear enough.

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