Data Calgary

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds practical details: default model, cost implications (BYO key), and return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

Three sentences, no wasted words. Each sentence adds essential information: what the tool does, default vs paid model usage, and return structure. Perfectly sized for quick comprehension.

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

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

No output schema exists, but the description sufficiently explains the return format. Parameters are covered, and the tool's purpose and limitations are clear. The description is complete given the tool's complexity.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the default model for 'models', the purpose of '_apiKey' (BYO key for Anthropic), and how 'context' helps disambiguate. This context complements 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 provides a specific verb ('probe'), resource ('LLMs', entity), and outcome (visibility score 0-100). It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model scoring and default model details.

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

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

The description lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes the default model and API key requirement for Anthropic. It does not explicitly state when not to use it, but the context is sufficient for appropriate selection.

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

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

Annotations indicate read-only, open-world, idempotent. Description adds specifics: routes to 4552 tools across 1160 sources, returns structured answer with citation URIs. No contradictions.

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

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

Front-loaded with key directive ('PREFER OVER WEB SEARCH'), then explains function, examples, sibling comparisons. Every sentence adds value; length is justified by content density.

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

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

Covers output format (structured answer with citation URIs), usage boundaries, and alternative tools. No output schema, but description sufficiently explains return value.

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

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

Schema coverage is 100% with good descriptions for the parameter and aliases. Description adds examples and context but no additional parameter semantics beyond the schema.

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

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

Description clearly states it routes questions to over 4,500 tools for factual answers with citations, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises preferring over web search, specifies when to step up to grounded or deep_research, and gives many concrete examples (e.g., 'current US unemployment rate').

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description explains the detailed process: routing among 4552 tools across 1160 sources, filling arguments, fetching data, and extracting answer using ONLY the tool result. It lists specific refusal reasons, providing full transparency about 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 a single, well-structured paragraph. It is front-loaded with the main purpose and then provides details in logical order. While concise, it could benefit from bullet points for the refusal reasons, but it is still efficient and clear.

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

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

Given the tool's complexity (high-stakes, many sources, refusal logic), the description covers all critical aspects: purpose, usage context, behavioral transparency, parameter semantics, and return format (including refusal reasons). It lacks an output schema but compensates with a detailed explanation of the response structure.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description adds value by clarifying that 'query, q, prompt, text, input' are all acceptable aliases, which is not obvious from the schema alone. This helps the agent choose any parameter.

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 a 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes to the correct tool, fetches data, and extracts answers only from the tool result. It distinguishes itself from the sibling 'ask_pipeworx' by the extra evidence extraction step, making the purpose very specific.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and gives example domains (financial, legal, medical). Also provides a clear exclusion: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call.

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?

Extensive behavioral details: market resolution, fan-out process, response shape, resolver contract, parent event extraction, news fallback, safety short-circuits, wide spread handling, resolution-rule risk. All align with annotations (readOnly, idempotent). 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?

Very detailed but verbose; front-loads purpose and usage but includes extensive examples and edge cases that could be separate docs. Structured with headers, but length may hinder quick parsing by an AI agent.

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 complex tool with 3 params, no output schema, and many integration patterns, the description is comprehensive: covers input formats, fan-out logic, response fields, confidence levels, safety blocks, and resolution risk. Agent has all needed context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: market parameter accepts slug/URL/text, depth enum explained, include_raw details on summary vs full payload. This adds value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifies acceptable inputs (slug, URL, question text), and gives usage examples like 'should I bet on X'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on data synthesis.

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

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

