Data Cambridge

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing that the tool probes multiple LLMs, requires an API key for Anthropic, and returns per-model data. It also mentions cost implications for Anthropic. However, it does not disclose potential rate limits or timeout behavior.

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 with no wasted words. It front-loads the main action and output, then provides model details, and ends with use cases. Each sentence serves a clear purpose and contributes to understanding.

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

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

Given the tool has 4 parameters (1 required) and no output schema, the description sufficiently covers behavior, return structure (per-model {score, confidence, signals, raw_response} + combined view), and use cases. It is complete for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, with each parameter already having a clear description. The description reinforces parameter usage (e.g., default model, API key purpose) and adds context about when to use the 'context' parameter for disambiguation. This goes slightly 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 probes LLMs about an entity and returns visibility scores (0-100) per model. It uses specific verbs ('probe') and resources ('LLMs'), and specifies the output structure. The tool's purpose is unambiguously defined and distinguishable from siblings like 'scan_competitor_ai_presence' by its focus on individual LLM scoring.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the default free model and when to bring your own Anthropic key. However, it does not explicitly mention when not to use this tool or contrast it with alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context: the tool routes to over 4,900 tools across 1,293 sources, fills arguments automatically, and returns structured answers with stable citation URIs.

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

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

The description is fairly long but front-loaded with the most important guidance, uses bullet-like phrasing, and every sentence adds value. A slight reduction for length, but still well-structured.

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

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

Despite no output schema, the description describes the return format (structured answer with citation URIs). Given the tool's complexity and broad scope, this is sufficient for an agent to understand what to expect.

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 six parameters all aliased to 'question'. The description explains that the parameter accepts natural language questions, and explicitly lists the supported aliases (query, q, prompt, text, input), which is helpful 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: handling questions about current/historical data from authoritative sources. It provides specific examples and contrasts with sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises preferring this tool over web search and gives detailed guidance on when to step up to alternatives like ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part questions.

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 safety traits, but description adds critical behavioral details: costs extra LLM call, returns explicit refusal reasons, extracts only from tool result. Lists possible refusal reasons, adding significant value beyond annotations.

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

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

The description is front-loaded with purpose and use cases. Every sentence is informative, though slightly verbose. Could be tightened but overall efficient and well-structured.

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

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

No output schema exists, so description fully explains return values: answer, evidence, confidence, source, fetched_at, refusal_reason and lists all refusal reasons. Also covers cost trade-off, making it complete for a grounded QA tool.

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

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

Schema coverage is 100% and all parameters are aliases for 'question'. The description does not add meaning beyond the schema; it only mentions that aliases are accepted. Baseline of 3 is appropriate as parameters are well-documented in 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's a 'hallucination-resistant answer mode for high-stakes reads', specifies the verb 'answers', and distinguishes from ask_pipeworx by mentioning same routing but extraction from tool results.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups'. Provides clear alternatives and 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing response shapes, resolver contract, parent event extraction, news fallback handling, safety logic for low-confidence matches and closed markets, wide-spread market handling, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and dense, lacking clear structure. Important details are mixed together in paragraphs, which could overwhelm the agent. While front-loaded with the main purpose, it could benefit from bullet points or sections for 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?

Despite the complexity (3 params, no output schema), the description thoroughly covers expected outputs, edge cases, safety behavior, and resolution rules. It provides enough detail for the agent to understand usage and handle various scenarios.

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

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

Schema description coverage is 100%, so the description adds minimal extra parameter meaning. It provides examples of market input formats and explains depth and include_raw, but these are already covered in the 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?

The description clearly states the tool researches a Polymarket bet by aggregating Pipeworx data. It specifies the resource (Polymarket bet), the verb (research), and the scope (data from multiple sources). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a single bet and providing comprehensive evidence.

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 gives use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides classifiers and fan-out examples. However, it does not explicitly state when not to use this tool or point to alternatives among siblings.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by detailing the output (dataset names, descriptions, and resource ids) and the specific data source, which goes 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 a single sentence that is concise and front-loaded with the key action and purpose. No unnecessary words 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?

