Data Winnipeg

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: probing multiple models, scoring return structure (score, confidence, signals, raw_response), and authentication transparency (API key passed through). 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?

Three sentences front-loaded with primary purpose, then usage context and return format. No fluff, every sentence earns its place.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers all aspects: what it does, parameters, return structure, use cases. Missing details on specific signals or raw_response content, but acceptable for a probe tool with annotations.

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 100% description coverage for all 4 parameters, so baseline is 3. Description adds meaning by explaining default model vs Anthropic with key, and that context helps disambiguation. This goes beyond schema descriptions.

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

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

The description clearly states the tool probes LLMs for visibility scoring (0-100) per model, with a specific verb and resource. It distinguishes from sibling tools like ask_pipeworx (single model) and entity_profile (static info) by emphasizing multi-model probing and scoring.

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

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

Provides explicit context for when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions default model and BYO key for Anthropic. However, lacks explicit when-not-to-use or alternatives, though the sibling list suggests other tools for single-model queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable behavioral context: it routes to 4,552 tools across 1,160 sources, fills arguments automatically, and returns structured answers with stable citation URIs. This provides transparency beyond the annotations about how the tool works internally.

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

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

The description is well-structured with front-loading of the key message 'PREFER OVER WEB SEARCH'. However, it is somewhat verbose with repeated emphasis (e.g., 'START HERE' later) and includes many examples that, while useful, could be more concisely summarized. It earns its length for clarity but is not maximally concise.

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

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