Explicit usage guidance: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It provides classifier examples and caveats for low-confidence matches, but does not explicitly state when not to use or list 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 read-only, idempotent, and non-destructive behavior. The description adds context about the return format (names, descriptions, resource IDs) and the data source, which is helpful but not extensive. 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 a single, well-structured sentence that immediately conveys purpose, data source, and output. No extraneous content.

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 four parameters with full schema descriptions and the description covers purpose, source, and output, it is complete. No output schema is needed for this 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 descriptions cover all four parameters (limit, query, offset, _apiKey) with clear details. The tool description does not add significant new meaning beyond what the schema provides, only noting the query is by keyword.

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 Calgary open-data catalogue by keyword, returning dataset names, descriptions, and Socrata resource IDs. It distinguishes itself from siblings like calgary_query and calgary_recent by specifying its role as a dataset search that feeds into calgary_query.

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 implicitly guides usage by noting that returned resource IDs are for use with calgary_query, establishing a clear workflow. However, it does not explicitly state when not to use this tool or compare it to other search datasets.

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 the endpoint (data.calgary.ca), full SoQL capability mention, and keyless endpoint option for _apiKey. This adds non-trivial context beyond annotations, but no detailed behavior like rate limits or result format.

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 key info. Each word contributes meaning. No filler.

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

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

The description covers usage, parameters (via schema), and SoQL capabilities. The only gap is no mention of return format (assumed JSON), but given the tool type, it's acceptable. Completeness is high for the complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal value: highlights resource_id as 8-char string and limit defaults/max, but these are already in the schema. The SoQL clause examples are helpful but not critical.

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 verb 'Run a raw SoQL query' against a specific resource ('Calgary open-data resource', 'data.calgary.ca') with exact format ('8-char like "iahh-g8bj"'). It distinguishes from siblings calgary_datasets and calgary_recent, stating their roles.

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

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

The description clearly states when to use this tool (run raw SoQL query) and provides guidance on finding resource IDs via calgary_datasets or using calgary_recent for common ones. Lack of explicit when-not-to-use exclusions is acceptable given the straightforward use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe, idempotent nature is covered. The description adds value by detailing behavior: returns latest rows newest-first, supports SoQL filtering, and optional API key for rate limits. No contradiction with annotations.

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

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

The description is concise (5 sentences) and front-loaded with key points: purpose, recommendation over web search, dataset names, ordering, and filtering guidance. 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?

For a simple read-only tool with complete schema and annotations, the description adequately covers purpose, usage, filtering, and ordering. No output schema is needed. Minor gaps like explicit return format are acceptable given the tool's simplicity.

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

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

Schema coverage is 100% with all parameters described (dataset, limit, where, _apiKey). The description does not add new parameter semantics beyond restating dataset options and limit default already in schema. Meets baseline but lacks extra insight.

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

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

The description clearly states the tool retrieves recent records from Calgary open datasets by friendly name (311, permits), specifying the verb (get recent records), resource (Calgary open datasets), and scope (newest-first). It distinguishes from sibling tools like calgary_query and calgary_datasets by emphasizing no Socrata ID needed and recommending alternatives for complex queries.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH' for common queries and directs 'for anything else use calgary_query'. Provides clear context on when to use this tool versus alternatives, including when filtering with SoQL 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals that it pulls the latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, returns sorted results by primary metric, and includes pipeworx:// citation URIs. This adds substantial behavioral context not present in 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 but efficient, front-loading the main purpose with example queries. It uses bullet-like structure and provides specifics without being verbose. Minor redundancy exists (e.g., repeated examples), but overall it is well-organized.

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

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

Given the tool has two parameters and no output schema, the description comprehensively covers input expectations, data sources, handling of edge cases (off-calendar fiscal years), and output format (paired data + URIs). It fully equips an agent to use the tool correctly without needing additional 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?

While schema coverage is 100%, the description adds meaning by explaining the type enum ('company' or 'drug') and the value format (tickers/CIKs for company, names for drug). It also specifies the range (2-5 items). This supplements the schema well, though it doesn't add deep semantics beyond what the schema already conveys.

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, explaining what data is pulled for each type (SEC filings for companies, FDA data for drugs). It provides example queries like 'X vs Y' and 'head to head', making the purpose unmistakable and distinct from sibling tools.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong usage guideline. It also clarifies when it should be used (comparing entities) and gives examples of the types of queries it handles, leaving no ambiguity.

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

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