Given no output schema, the description adequately explains what the tool returns. Parameter descriptions cover all inputs. The combination of description, schema, and annotations provides a complete picture for a search tool.

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

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

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

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

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

The description clearly states the tool searches the Cambridge open-data catalogue by keyword and returns specific fields (dataset names, descriptions, Socrata resource ids). It distinguishes from sibling tools like cambridge_query and cambridge_recent by specifying the output and purpose.

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

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

The description indicates when to use the tool (keyword search) and what it returns. While it doesn't explicitly mention when not to use or alternatives, the context from sibling tools makes it clear that this is a discovery step before using cambridge_query.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about API key for rate limits, default max rows, and that it's a raw query, which 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?

Two sentences, front-loaded with purpose, then details. Every sentence adds value, no wasted words.

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

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

Given the complexity of a SoQL query tool with 8 parameters and no output schema, the description covers resource_id format, all SoQL clauses, API key option, and limits. References sibling tools for discovery, making it complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving examples of resource_id format and SoQL clause syntax, which helps the agent understand parameter usage 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 runs a raw SoQL query against Cambridge open-data resources by Socrata id, with examples. It distinguishes from siblings by referencing cambridge_datasets and cambridge_recent for finding 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?

Explicitly directs users to cambridge_datasets or cambridge_recent to find resource IDs, and lists full SoQL clauses available. However, does not explicitly state when not to use this tool vs 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 read-only, idempotent, non-destructive behavior. The description adds that it returns latest rows newest-first, which is not covered by annotations. It also mentions SoQL filtering capability and default limit, providing useful behavioral context beyond structured fields.

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

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

The description is concise with two sentences plus a brief usage note. It front-loads the core purpose and immediately provides actionable usage guidance. Every sentence contributes, no wasted words.

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

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

For a simple retrieval tool with no output schema, the description adequately explains return behavior (latest rows, newest-first) and filtering options (SoQL where). It mentions limit but not pagination details, which is acceptable given the limit parameter range (1-1000). The sibling distinction compensates for any missing context.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the 'friendly name' concept for dataset, clarifying that where is an optional SoQL filter, and noting the default limit of 20. This goes beyond the schema's baseline 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 states the tool retrieves recent records from Cambridge open datasets by friendly name, avoiding Socrata IDs. It names specific datasets (311, crime, permits) and distinguishes from sibling cambridge_query, which handles more complex queries. The verb 'Get' is implied by 'Returns the latest rows', making purpose clear.

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

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

Explicitly advises preferring this tool over web search for specific queries ('recent crime', '311 requests', 'building permits') and directs to cambridge_query for anything else, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific financial metrics, correct handling of off-calendar fiscal years, sorting by primary metric, and returning citation URIs. No contradiction.

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

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

The description is front-loaded with example queries and the core action. Every sentence adds value, but it is relatively long. Still, it is well-structured and avoids redundancy. A slightly more concise version could be equally informative.

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

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

Despite no output schema, the description explains return format: 'Results sorted by primary metric' and 'Returns paired data + pipeworx:// citation URIs per entity.' It covers both entity types, data sources, sorting behavior, and the benefit (replaces 8–15 lookups). For a tool with only 2 parameters, this is comprehensive.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds significant meaning beyond the schema: for type='company' it lists exact financial metrics (revenue, net income, cash, long-term debt) and for type='drug' it lists adverse-event counts, FDA approvals, and trial counts. It also clarifies the range (2–5) and gives examples.

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 comparison of 2–5 companies or drugs in one parallel call, with example queries like 'X vs Y' and 'which is bigger'. It distinguishes from siblings by explicitly preferring this tool over sequential single-pack lookups, and noting it replaces 8–15 sequential lookups.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete examples of when to use (comparison queries) and implies alternatives (entity_profile for single entities). However, it does not explicitly list when not to use the 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?