Given the tool's complexity (many use cases, multiple siblings, no output schema), the description covers essential context: it lists domains, provides examples, explains routing behavior, and clarifies when to step up to other tools. It does not describe the return format details beyond citation URIs, but this is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% (all 5 aliases for the question parameter are documented). The description does not add any additional meaning beyond what the schema provides; it only reiterates that the tool accepts a natural language question. Since coverage is high, baseline is 3.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and lists many specific domains (SEC filings, FDA drug data, etc.), making the tool's purpose extremely clear. It uses strong verbs like 'routes', 'fills arguments', and 'returns' to describe its action. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly states when to use this tool ('START HERE for most questions', 'prefer over web search') and when to use alternatives ('Step up only when needed: for a hallucination-resistant single answer with verbatim evidence... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also provides example queries that illustrate appropriate usage.

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

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

Discloses refusal reasons, extraction behavior, and cost impact. Annotations already provide safety hints, and description adds rich 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?

Concise yet comprehensive. Front-loaded with key purpose and usage guidance. Every sentence adds value without redundancy.

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

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

Given complexity (multiple refusal reasons, cost tradeoff, extraction process), description is complete. No output schema but return format is thoroughly 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 clear parameter descriptions. Description adds value by explaining that question accepts multiple aliases and is natural language, though schema already covers this.

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 'hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with ask_pipeworx, distinguishing it from sibling tools.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on... Prefer ask_pipeworx for casual lookups.' Also notes cost tradeoff.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, but the description goes far beyond. It details fan-out logic, response shapes, resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits for low confidence and closed markets, wide-spread liquidity warnings, and resolution-rule risk. There is no contradiction with annotations; the description adds extensive behavioral context.

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

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

The description is thorough but long. It is front-loaded with the main purpose and then systematically covers classifiers, examples, response shapes, resolver contract, edge cases, and safety. Every section adds value, though some details (e.g., specific data sources in examples) could be condensed. Overall, it's well-structured for the complexity.

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

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

Given the tool's complexity (resolver, classifier, fan-out, multiple data sources, evidence packet, edge cases), the description covers all essential aspects: input specifications, process overview, output fields, edge cases (closed markets, low confidence, wide spreads, cancellation rules), and safety notes. Since there is no output schema, the description fully explains return values and behaviors.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'depth' parameter with examples (quick vs thorough), the 'market' parameter with multiple input formats, and the 'include_raw' parameter with implications on response size. It provides concrete guidance 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, or question text) and outputs (evidence packet + market-vs-model comparison). The scope is well-defined, differentiating it from siblings like polymarket_edges or polymarket_arbitrage by its comprehensive data-fan-out behavior.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context. However, it does not specify when NOT to use it or mention alternatives, which would improve the score.

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 read, idempotent, non-destructive. The description adds valuable behavioral context: explains data sources (SEC EDGAR for companies, FAERS for drugs), sorting by primary metric, and that off-calendar fiscal years are handled. No contradictions.

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

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

The description is a single, dense paragraph with no wasted words. It front-loads example triggers, then core purpose, then details. Every sentence contributes value.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description fully explains what data is returned for each type, how results are sorted, and that citations are included. No output schema, but the description covers return format sufficiently.

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

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

Schema coverage is 100%. The description adds concrete examples (e.g., tickers like AAPL, MSFT; drug names like ozempic) and clarifies the meaning of each type, going beyond the schema's brief descriptions.

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

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

The description clearly states the verb (compare), resource (entities), and scope (2-5 companies or drugs). It distinguishes from sibling tools like entity_profile by emphasizing side-by-side comparison in one call, and provides concrete example queries that trigger this tool.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' indicating when to use. It lists example queries (comparison phrases) but does not explicitly mention when not to use, though it's implied for single entity lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful context about the exact data returned and the chaining pattern, which goes beyond what annotations provide.

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

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

The description is two sentences, front-loading the purpose and efficiently covering the key behavioral details (returned fields, chaining). 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 keyword-search tool with no output schema, the description is complete: it names the search domain, the returned fields, and how to use the results. No gaps in guidance.

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

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

Schema description coverage is 100%, with each parameter (limit, query, offset) described in the input schema. The description does not add additional meaning beyond the schema, but the schema is sufficient. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches the Winnipeg Open Data catalog by keyword, specifies the returned fields (resource_id, name, description, category, update date), and hints at how to use the output (pass resource_id to query/metadata). It is distinct from siblings, which cover different domains.

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

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

The description implies usage for keyword-based search and tells the agent to pass resource_id to another tool, but does not explicitly state when to use this vs. alternatives or provide exclusions. However, this is sufficient for a straightforward search tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: account required, paid plan for 'thorough', decomposed parallel execution, returns findings packet with gaps, expected 15-60s. 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 thorough but slightly verbose, containing multiple clauses and parentheticals. Could be more concise while retaining key information. Well-structured with clear sections but could be trimmed.

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

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

Given the complexity (2 params, no output schema, many siblings), the description is very complete. It covers behavior, limitations, timing, alternatives, and expected output format. Missing output schema is compensated by describing the findings packet.

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 value by mapping 'depth' enum to number of facets and clarifying 'question' supports broad/multi-part natural language queries. 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?

The description clearly states it performs grounded multi-source research across 1160 structured data sources and returns a findings packet. It distinguishes from siblings like ask_pipeworx by clarifying it is not open-web search and decomposes questions into facets.

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

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

Explicitly states when to use this tool: for broad/multi-part questions over structured data. Provides alternatives for single lookups (ask_pipeworx) and breaking news (ask_pipeworx). Also gives account requirement and paid plan details.

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

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

Description discloses that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' Annotations (readOnlyHint, idempotentHint) are consistent; no contradictions.

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

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

Description is somewhat lengthy but well-structured: purpose, usage context, return format. Every sentence adds value, though the domain list could be trimmed. Front-loaded with key info.

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

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

Given no output schema, the description adequately explains the return format (tools with names, descriptions, schemas). Examples and parameter details are sufficient. No missing critical 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 detailed descriptions for each parameter. Description adds minimal additional meaning beyond listing aliases and providing examples, but the schema already does the heavy lifting. Baseline 3 is appropriate.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and highlights that it returns tool schemas, distinguishing it from sibling tools like 'query' and 'search_within' which perform direct lookups.

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

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

Explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (for single answers).

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

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

Annotations already cover readability and safety. The description adds valuable context: parallel fan-out across sources, soft-failure of USPTO, return structure. Could mention rate limits or auth, but transparent enough.

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 examples and key instructions. Some sentences are dense but each adds value. Slightly longer than necessary, but not problematic.

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?

Explains the return structure in detail (cik, filings, fundamentals, patents, news, LEI). No output schema, but description compensates fully. Sufficient for agent to understand what to expect.

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

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

Schema covers both params, description adds meaning: value must be ticker or CIK (names unsupported), type currently limited to 'company'. This exceeds baseline by clarifying constraints.

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

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

The description clearly states the tool's purpose: providing a holistic, cross-source profile of a US public company. It lists data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields, and gives example queries that illustrate usage.

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 'ALWAYS PREFER over chaining...' for holistic views, and specifies when not to use ('names not supported – use resolve_entity first'). Provides clear context for tool selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing stale/sensitive data but does not elaborate on idempotency or side effects beyond 'Delete'.

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

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

Two sentences: first states purpose, second gives usage guidelines. No wasted words. 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?

For a simple 1-param tool with no output schema, description covers purpose and usage. Annotations fill in safety/behavior. Complete enough.

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

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

Only parameter 'key' has schema description 'Memory key to delete'. Description says 'by key.' Schema coverage is 100%, so description adds no extra meaning.

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

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

Description states 'Delete a previously stored memory by key.' Verb 'delete' and resource 'memory' are specific. Distinguishes from siblings '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 says when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Pairs with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context: fetches page, extracts content, emits markdown. No contradictions.

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

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

The description is a single paragraph that efficiently conveys purpose, process, and use cases without excessive detail. Could be slightly more structured with bullet points.

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

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

Despite no output schema, the description fully explains the output (single text blob ready for site-root/llms.txt). It covers behavior, output format, and practical use cases.

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

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

Schema coverage is 100% (both parameters documented). The description mentions extraction of 'title/description/key links' but does not add meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with specific extraction details (title, description, links) and output format. It distinguishes from siblings like scan_competitor_ai_presence by being focused on a specific deliverable.

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

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

The description lists explicit use cases ('getting a client's site indexed... drafting llms.txt... auditing how an AI crawler would see a competitor') but does not explicitly exclude scenarios or mention 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 cover readOnlyHint, idempotentHint, destructiveHint. Description adds contextual details like specific return fields (id, type, params, etc.) and the include_inactive parameter behavior, which enriches beyond annotations.

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

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

Two sentences, front-loaded with purpose, then usage. Every word is purposeful with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is sufficiently complete: it enumerates return fields and provides usage context. Only minor room for improvement (e.g., clarifying default behavior of include_inactive).

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% for the single parameter (include_inactive). The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions.' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by being a read-only list operation.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it and implies alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the exact returned information (columns, types, row count, category, last-updated) and the parameter format, enhancing transparency beyond the annotations.

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

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

The description is a single sentence with an example, concise and front-loaded with the tool's purpose. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers the return value (schema + metadata with specific fields) adequately. It is complete for its 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% with a description for 'resource_id'. The description provides an example of the ID format but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'Winnipeg Open Data dataset's schema + metadata', and specifies the required parameter 'resource_id' with an example. It distinguishes this tool from siblings by its specific domain and data type.

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

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

The description provides context that this tool is for retrieving schema and metadata of a dataset by resource ID, implying it is used when needing dataset structure and details. It does not explicitly state when not to use or list alternatives, but the context is clear among siblings.

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

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

Annotations do not indicate destructive or idempotent behavior. The description adds important behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads digests daily. No contradiction with annotations (all false).

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then provides usage guidelines, parameter hints, and behavioral notes. Every sentence adds value, with no redundancies or fluff.

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

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

Given no output schema, the description could mention what happens after submission (e.g., confirmation or receipt). However, it does cover the feedback lifecycle (digests, roadmap impact). For a simple feedback tool, this is largely complete, but a brief note on response would push it to 5.

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

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

Schema coverage is 100%, so the description does not need to repeat schema info. However, it adds value by explaining enum values for 'type' (e.g., 'bug = something broke or returned wrong data'), providing constraints for 'message' (1-2 sentences, 2000 chars), and clarifying that 'context' is optional. This enhances 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 uses specific verbs ('tell', 'use') and resources ('Pipeworx team', 'tools/packs') and clearly distinguishes the tool's purpose from siblings. It lists explicit use cases (bug, feature, data_gap, praise) and defines what type of feedback each entails.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides negative guidance ('don't paste the end-user's prompt') and mentions rate limits and quota impact.

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 beyond annotations: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h). Annotations already cover safety and idempotency.

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 plus bulleted use cases. Efficient, front-loaded, no redundancy.

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

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

Complete for a read-only, single-parameter tool. Describes output and caching. No output schema needed.

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

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

Schema covers 100% of parameter. Description adds nuance about window purpose but doesn't significantly expand beyond 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?

Clearly states the output: top tools, top packs, total call volume over a window. Lists three specific use cases. Distinguishes from siblings like discover_tools.

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

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

Explicitly describes when to use (discovery, confirmation, alignment) and explains window trade-offs. Lacks explicit when-not-to-use, but context is clear.

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

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

Discloses key behavioral traits: uses Jaccard similarity threshold for cross-event pairs, filters placeholders, performs fill check against live CLOB depth. No contradiction with annotations (readOnlyHint, idempotentHint). Adds context beyond annotations.

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

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

The description is verbose (over 300 words) and packs many details into run-on sentences. While comprehensive, it could be more concise and better structured. Important information is front-loaded, but the density may hinder quick parsing.

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

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

Covers all essential aspects: input modes, response structure, edge cases (placeholders, low similarity), fill check behavior. Lacks explicit mention of error handling or limits, but given no output schema, it provides sufficient context for an AI agent.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains event and topic parameters with examples (slugs, URLs, seed questions), describes how each mode works and when to use them. Goes well beyond brief schema descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It explains three distinct modes (no args, event, topic) with specific examples, and the output structure is described. It distinguishes itself from siblings by focusing on arbitrage scanning.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for single-event partition_check, topic for cross-event scanning. Recommends event mode for specific markets. Also directs to use polymarket_fill_risk for custom sizing and warns against trading when realizable_edge_pp <= 0. Clear when-to-use and when-not-to.

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 and idempotentHint, and the description adds significant behavioral context: caching at KV level keyed on knobs, edge computation details, slippage assumptions, Fed bet exclusion, and diagnostic info for empty segments. No contradictions.

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

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

The description is lengthy but well-organized with clear sections for model families, knobs, and response structure. Every sentence adds value, though it could be more concise 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 9 parameters, multiple model families, and no output schema, the description is exceptionally complete. It explains the response structure (by_segment), diagnostics, caching, and edge calculation details, covering all necessary context for an agent to use the tool correctly.

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

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

Schema covers 100% of parameters with detailed descriptions, so baseline is 3. The tool description does not add additional parameter-level meaning beyond what is already in the schema.

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

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

The description clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly designed for daily betting discovery. It distinguishes itself from sibling tools like polymarket_arbitrage by detailing five specific model families and their logic.

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 the tool's purpose for discovering opportunities without paging and provides extensive knob details for filtering. However, it lacks explicit when-not-to-use guidance or direct comparisons to alternatives like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: history depth bounded by 60-day TTL, decay computed from daily closes (not intraday), and explanation of response fields including trend and decay rate.

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

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

The description is lengthy but well-structured, with clear sections for response and limits. It front-loads the key question answered and uses formatting (RESPONSE:, LIMITS:) to aid readability. Could be slightly more concise but earns its sentences.

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 read-only retrieval tool with no output schema and two parameters, the description is thorough. It explains exactly what the response contains (tracked, expired, snapshot_dates), defines derived fields (trend, decay), and notes limitations (TTL, snapshot gaps). An agent can fully understand how to use 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 descriptions for both parameters. The description adds context like default values and allowed ranges, but does not provide significant new meaning beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on historical analysis rather than current edges.

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

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

The description implicitly guides usage by contrasting fresh vs old edges, indicating when historical context matters. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to differentiate from sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description confirms this. It adds behavioral details like 'walks the ladder' and explains returns (top_of_book, vwap_fill_price, etc.) and risks (partial fills leading to unhedged positions). No contradiction.

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

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

The description is longer than minimal but well-structured with section headers and bullet points. It is front-loaded with the purpose and each sentence adds value. Could be slightly more concise, but structure aids readability.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains both modes in detail, lists return fields for each, and covers behavioral warnings. Without an output schema, it effectively documents outputs.

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

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

Schema description coverage is 100%, but the description adds significant context beyond the schema: explains mode differences for `market` vs `event`, default behavior for `side`, and interpretation of `size_usd` in basket mode. This adds genuine value.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool.

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

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

The description provides explicit usage conditions: requires one of `market` or `event`, and advises use 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against not using it for basket fills, citing unhedged directional risk.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: conditions for real spreads (equivalent bet shapes), temporal alignment checks, and explanation of compatibility_warning for non-equivalent shapes or unrelated events. This fully discloses edge cases 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 8 sentences long, which is moderately concise. It is front-loaded with purpose and modes, but later sentences include redundant warnings (e.g., 'pre-mapped ≠ tradeable'). While every sentence adds value, the length could be reduced 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?

No output schema is provided, so the description must explain return values. It does so comprehensively: lists response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and their meanings. Edge cases (non-equivalent bet shapes, temporal misalignment) are fully covered.

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

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

Schema coverage is 100%, providing baseline 3. The description adds context: explains the two modes, how explicit parameters override topic-mapped sides, and provides example values. This enhances understanding of parameter interactions, justifying a 4.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-platform comparison. The verb 'spread' and resource 'Kalshi and Polymarket' are specific and unambiguous.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and when to use each. It warns that most pre-mapped topics return compatibility warnings, guiding agents not to assume tradeability. However, it does not explicitly state when not to use this tool or provide direct comparisons with alternatives, which would earn a 5.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description focuses on adding context: it returns JSON, uses SoQL without leading $, and mentions default limit. This goes beyond what annotations provide.

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

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

The description is concise: two sentences, no redundant words. It front-loads the main action and immediately specifies the required parameter and optional filters.

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 7 parameters and no output schema, the description covers the core functionality. It does not explain the pagination behavior beyond limit/offset or the structure of the JSON response, but it is sufficient for an informed user.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by grouping the SoQL parameters, noting the '$' prefix is omitted, and clarifying the result format (JSON). This provides helpful 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 specifies the verb 'Run', the resource 'Socrata SoQL query against a Winnipeg Open Data dataset', and the key parameter 'resource_id'. It distinguishes from sibling tool 'datasets' which likely lists available datasets.

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 implies when to use: when you have a specific resource_id and want to query with SoQL filters. However, it does not explicitly state alternatives or prerequisites, such as needing to call 'datasets' first to obtain the resource_id.

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 behavior. The description adds scoping (anonymous IP, key hash, account ID), the effect of omitting the key (list all), and pairing semantics, all 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 concise with no wasted words. It front-loads the core action and each sentence adds necessary information, making it efficient.

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

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

Given the simple parameter (optional string), no output schema, and full annotation coverage, the description covers all necessary context: purpose, usage, scoping, and complementary tools.

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

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

Schema coverage is 100% and baseline is 3. The description adds value by explaining that omitting 'key' lists all saved keys, and provides usage examples that clarify parameter 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 the tool retrieves a previously saved value or lists all keys, using specific verbs and resource reference. It distinguishes from siblings by explicitly mentioning '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?

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also mentions pairing with 'remember' and 'forget', giving a clear mental model.

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 behavioral details like the effect of mark_read (flagging events as read), and confirms polling suitability, which enhances 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 three sentences, front-loaded with the main purpose, and every sentence adds necessary information without redundancy. It is appropriately concise.

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

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

Given the absence of an output schema, the description explains what fields are returned (source, citation_uri, raw payload). It covers key parameters, mentions polling and alternative access, and provides enough context 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?

All 5 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by providing example filter values ('sec_8k') and explaining the effect of mark_read, slightly improving semantics.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the return includes source, citation_uri, and raw event payload, and provides filtering options. This is a specific verb+resource with enough detail to distinguish it from sibling tools.

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

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

It mentions polling works fine and provides an alternative access method via a direct URL, giving clear context for usage. However, it does not explicitly exclude cases or mention alternatives among sibling tools.

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

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

The description discloses behavior beyond annotations: fans out to multiple sources (SEC, GDELT, GNews, USPTO), fallback logic, and return structure. Annotations already indicate read-only, idempotent, and open-world, which are consistent.

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 yet well-structured, front-loading the purpose and providing examples. Could be slightly more concise, but every sentence adds useful information.

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

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

Given no output schema, the description explains the return structure (changes grouped by source, total_changes count, pipeworx:// URIs). It covers all 3 required parameters and complex multi-source behavior 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 descriptions cover 100% of parameters. The description adds context on accepted formats for 'since' (ISO date or relative shorthand) and clarifies 'value' accepts ticker or CIK. Slight redundancy but adds value.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It provides example queries and explicitly distinguishes from the sibling tool entity_profile.

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

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

The description gives explicit guidance on when to use this tool (recent changes) and when to use entity_profile instead (static profile). It also explains fallback behavior and soft-failures, helping the agent decide.

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

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

Annotations indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds scoping by identifier, 24-hour retention for anonymous users, and pairing with recall/forget. No contradictions. Could mention overwrite behavior but idempotent hint covers it.

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

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

Three sentences, each with clear purpose: what it does, when to use, how it works. No wasted words, front-loaded with core action.

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

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

Given only two parameters fully described in schema and no output schema, the description covers lifecycle (save, recall, forget), scope, and retention. Complete for a storage 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 descriptions for key and value. The description adds concrete examples of key naming conventions (e.g., 'subject_property') and value types (findings, addresses), adding semantic 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 saves data for later reuse across conversations or sessions, specifies key-value pairs, and distinguishes from siblings recall and forget. Verb 'save' with resource 'data' is specific and aligned with the name.

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 when to use (discover something worth carrying forward like ticker, address, preference) and pairs with recall and forget. Also covers persistence differences between authenticated and anonymous sessions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This explains internal behavior beyond annotations.

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

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

Description is front-loaded with example queries, then a clear purpose statement, followed by detailed type breakdowns. Every sentence adds value, and the structure is logical 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?

Despite no output schema, the description thoroughly explains return values for both entity types, including additional fields like citation URIs. It covers input/output semantics completely for a simple 2-param 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 has 100% coverage, but description adds rich meaning: explains what each type returns (e.g., company returns ticker + CIK + company_name + citation URI), provides concrete examples (AAPL, 0000320193, ozempic), and notes auto-disambiguation. This far exceeds the schema's basic enum and description.

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

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

Description starts with example queries, then explicitly states 'resolve a user-spoken NAME to the canonical/official identifier'. It clearly distinguishes purpose from sibling tools like compare_entities or entity_profile, and specifies when to use (when you have a name but need an ID).

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

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

Provides clear when-to-use by saying 'Use FIRST whenever you have a name but need an ID.' Does not explicitly detail when not to use or contrast with siblings, but the context is clear and the tool is positioned as the primary resolver.

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 behavior. The description adds context on how it works (probes each entity with ai_visibility_check, ranks results) and what output includes (score, confidence, signal density). No contradictions with annotations.

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

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

Three sentences front-load purpose, then explain mechanism, then provide use case and output details. Every sentence adds value with no redundancy.

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

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

The description covers the tool's process, output format, and typical use case. Missing explicit mention of entity count range (2-8) but schema covers that. No output schema, so return values are well 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%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions, which are already clear.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check, and ranks results. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implies when to use (multi-entity comparison) versus ai_visibility_check (single entity), but does not explicitly state when not to use or mention alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as expected. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts.

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, front-loading the core purpose and usage guidelines. It contains necessary details without unnecessary verbosity, though minor trimming could be possible.

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 of multiple sources), the description is remarkably complete. It covers what it does, what it returns (listing fields), limitations (npm only v1), and graceful degradation. No gaps identified.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra clarity: scoped packages are accepted for 'package', and a default behavior for 'version' is explained. No ambiguity.

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

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

The description clearly states it's a composite check for adding npm packages, specifying the verb 'scan' or 'check' and the resource (npm package). It distinguishes from sibling tools by explicitly limiting to npm ecosystem and mentioning fallback for other ecosystems.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives a clear when-not: for other ecosystems, use deps.dev:version directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K with truncation flag), and the inclusion of character offsets for verification. This fully discloses technical 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 concise, with each sentence serving a purpose: stating core function, usage context, technical mechanism, and pairing. It front-loads the purpose and is well-structured without waste.

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

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

Despite the lack of an output schema, the description explains the return format (passages with offsets and similarity scores). It also covers edge cases (200K char cap and truncation). Given the moderate complexity, the description is fully complete for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add extra meaning beyond reiterating the parameter roles. Thus, it adds minimal value over the schema, resulting in the baseline score of 3.

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

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

The description explicitly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It clearly identifies the action (search) and the resource (text within a record). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the context of reducing prompt space.

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

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

The description provides clear guidance on when to use: 'Use when the record is too big to cram into the prompt.' It explains the benefits (saves context, returns relevant passages with offsets) and mentions a complementary tool (ask_pipeworx_grounded), effectively differentiating usage.

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

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

Description contradicts the idempotentHint annotation by stating it returns a 'new' subscription id, implying each call creates a distinct subscription. While it provides useful behavioral details like SMS limits and phone verification, the contradiction with annotations severely undermines transparency.

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

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

Well-structured with core purpose first, followed by requirements, types, and delivery details. Sentences are informative, but the length could be slightly reduced without losing value. Still 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 (3 params, nested objects, no output schema), the description covers types, delivery channels, and constraints adequately. Lacks explicit mention of output format beyond returning an ID, which is acceptable.

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

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

Adds extensive meaning beyond the schema: explains each type's parameters with examples, delivery channel options with constraints, and verification steps. Schema coverage is 100%, but description enriches understanding significantly.

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, specifying the action (create), resource (subscription), and return value (new subscription id). It distinguishes itself from sibling tools 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?

Provides explicit when to use (setting up monitoring) and prerequisites (Pipeworx OAuth account). Implicitly excludes use for anonymous/BYO users and suggests alternatives like recent_alerts for pulling alerts, but lacks explicit 'use this when not to use' language.

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 read-only, open-world, idempotent, non-destructive behavior. The description adds that it returns example questions with tool+argument shapes from the live catalog, providing useful behavioral context beyond what annotations convey.

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

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

The description is somewhat verbose (4 sentences) but front-loaded with key synonyms and use cases. While informative, it could be more concise without losing clarity.

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

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

Despite lacking an output schema, the description fully explains the output format (categorized examples with tool+argument shapes) and usage scenarios. It covers all necessary context for a tool that serves as an entry point.

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

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

Schema coverage is 100% with a single parameter. The description adds practical examples and clarifies that omitting the parameter returns a full spread, which is valuable guidance beyond 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's role as the onboarding entry point for new agents, listing synonyms for user intents and specifying the output. It distinguishes itself from siblings by indicating it should be used first to discover capabilities.

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 usage first when unfamiliar with Pipeworx, and explains when to use the topic parameter. While it doesn't enumerate alternatives, the context implies when not to use it, making it clear for the agent.

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 context beyond annotations: it explains that the row is deactivated (not deleted) and historical events stay available. Annotations already indicate mutation and idempotency, but this adds detail on side effects.

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, each providing essential information: what it does and behavioral details. No wasted words, 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 single-parameter tool with no output schema and good annotations, the description is fully complete: it covers purpose, ownership, and post-call behavior.

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

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

Schema coverage is 100% with a single parameter. The description adds value by stating the id is a uuid returned by subscribe, providing source and format 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 states 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description notes 'Ownership is enforced — you can only cancel your own subscriptions', providing explicit guidance on when to use the tool and a constraint. It does not mention alternatives 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?

Adds context beyond annotations: returns verdict with five options, provides citation and percent delta, and replaces multiple sequential calls. No contradiction with readOnlyHint.

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?

Begins with example phrasings, then usage guidance, domain, and return values. Every sentence is informative; slightly long but all content 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 domain, return structure (verdicts, delta, citation), and replaces multi-call workflow. Lacks error handling details but sufficient given no output schema.

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

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

Schema says natural-language factual claim; description adds concrete examples like 'Apple's FY2024 revenue was $400 billion', enriching the meaning beyond the schema alone.

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

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

Description clearly states 'natural-language claim verification against authoritative sources' with specific verb 'verify' and resource 'claim'. Examples of phrasings like 'fact check' differentiate from siblings like ask_pipeworx or deep_research.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies domain 'company-financial claims'. No explicit when-not, but the domain restriction is clear enough for routing.

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