Adds significant context beyond annotations: account/sign-in requirement, paid tier for 'thorough' depth, expected response time (15-60s), detailed output format (findings packet with evidence, confidence, source, citation, gaps array). No contradiction with annotations (readOnlyHint, openWorldHint, 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?

Despite length, every sentence adds value. Front-loaded with critical account requirement, then clear explanation of functionality, usage guidance, and output format. Well-structured for quick scanning.

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

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

Given no output schema, description fully explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation, gaps[]). Also covers timing and limitations. Complete for a complex research tool.

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

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

Schema coverage is 100%, but description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and clarifies that questions can be broad/multi-part. Value beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1160 structured data sources, decomposing questions into facets and routing to tools in parallel. It distinguishes from siblings like ask_pipeworx by specifying when each is appropriate.

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 (broad/multi-part questions over structured data) and when not to (breaking news, colloquial current news, or if not signed in). Names alternatives: ask_pipeworx for single lookups or breaking news, and again for unauthenticated users.

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 readOnly, idempotent, and non-destructive behavior. The description adds value by specifying that results include 'names, descriptions, and full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' which aids agent expectation.

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, front-loading the core purpose, then listing example domains and key output features. It is efficient without unnecessary detail, though could be slightly more 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 adequately describes the return value (top-N tools with schemas and examples) and notes that results are call-ready. The tool is simple and annotations are rich, so the description is complete enough for effective 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%. The description explains that the primary parameter 'query' accepts natural language and lists aliases (task, q, description, search), plus provides two examples. This adds context beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and emphasizes the tool's role in discovery, distinguishing it from sibling tools that likely perform specific tasks rather than browse.

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

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

The description explicitly instructs to 'Call this FIRST when you have many tools available,' providing clear context for use. It does not explicitly state when not to use it, but the guidance is sufficient given the tool's discovery nature.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description details the tool's internal behavior: fanning across multiple sources, returning specific fields (e.g., recent_filings with URIs, LEI from GLEIF), and handling of deprecated APIs. 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 verbose but every sentence adds value, front-loading with example queries. It could be slightly more structured, but it's efficient given the complexity of the tool.

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

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

Given the tool's complexity (multi-source, potential failures, specific input formats), the description comprehensively covers input constraints, output details, limitations, and usage patterns. No output schema exists, but the description adequately details return values.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: 'value' expects ticker or zero-padded CIK, not names, and 'type' is limited to 'company'. It also cross-references resolve_entity for name resolution, adding crucial context.

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

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

The description explicitly states the tool's purpose: generating a full cross-source profile of a US public company. It lists example queries and key features like parallel execution, distinguishing it from sibling tools such as resolve_entity and chaining alternatives.

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 when-to-use guidance ('ALWAYS PREFER over chaining...') and when-not-to (names not supported, use resolve_entity first). It also notes limitations like the PatentsView API sunset and soft-fall behavior.

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

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

Annotations already indicate destructive and idempotent; description confirms deletion behavior without contradiction, but adds little 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 concise sentences plus pairing advice; no wasted words.

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

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

For a simple one-param delete tool with annotations, description fully covers purpose, usage, and pairing.

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

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

Schema coverage is 100% with good description for 'key'; description adds no extra meaning beyond what 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?

Description clearly states verb 'delete' and resource 'previously stored memory by key', distinguishing it from siblings like 'remember' and 'recall'.

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

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

Explicitly tells when to use (stale context, task done, clear sensitive data) and pairs with related tools, providing excellent usage 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, openWorldHint, idempotentHint, and destructiveHint false. Description adds that it fetches the page, extracts content, and emits markdown, which provides moderate behavioral insight without contradicting annotations.

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

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