Description adds substantial behavioral context beyond annotations: details internal process (decomposes question into facets, routes to 4,928 tools in parallel), output format (findings packet with verbatim evidence, confidence, gaps, contradictions), time expectations (15-60s, up to 90s for thorough), and handling of large records. All consistent with readOnlyHint and other annotations.

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

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

Description is well-organized: starts with critical account requirement and alternative, defines purpose, explains internal process, output format, depth differences, and performance expectations. Each sentence adds value, though it is somewhat verbose. Still, clarity is prioritized over 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?

Complete coverage for a complex tool: input requirements (natural language question), depth options with detailed behavior, output structure (findings packet with fields), performance expectations, account requirements, and alternatives. No missing information needed for an AI agent to decide usage and invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enriches understanding by explaining implications of depth levels (e.g., standard adds gap-recovery, thorough adds leads chase) and clarifies that broad questions are fine. Also adds constraint that 'thorough' requires a paid plan, which is helpful for parameter selection.

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

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

Clearly states 'grounded multi-source research across Pipeworx's 1293 structured data sources in one call', contrasts with ask_pipeworx and open-web search, and provides specific examples of suitable questions. Distinguishes well from sibling tools like ask_pipeworx.

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

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

Explicitly states when to use this tool vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and if not signed in, use ask_pipeworx. Also notes account requirements and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This fully explains the behavior beyond annotations, with 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. It front-loads the purpose, then gives usage guidance, and finally describes the return format. Every sentence is informative with no fluff. It is concise yet comprehensive.

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

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

Given the tool has no output schema, the description compensates by explaining the return format (top-N tools with schemas and examples). It does not explain the limit parameter's default or edge cases, but that is covered in the schema. Overall, the description provides sufficient context for the agent to use the tool effectively. A slight deduction for not mentioning the default limit.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mentions aliases for query (task, q, search, description) but adds no significant meaning beyond the schema. Baseline 3 is appropriate as the description does not degrade but does not add much value.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes it from sibling tools by saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This makes the purpose unambiguous and distinct.

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

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

Explicit guidance is provided: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also gives examples of when to use (e.g., 'look up FDA drug approvals'), and implies when not to use (when you already know the specific tool). This is excellent usage direction.

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 and idempotentHint. The description adds valuable behavioral details beyond annotations, such as mentioning it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes that the patents API 'soft-fails until reactivated'. This exceeds the minimal annotation context.

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

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

The description is appropriately sized for a complex tool, front-loaded with example queries that quickly convey purpose. While dense, every sentence adds value; minor redundancy in listing examples could be trimmed but overall is well-structured.

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

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