Single paragraph, front-loaded with purpose, then process, then use cases. No extraneous sentences; reasonably concise for the information provided.

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

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

With no output schema, the description explains that output is a single text blob for site-root/llms.txt, which is sufficient for a simple tool. Does not cover edge cases but is complete for typical use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no extra semantic depth 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt', and distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not mention when not to use or alternative tools, but the given contexts are clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about caller-scoped results and returned fields, but does not reveal further behavioral traits beyond schema.

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, no wasted words. First sentence states action and return, second gives usage guidance. Front-loaded and efficient.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, returned fields, and use cases completely.

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

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

Schema has one parameter with full description. Tool description does not add additional semantic detail beyond what schema provides. Schema coverage is 100%, so 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?

Describes specific action ('List the caller's active subscriptions'), lists returned fields, and differentiates by mentioning use cases distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Does not explicitly state when not to use, but the purpose is clear.

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

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

Annotations indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), which is consistent with a feedback submission. The description adds behavioral context: rate limits (5/day), that it's free, doesn't count against quota, and that the team reads digests daily, providing transparency beyond annotations.

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

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

The description is a single paragraph that effectively covers purpose, usage, limitations, and behavioral details in a logical order. While comprehensive, it could be slightly more concise by merging some clauses, but overall 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 (feedback submission) and the absence of an output schema, the description is complete. It explains what to expect (the team reads digests, affects roadmap) and covers all necessary context for correct 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 detailed descriptions for all parameters, including enum values for 'type' and optional structure for 'context'. The description adds additional guidance: 'Describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt', which enriches the semantics beyond the schema.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. It explicitly enumerates use cases (bug, feature, data_gap, praise) and distinguishes it from sibling tools which are primarily query or action 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 provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise). It also includes important constraints: don't paste the end-user's prompt, rate-limited to 5 per identifier per day, and that it's free and doesn't count against quota.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds valuable behavioral context: data source 'CF analytics-engine', absence of PII, and caching behavior (5min-1h). No contradictions with annotations.

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

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

Two focused paragraphs: first states purpose, second lists use cases and metadata. No wasted words, every sentence adds value. Front-loaded with key information.

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

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

For a simple read-only tool with one parameter and no output schema, the description is fairly complete. It explains data source, privacy, caching, and purpose. Missing explicit output structure, but the return values are implied by 'top tools, top packs, and total call volume'.

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 does not add additional parameter info beyond what's already in the schema (e.g., the enum description). The description's mention of windows is redundant with the schema's enum description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific windows, and provides three concrete use cases. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on trending data.

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

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

Three explicit use cases are provided, but no direct comparisons to sibling tools or explicit when-not-to-use guidance is given. However, the use cases serve as strong situational cues.

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

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

Annotations indicate safe, idempotent, non-destructive. Description adds rich behavioral details: monotonicity checks, partition checks, Jaccard similarity threshold (0.30), placeholder filter, fill check against CLOB depth. No contradiction with annotations.

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

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

Description is front-loaded with purpose and modes. Well-organized with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). However, it is somewhat verbose and could be trimmed without loss of essential information.

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

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

Given no output schema, description adequately explains response structure (opportunities[], partition_check, fill_check). Covers edge cases like placeholders and Jaccard similarity. Could more concisely list output fields but overall complete.

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

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

Schema coverage is 100%, but description adds substantial meaning beyond schema: explains event slug format, accepts full URLs, describes topic as seed question and that tool searches. Also clarifies mode behavior and constraints like 'skipped_low_similarity'.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) and uses specific verbs like 'call' and 'pass'. It implicitly distinguishes from siblings by focusing on arbitrage and referencing polymarket_fill_risk for sizing.

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 each mode: no args for trending_scan, event slug for single-event, topic for cross-event. It also provides negative guidance: when fill check shows realizable_edge_pp ≤ 0, not to trade. References sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds extensive behavioral context: caching (1h), model internals (lognormal barriers, GDELT momentum, partition overround with sport-specific bias correction), diagnostic fields (funnel counters, filter_skips), and edge decay warnings. This goes far beyond the annotations' safety profile.

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 verbose but well-structured with clear sections for segments, parameters, and response format. It front-loads the purpose and uses bullet-like formatting. Some technical depth could be externalized, but every sentence adds value for a complex tool.

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

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

Given no output schema, the description fully documents the response structure (by_segment, fed_candidates, diagnostics, per-opportunity fields). It explains why segments might be empty, covers all 9 parameters, and addresses edge cases (Fed notes, caching, slippage assumptions). No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant value: each parameter's purpose, defaults, and interaction effects are explained (e.g., min_kelly filters single-leg only, min_partition_leg_kelly applies to partition legs). Examples and edge cases (e.g., 'thinner books, bump slippage') enrich understanding beyond the schema.

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

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

The description clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees, with a specific use-case: 'what should I bet on today'. It details three model segments, distinguishing its discovery-focused approach from sibling tools like polymarket_arbitrage. The verb+resource is explicit and well-defined.

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

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

The description provides rich usage guidance: it explains when to use filters (min_liquidity, max_spread_pp, etc.), mentions caching behavior, and notes Fed bets are excluded from ranking with rationale. However, it lacks explicit contrast with sibling tools—for example, when to use polymarket_arbitrage instead—so agents must infer differentiation from context.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description goes far beyond by detailing exactly what the tool computes (time-series, first_seen, trend, decay_pp_per_day), the structure of the response (tracked, expired, snapshot_dates), and limits (60-day TTL, gaps due to cache misses). No contradictions.

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

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

The description is fairly compact given the amount of information. It starts with the core purpose, then a clarifying analogy, then lists args and response structure. Slightly verbose in the response section but well-organized 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?

Despite lacking an output schema, the description fully details the response fields and their meanings, including edge_pp_net time-series, trend, decay, expired opportunities with lifespan, and snapshot dates. Limits are also covered. The tool is well-contextualized for an AI agent.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description adds defaults (days=14, window='1wk') and clarifies possible values for window (24hr, 1wk, 1mo), which is not in the schema as enums. This adds meaningful context beyond the schema.

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

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

The description clearly defines the tool as an edge persistence and decay tracker built from daily snapshots. It explicitly answers the question 'how long has this edge existed and is it shrinking?', distinguishing it from sibling tools like 'polymarket_edges' which likely provides current edge data.

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

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

The description provides clear context on when to use the tool (to understand edge persistence and decay) and gives a practical example comparing a fresh edge to an older one. It does not explicitly list alternatives or when not to use it, but the context is strong enough.

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

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

Annotations declare readOnlyHint, idempotentHint, and no destructiveness. The description adds behavioral details: walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc. It also mentions constraints like $500 threshold for edge trades. No contradiction with annotations.

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

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

The description is moderately long but well-structured with clear headings (SINGLE-MARKET, BASKET) and bulleted output fields. Every sentence is functional, providing necessary details or warnings. No superfluous content.

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

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

Given the tool's complexity (two modes, multiple outputs, no output schema), the description thoroughly covers the return structure, risk warnings (partial fills, directional risk), and operational constraints. It is complete enough 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%, but the description adds significant value: explains size_usd differently for single-market vs basket, clarifies defaults and auto-detection for side in basket mode, gives clamp range (10–1,000,000). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and specifies use cases like checking fills before acting on arbitrage signals. This is highly specific and differentiates from siblings like polymarket_arbitrage.

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

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

Explicitly states: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about partial fills converting arb into unhedged directional positions, 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 declare readOnlyHint true, idempotentHint true, destructiveHint false. Description adds rich behavioral context: two modes, response structure with safety fields, explanation of skipped comparisons and temporal alignment, and caveat that pre-mapped topics often return warnings.

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 detailed and front-loaded with the core concept. Some sentences are dense but every sentence adds value. Slightly wordy but well-organized.

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

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