Given no output schema, the description thoroughly explains return fields (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and sources. It also discloses limitations (patents API sunset). This provides complete context for an agent to understand what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by clarifying that 'value' must be a ticker or zero-padded CIK, and warns that 'names not supported — use resolve_entity first'. This provides critical usage context not fully captured 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 uses specific verbs like 'Tell me about', 'research', 'brief me', and explicitly states it provides a 'full cross-source profile of a US public company'. It distinguishes from siblings by noting that to resolve names one should use 'resolve_entity' first, clearly differentiating its 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?

Explicitly states to 'ALWAYS PREFER' this tool over chaining single-pack lookups for holistic views. It also specifies when not to use it (names not supported) and directs to 'resolve_entity' as an alternative, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, clearly indicating the tool is destructive. The description adds context about clearing sensitive data but does not significantly extend beyond what annotations convey.

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

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

The description is two sentences, front-loading the action and usage guidance with no unnecessary words. Every sentence provides value.

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

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

For a simple tool with one parameter and no output schema, the description, together with annotations and schema, provides complete context. It explains why and when to use the tool, and pairs it 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?

The input schema has 100% coverage with a description for the 'key' parameter. The description does not add further detail beyond the schema, so it meets 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 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from siblings 'remember' and 'recall' by mentioning pairing, making the tool's purpose unambiguous.

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

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

The description explicitly says when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also refers to sibling tools for context, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context by detailing steps: fetches the page, extracts title/description/key links, emits markdown format. This goes beyond annotations, though it omits details on error handling or redirects, which is acceptable given 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 three concise sentences with no wasted words. The first sentence immediately states the core purpose and beneficiary, ensuring clarity. It is well-structured and front-loaded.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers inputs, process, output format, and use cases. It mentions the output is a 'single text blob' in markdown format. The only missing detail is potential limitations (e.g., authentication), but annotations (openWorldHint) imply external access is expected.

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 provides descriptions for both parameters. The description restates 'Full URL' for url and 'Maximum number of link entries' for max_links, adding no new meaning. Baseline is 3 because schema does the heavy lifting.

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, specifying the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes from siblings by focusing on the specific llms.txt format and mentioning AI crawlers, which is unique among the sibling list.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. These provide clear context on when to use. However, it does not mention when not to use it or contrast with alternative tools like 'ai_visibility_check' or 'scan_competitor_ai_presence', which are related but different.

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 fields (id, type, etc.), which is useful 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 action and return fields, no wasted words. Perfectly concise.

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

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

No output schema but description lists return fields. Simple tool with good annotations, fully sufficient for an agent to understand usage.

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

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

Schema coverage is 100% with full description for the only parameter (include_inactive). Description adds no extra parameter information, 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 'List the caller's active subscriptions,' specifying verb, resource, and scope. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides context and primary use cases.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds crucial behavioral details: it's a write operation that sends data, is free, has rate limits, and the team reads digests daily. No contradictions with annotations.

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

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

The description is concise (three sentences plus bullet-like details), front-loaded with the core purpose, and every sentence adds value. No fluff.

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

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

Given the tool's simplicity (3 parameters, 2 required, one nested object), the description is fully complete. It covers what to say, how to structure, constraints, and audience expectations. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances meaning by elaborating on the 'type' enum values and explaining the 'context' object's usage, providing more practical guidance than 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 is for sending feedback to the Pipeworx team, specifying types like bug, feature/data_gap, and praise. It distinguishes itself from all sibling tools, which are focused on data retrieval or other actions, making its purpose unique and unmistakable.

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

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

Explicit guidelines are provided: use for wrong/stale data (bug), missing tools (feature/data_gap), or praise. It advises against pasting end-user prompts and mentions rate limits (5 per identifier per day) and that it's free and doesn't count against quota, giving clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context: data source (CF analytics-engine), no PII, and caching window (5min-1h). This goes beyond annotations sufficiently.

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

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

The description is concise (three sentences plus three bullet points) with no wasted words. It front-loads the main output, then lists use cases, then adds data provenance details. Every sentence adds value.

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

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

Given the simple input schema (one enum parameter) and no output schema needed, the description is complete: covers purpose, usage, behavioral details, caching, privacy, and data source. Nothing missing for this type of tool.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds semantic value beyond the schema by explaining the trade-off between short and long windows ('surfaces what's hot right now' vs 'steady-state demand').

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

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

The description clearly states the function: returns top tools, packs, and call volume over a window. It specifies the resource (Pipeworx usage data) and verb (trending/aggregate), distinguishing it from sibling tools that serve other purposes like asking questions or searching.

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 enumerates three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains window semantics. This provides clear when-to-use guidance without needing 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral details: monotonicity checks, partition-sum checks, scanning top ~200 markets, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB depth, and response structure. 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 detailed and well-structured, starting with purpose, then modes, then technical details. While long, every sentence adds value. It could be slightly more concise, but given complexity, it is appropriate.

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 2 parameters, no output schema, and no nested objects, the description is very complete. It explains the tool's behavior, modes, response structure (opportunities[], partition_check, fill check info), and important caveats (placeholders, Jaccard similarity, when not to trade). It references sibling tool for custom sizing. 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 description coverage is 100% (both parameters have descriptions describing mode and accepted input). The description goes further by explaining behaviors: trending_scan with no args, event slug vs topic seed, and recommends event mode. It also notes that full URLs are accepted, enhancing parameter understanding.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by specifying exact use cases.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and explains when to use topic mode. It also warns about fill check and when not to trade, and references polymarket_fill_risk for custom sizing.

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

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

The description adds extensive behavioral context beyond annotations: details on model families, edge calculation, caching, diagnostics, and filter logic. Annotations indicate readOnlyHint=true, and description confirms no destructive actions. 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 well-structured with clear sections and front-loaded purpose. Every sentence adds value, though some details could be condensed. It's 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?

Given the tool's complexity (9 parameters, rich output structure), the description is extremely complete. It explains output segments, diagnostics, caching, and each filter's role. No output schema exists, so the description fully covers what to expect.

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

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

Schema coverage is 100%, and the description adds meaningful context for each parameter (e.g., 'min_kelly' explanation of sensible betting). It enhances understanding of how filters affect edge detection.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes from sibling tools like polymarket_arbitrage by focusing on edge discovery.

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

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

The description provides clear guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the three segments and filter knobs. While it doesn't explicitly exclude sibling tools, the context makes the use case clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it reads from daily snapshots, uses a lookback, and details limitations (60-day snapshot TTL, decay from daily closes, not intraday). 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 dense but well-structured with clear sections: purpose, response fields (tracked, expired, snapshot_dates), and limitations. It is front-loaded with the core purpose. While slightly verbose, every sentence adds essential information. Minor improvements could tighten wording, but overall effective.

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

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

Given the tool's complexity and the lack of an output schema, the description comprehensively explains the return structure, including details on time-series, trends, decay, expired opportunities, and snapshot gaps. Limitations are also covered. The description leaves little ambiguity about what the tool returns and how to interpret 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%, baseline 3. The description adds value by labeling 'window' as 'snapshot family' and explaining how parameters affect the response structure (lookback, window family). It also connects parameters to the tool's function (e.g., days for lookback). This extra context merits a 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 the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage by focusing on historical trend analysis. The specific answer to 'how long has this edge existed and is it shrinking?' makes the purpose immediately clear.

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

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

The description explains when to use the tool (to understand edge longevity and decay) and contrasts a fresh wide edge with a 3-week-old one. It implicitly differentiates from polymarket_edges (likely for current data) but does not explicitly state when not to use it or list alternatives. The usage context is clear, but exclusion criteria are absent.

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 extensive behavioral context beyond annotations: it explains the order-book walk, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and basket mode specifics (forced_directional_risk, thin_legs). Annotations already indicate read-only, but the description enriches understanding of what happens and its implications. 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 well-structured with clear sections for modes and usage, but it is somewhat lengthy. However, every sentence earns its place by conveying necessary detail about complex behavior. Front-loading the requirement ('REQUIRES one of market or event') helps efficiency.

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 enumerates return fields and explains both modes comprehensively. It addresses real-world pitfalls (thin books, partial fills, dominant loss mode) and provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds crucial nuances: size_usd meaning differs between single-market (max spend/target proceeds) and basket (settlement notional). Side defaults and auto-detection for basket are explained. The description adds value beyond schema, though schema already covers basics.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes two distinct modes (single-market and basket) and explicitly differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it before those 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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the rationale (theoretical overround not capturable, partial fills cause unhedged positions) and requires one of 'market' or 'event', providing clear when-to-use and why.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds safety fields (compatibility_warning, temporal_alignment, skipped counters), openly states that real spreads are rare, and explains behavior for mismatched bet shapes and unrelated events.

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

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

Well-structured with logical flow: purpose, modes, response, safety. Slightly verbose but every sentence adds value. Front-loaded with core concept.

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

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

Given no output schema, the description thoroughly explains the response structure (leg prices, spreads, safety fields, temporal alignment, skipped counters). Covers all critical context for correct usage.

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

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

Schema coverage is 100% with descriptions; description adds context by listing the exact 10 macro shortcuts, explaining override behavior, and providing usage examples 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from any single-venue tool like polymarket_edges or general research 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 describes two modes (topic shortcuts vs explicit tickers), warns that most pre-mapped topics yield compatibility warnings, and explains when spreads are meaningless (e.g., when temporal_alignment:false).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. Description adds value with scoping detail and dual behavior (retrieve vs list), but does not go beyond annotations significantly.

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 primary action, no fluff. Every sentence adds value, making it highly efficient.

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

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

Given the simple parameter schema, strong annotations, and lack of output schema, the description fully covers behavior, scope, and relations to sibling tools. No gaps.

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

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

With 100% schema coverage, description elaborates on the key parameter: omitting it lists all keys, providing it retrieves a specific value. This adds meaningful context beyond the schema's description.

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

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

Description clearly states the tool retrieves a saved value or lists keys, with specific verb+resource. Distinguishes from siblings remember and forget, making purpose unmistakable.

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

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

Provides clear context for use (look up stored context without re-deriving) and mentions scoping. Lacks explicit exclusion or comparison to alternatives, but the use case is well-defined.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint are true and destructiveHint false. The description adds that returned events carry source, citation_uri, raw payload, and that setting mark_read:true flags events as read so next call shows only newer ones. This provides behavioral detail beyond annotations.

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

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

Three sentences, front-loaded with purpose. Each sentence adds essential information: what it returns, how to filter, mark_read behavior, and alternative access for scripts. No unnecessary words.

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

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

No output schema, so the description adequately explains the return structure (source, citation_uri, raw payload). It covers filtering and mark_read mechanism. However, it does not mention the limit and unread_only parameters, which are in the schema but not explained in the description.

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

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

Schema coverage is 100%. The description explains the type, since, and mark_read parameters, including the effect of mark_read. However, limit and unread_only are not described in the description, though the schema covers them. The description adds value beyond the schema for the mentioned parameters.

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

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

The description starts with 'Pull fired events from your subscription feed', which is a specific verb+resource. It distinguishes from sibling tools by focusing on subscription feed alerts, and mentions filtering by type and since, and the mark_read feature.

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

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

The description gives clear context on usage: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This implies when to use the tool versus direct API access. However, it does not explicitly compare against sibling tools or state when not to use it.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, relative date shorthand, and structured response format (changes[] + total_changes + citation URIs). No contradictions.

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

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

The description is a single dense paragraph that front-loads example queries and then efficiently covers sources, parameters, and alternatives. Every sentence serves a purpose with no redundancy.

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

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

Given no output schema, the description does a good job explaining what the tool returns (changes grouped by source, total_changes count, citation URIs). It also notes the soft-fail for patents and fallback behavior. A perfect 5 would require more detail on the exact structure of each change item, but the current level is sufficient for an AI agent to understand the tool's capabilities.

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

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

Schema already has 100% description coverage for all 3 parameters. The description adds value by providing usage examples (e.g., '7d', '30d', '3m', '1y' for `since`) and clarifying that `value` can be a ticker or zero-padded CIK. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool provides a change feed for a company, listing the specific sources (SEC EDGAR, GDELT/GNews, USPTO) and contrasting with the static profile tool entity_profile. The verb 'fan out' and examples of user queries make the purpose unmistakable.

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

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

Explicitly tells when to use this tool and when to use the alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This provides clear guidance for selection among siblings.

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

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

Description adds value beyond annotations: scope by identifier, persistence for authenticated vs anonymous. No contradiction with idempotentHint.

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

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

Four sentences, front-loaded with purpose. Every sentence is informative with no fluff.

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

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

Complete for a simple 2-param tool with annotations; explains storage behavior, scope, and companion 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 covers both parameters fully; description adds concrete examples of keys and values, enhancing 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?

Clearly states the tool saves data for later reuse, with specific verbs and resource (key-value pair). Differentiates from siblings by mentioning recall and forget.

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

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

Explicit guidance on when to use (discover something worth carrying forward) and pairing with recall/forget. Also notes session persistence differences.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. It also details return value structures including citation URIs, going beyond annotations.

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

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

The description is well-structured, starting with examples and usage guidance, then detailing supported types. Every sentence adds value, though slightly verbose. It is front-loaded with immediate use cases and informative without being wasteful.

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

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

No output schema exists, so the description fully covers return values per entity type, including citation URIs. It explains that multiple input forms are accepted (ticker, CIK, name) and mentions auto-disambiguation. Given two entity types, the description is thorough and leaves no ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples of input values (ticker, CIK, brand/generic names) and noting auto-disambiguation for company name inputs. This extra context justifies a 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 it resolves user-spoken names to canonical identifiers, provides example queries, and lists supported entity types (company and drug) with specific outputs. It differentiates from sibling tools by positioning itself as the first step when an ID is needed, contrasting with other entity tools like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It gives clear context for when to use (when asking for ticker, CIK, RxCUI). While it doesn't name specific alternative tools, the guidance is strong. Missing explicit when-not-to-use or alternatives reduces to 4.

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, so the description adds limited behavioral context. It does mention that it probes with ai_visibility_check and returns a ranked list with score, confidence, signal density, but these are functional details rather than behavioral constraints.

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 efficiently convey the tool's action, internal process, use case, and output summary. No wasted words, front-loaded with the main purpose.

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

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

Despite no output schema, the description adequately explains the output structure (ranked list with score, confidence, signal density), the number of entities (2-8), and the internal call to ai_visibility_check. Given the annotations cover safety, the description is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so parameters are documented. The description adds extra meaning by specifying that the first entity is the 'subject' for narrative and the rest are competitors, and clarifies the context parameter's purpose.

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 compares AI visibility across multiple entities side-by-side, specifying it probes each entity with ai_visibility_check and ranks them. This distinguishes it from the sibling tool ai_visibility_check, which presumably handles single entities.

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

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

The description gives a concrete use case (competitive AI-marketing audits) and an example question, guiding when to use it. While it does not explicitly state when not to use it, the sibling tool ai_visibility_check implies that for single entity checks, that tool is appropriate.

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?

Describes composite nature, partial failures (bundlephobia first measurement 5-30s, sources_failed list), and graceful degradation. No annotation contradiction; adds value beyond readOnlyHint, idempotentHint, etc.

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

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

Single paragraph but dense with information. Front-loaded with purpose, then usage, scope, behavior, and output. Could be slightly more structured but still efficient.

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

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

No output schema, so description explains return structure (summary block, per-advisory, links, alternative versions) and partial failure behavior. Covers essential aspects, though format not specified.

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 100% with good descriptions. The description reinforces the schema by noting scoped packages accepted and version defaults. Adds context but doesn't significantly extend 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?

Clearly states the tool is a composite check for npm packages combining deps.dev and bundlephobia, addressing 'should I add this npm package' queries. Distinct from sibling tools which are unrelated or for different ecosystems.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small' and specifies NPM ecosystem only, with alternatives for other ecosystems. Provides clear when-to-use and scope limitations.

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

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

Discloses behavioral traits beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. Annotations already indicate read-only, idempotent, and non-destructive, and the description adds technical detail 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?

Three concise sentences with front-loaded purpose. Every sentence adds value: first sentence defines core, second explains use case and benefits, third gives technical details. No wasted words.

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

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

Despite no output schema, description fully covers return values ('top-N passages with character offsets and similarity scores'), constraints (200K char cap, truncation flag), and pairing with sibling tools. For a moderately complex search tool with rich annotations, this is complete.

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

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

Schema coverage is 100% with decent descriptions for each parameter. The description adds context beyond schema: e.g., text is 'already pulled' document, query is natural-language with examples, limit is 'max passages'. This enhances agent understanding without redundancy.

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

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

Description clearly states 'semantic search INSIDE a fetched record', with specific verb (search within), resource (fetched record), and output (passages with offsets and similarity scores). It distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and explaining the use case.

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

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

Provides clear context for when to use: 'when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. Also mentions pairing with ask_pipeworx_grounded for grounded answers. Lacks explicit when-not-to-use or alternatives beyond the sibling pair, but clear enough for most 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?

The description provides rich behavioral detail beyond annotations: requires OAuth, anonymous/BYO cannot persist, feed is always on, email/sms have caps and verification requirements, webhook is HMAC-signed and auto-disabled after 10 failures. No contradiction with annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false).

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 return value, but is lengthy. However, every sentence adds value, explaining types, channels, and constraints. A minor trim could improve conciseness, but it 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 3 parameters (2 required), 100% schema coverage, no output schema, and moderate complexity, the description covers all necessary context: supported types, parameter formats, delivery channels, authentication requirements, rate limits, and webhook behavior. It is complete for effective tool use.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains each subscription type (sec_8k, polymarket_edge, etc.) with specific parameter examples, and details each delivery channel (email, sms, webhook) including verification, rate limits, and signing. This goes far beyond what the schema provides.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation, and covers supported types and delivery channels.

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 specifies requirements (Pipeworx OAuth account, no anonymous/BYO), supported subscription types with examples, and delivery channels. It could be slightly more explicit about when not to use (e.g., for one-time queries), but the context makes it clear that this is for persistent monitoring.

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 true. The description adds significant behavioral details: it returns 'category-bucketed example questions', 'each with the exact tool + argument shape', and notes it is 'drawn from the live catalog of thousands of tools'. This goes well beyond the annotations.

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

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

The description is moderately long but well-structured, starting with common user queries and then explaining the tool's purpose and output. Every sentence adds value, though some minor trimming could improve conciseness without losing 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 tool's role as an onboarding entry point, the description covers when to use it, what it returns (category-bucketed examples with tool shapes), and the optional topic parameter. No output schema exists, but the description fully explains the return behavior, making it complete for its intended 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 description coverage is 100% with a description for the topic parameter. The description adds meaning by explaining that omitting topic gives a 'cross-category spread' and listing specific focus areas (finance, pharma, etc.), which aids understanding beyond the schema's enumeration.

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

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

The description clearly identifies the tool as an onboarding entry point for new agents, listing example questions and stating it returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by being the first step to learn what Pipeworx can do.

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 it 'FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It provides clear context for when to use it, though it could explicitly mention when not to use it (e.g., after initial onboarding).

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

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

Discloses beyond annotations: explains that deactivation (not deletion) preserves historical events via recent_alerts. Annotations already indicate non-destructive and idempotent, and description adds valuable behavioral detail 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?

Two sentences with no wasted words. Purpose is stated first, followed by essential behavioral constraints.

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

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

For a simple tool with one required parameter and no output schema, the description fully explains the effect (deactivation vs deletion) and how historical events are retained.

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 for the parameter in the schema already explains it. The tool description adds no new parameter details, so baseline of 3 is appropriate.

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

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

Description clearly states the verb 'Cancel' and the resource 'subscription id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains that the row is deactivated not deleted. Lacks mention of specific alternatives but provides 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: uses SEC EDGAR + XBRL, returns verdict, structured form, actual value with citation, and percent delta. Also explains efficiency gain. 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 3-4 sentences, front-loaded with example queries, and every sentence adds value. No wasted words.

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

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

Despite no output schema, the description comprehensively covers input, output types, domain, scope, and the tool's efficiency benefit. Complete for a complex tool.

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

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

Schema coverage is 100% with a single well-described parameter 'claim'. The description adds example formats but does not significantly extend beyond the schema's description. 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 the tool does natural-language claim verification against authoritative sources, with specific example queries and domain (company-financial claims for US public companies). It distinguishes from sibling tools by explaining it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes to company-financial claims. It does not explicitly state when not to use, but the context is clear.

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