Without an output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). All necessary context for correct tool invocation is provided.

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 each parameter. Description adds value by explaining the topic shortcuts list, how explicit overrides work, and the effect of choosing one mode over the other.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from sibling tools like polymarket_arbitrage by specifying its multi-venue nature.

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 and explicit event identifiers) and warns when spreads are not meaningful (compatibility_warning conditions, temporal misalignment). Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only and idempotent. Description adds scoping to identifier and pairing with remember/forget, providing extra context.

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

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

Three sentences, front-loaded with the main verb and resource. Every sentence adds value with no wasted words.

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

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

For a simple tool with one optional parameter and good annotations, the description fully covers retrieval, listing, scoping, and pairing, leaving no gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no new parameter info beyond what the schema already states.

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

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

Clearly states it retrieves a previously saved value or lists all keys. Distinguishes from sibling tools like 'remember' and 'forget'.

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

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

Explicitly says to use for looking up stored context like ticker or notes, and mentions omitting key to list all. No explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds context about the mark_read parameter's effect on subsequent calls and the structure of returned events, enhancing transparency beyond annotations.

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

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

The description is a single, well-structured paragraph. Each sentence adds value: listing returned fields, explaining parameters, and noting alternative access. No redundant or filler text.

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

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

Even without an output schema, the description fully explains what each event contains and how parameters affect behavior. It also mentions polling suitability and an alternative endpoint, covering all relevant context for a read-only tool.

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

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

Schema coverage is 100%, but the description adds practical details: gives an example type ('sec_8k'), explains that 'since' is an ISO timestamp, and clarifies that mark_read flags events as read so future calls only show newer ones. This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned fields (source, citation_uri, payload). It distinguishes itself from sibling tools like list_subscriptions, subscribe, and unsubscribe by focusing on reading alerts.

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 mentions that polling works fine and provides an alternative REST endpoint for scripts and dashboards, guiding the agent on when to use this tool versus other methods.

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 mark it as readOnly, idempotent, non-destructive, but the description adds critical behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and date format flexibility. This contextualizes the annotations well.

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

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

The description is front-loaded with examples and is well-structured, but it is somewhat lengthy. Each sentence adds value, making it efficient for its complexity.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options), the description covers most aspects: sources, fallback, date formats, and return structure. It lacks explicit error handling notes but mentions soft-fail for patents.

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 good descriptions, but the description adds value by explaining the 'since' parameter's relative shorthand ('7d', '30d', '3m', '1y') and typical use ('30d' or '1m'). It also clarifies that 'type' is limited to 'company', which is not in the schema description.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with concrete example queries ('What's new with X', 'latest on Y'). It distinguishes itself from sibling 'entity_profile' which is for static profiles, making the purpose unambiguous.

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

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

The description explicitly contrasts with 'entity_profile' for static data, and provides example queries that contextualize usage. It also explains fallback behavior (GDELT→GNews). However, it does not systematically list all scenarios where this tool should be avoided in favor of other 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?

Adds key behavioral context beyond annotations: scoped by identifier, persistence differences between authenticated and anonymous sessions (24 hours vs persistent). No contradiction with annotations.

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

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

Four sentences front-load purpose, then usage, then persistence, then siblings. No redundant words; every sentence earns its place.

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

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

Covers purpose, when to use, persistence, scope, parameters, and related tools. No output schema, but simple store does not require return value explanation.

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

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

Schema covers both parameters at 100%, and description adds value by providing key naming examples ('subject_property', 'target_ticker') and clarifying value accepts any text.

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 uses specific verb 'save' and resource 'data', and distinguishes itself from sibling tools 'recall' and 'forget' by stating it is for storing with examples like 'resolved ticker, target address, user preference'.

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?

States when to use ('when you discover something worth carrying forward') and pairs with recall/forget, but does not explicitly exclude scenarios.

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

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

Annotations indicate the tool is read-only, idempotent, and non-destructive. The description adds value by explaining that each call cascades through several lookup endpoints internally and replacing manual lookups. It also details the return format for each entity type, including citation URIs, without contradicting annotations.

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

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

The description is relatively concise given the amount of information, starting with example phrasings, then purpose, then type-specific details. Each sentence adds value, though it could be slightly tighter. Overall 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 complexity (two entity types, multiple lookups) and lack of output schema, the description is remarkably complete. It explains what is returned for each type, including citation URIs, and highlights that it replaces 2-3 manual lookups. No gaps in information.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by explaining accepted values per type (e.g., ticker, CIK, or name for company; brand or generic name for drug) and detailing the output structure. This enhances understanding 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 resolves a user-spoken name to an official identifier, listing example phrasings and specifying that it supports 'company' and 'drug' types. It distinguishes itself by noting that other tools require these IDs, and the phrase 'Use FIRST whenever you have a name but need an ID' provides strong purpose clarity.

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

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

The description explicitly instructs when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives concrete examples. It does not explicitly mention when not to use it or compare to sibling tools like entity_profile, but the guidance is clear and actionable.

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

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

The description discloses the internal process (probing each entity with ai_visibility_check, ranking by score, highlighting most/least recognized) and the output structure (ranked list with score, confidence, signal density). Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds valuable behavioral context without contradiction.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds value with no wasted words. The structure flows naturally from purpose to usage to output.

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 lack of output schema, the description compensates by describing the return format. It also explains the context parameter for disambiguation. However, it could provide more detail on models behavior (e.g., default is workers-ai) which is only in the schema. Overall, adequate but not exhaustive.

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 does not add significant new meaning to parameters beyond what the schema already provides. It references entities and output but doesn't elaborate on models or context behavior.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, ranking them. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the competitive audit use case.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. It doesn't explicitly state when not to use it or mention alternatives, but the context is sufficient for an agent to understand appropriate scenarios.

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

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

Annotations already indicate safe read operations and idempotency. The description adds significant behavioral context: it fans out across two services, returns a detailed summary, and notes that bundlephobia's first measurement can take 5-30 seconds with graceful degradation.

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 lengthier but well-structured, with the purpose front-loaded. Every sentence adds value, including specific examples, ecosystem notes, and behavior under partial failure. No unnecessary repetition.

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

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

Given the tool's complexity (composite check, multiple data sources), the description thoroughly explains what is returned even without an output schema. It covers all key aspects: what is checked, what is returned, and edge cases like partial failures.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add new semantic meaning beyond the schema; it mostly reiterates the purpose. A 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 it is a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size. This distinguishes it from any sibling tools, as none are about package evaluation.

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 provides examples. Also notes NPM ecosystem only in v1 and mentions alternatives for other ecosystems. Partial failure handling is clearly described.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds substantial behavioral details: embedding model (BGE-base-en), similarity (cosine over 500-char windows), character cap (200K with truncation flag), and offset returns for quote verification. 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?

~100 words, well-structured. Front-loaded with core purpose, then usage guidelines, then technical details. 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?

No output schema, so description must cover return values. It explains output includes top-N passages with character offsets and similarity scores, plus truncation flag. Could mention exact offset format or score interpretation, but overall complete for a complex semantic 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%, baseline 3. Description adds context: text parameter mentions max 200K chars; limit parameter gives default and range; query parameter provides examples ('supply-chain risk', 'drug interactions with warfarin'). Adds meaning beyond schema.

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

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

Description clearly states it performs semantic search inside a fetched record, specifying inputs (text, query) and outputs (passages with offsets and similarity scores). Distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Provides alternative: 'Pairs with ask_pipeworx_grounded'. Explains benefits: saves context, returns only relevant passages with verification offsets.

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

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

Annotations provide mutation and idempotency hints. The description adds significant behavioral context: account requirements, delivery channel constraints (phone verification, SMS cap, webhook auto-disable), and type-specific parameters. Missing details on failure scenarios or idempotency behavior, but overall adds 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 lengthy but well-structured with bullet points and examples. It front-loads the main purpose. Every sentence provides value, though some verbosity could be trimmed without losing clarity.

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

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

Given the tool's complexity (multiple types, nested delivery object, no output schema), the description covers input thoroughly. It mentions the return value (subscription ID) and includes details on delivery constraints. The lack of output schema is partially compensated by the input schema's descriptions.

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 each parameter is described in the schema. The description adds examples for each type and explains delivery channel constraints in detail, enhancing understanding beyond schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It uses specific verbs and resources, and distinguishes from siblings like list_subscriptions 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?

The description specifies requirements (Pipeworx OAuth account) and lists supported subscription types with examples. It implies when not to use (anonymous/BYO accounts cannot persist), but does not explicitly compare with alternatives or provide explicit when-to-use/when-not-to-use guidelines.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant context: it reveals that the tool returns category-bucketed example questions, each with exact tool+argument shapes drawn from a live catalog, and explains behavior with no arguments vs. with a topic, going well 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 fairly long but well-structured: it starts with common user queries, then states the core purpose, then details output and usage. It front-loads the key information and every sentence adds value. A slight tightening could improve it, but it is 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 (returns categorized suggestions with tool shapes), the description comprehensively covers purpose, output structure, parameter usage, and positioning among many siblings. Without an output schema, the description compensates by describing the return format. Everything a new agent needs is present.

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 one optional parameter 'topic' with a short description. The description expands on this by listing specific possible values (finance, pharma, etc.) and clarifying that omitting it gives a full spread. With 100% schema coverage, baseline is 3; the added 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 the tool's purpose: it is the onboarding entry point for agents to discover what questions can be asked of Pipeworx. It uses specific verbs like 'suggest questions' and resource 'Pipeworx capabilities', and distinguishes from siblings like ask_pipeworx by focusing on example questions and tool shapes.

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

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

The description explicitly says to use this tool first when you don't know what Pipeworx can do or to learn how to use meta-tools. It explains when to omit topic vs. pass a specific topic. It does not explicitly state when not to use it, but the context is clear enough.

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

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

The description adds value beyond annotations by detailing that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. Annotations indicate non-destructive and idempotent behavior, which aligns with the description.

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 long, front-loaded with the primary action, and contains no unnecessary words. It is 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 tool (1 param, no output schema, adequate annotations), the description provides sufficient context about ownership, deactivation, and historical availability, meeting the needs for selecting and invoking 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 the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no further semantic detail 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 'Cancel a subscription by id,' specifying the verb (cancel) and resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions') and what happens upon cancellation ('deactivated, not deleted'), providing clear context. However, it does not explicitly mention when not to use this tool or name alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: returns a verdict with possible values, structured form, actual value with citation, and percent delta. It also explains that it replaces multiple sequential calls, and 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 and front-loaded with query patterns, purpose, and usage. Every sentence adds value, concisely covering scope, return value, and benefits. No wasted words.

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

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

Given the tool's complexity (single claim, limited scope), the description is fairly complete: explains scope, return format, and value. However, it lacks details on error handling or what happens for unsupported claim types, though the 'unsupported' verdict is mentioned. Output schema is absent but return values are described.

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 good description of the 'claim' parameter. The description provides example claims similar to the schema, adding minimal new meaning. Baseline is 3 due to high coverage, and the examples do not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific verb ('validate') and resource ('claims'). It distinguishes from siblings by noting it replaces 4-6 sequential calls, and provides example query patterns.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also defines scope limits (company-financial claims for US public companies). However, it does not explicitly state when not to use or name alternative tools, though the sibling list implies no direct substitute.

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