Data Toronto

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

With annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds value by detailing the probe behavior, default free model, API key passthrough, and return structure (per-model score, confidence, signals, raw_response). No contradictions.

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

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

The description is three sentences, about 50 words, with no redundant phrases. It front-loads the core action, then provides key configuration details, and ends with return format and use cases. Every sentence is essential.

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 clearly explains what the tool returns (per-model object and combined view). It covers main configuration (default model, optional API key), required parameter (entity), and optional parameters (models, context). The annotations further support safety and idempotency, so the description is complete 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% with descriptive parameter descriptions. The tool description adds context beyond the schema (e.g., default model, that _apiKey is required for Anthropic, scoring range). This provides added meaning for parameter usage.

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

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

The description uses a specific verb ('probe') and resource ('LLMs'), states the output ('score visibility 0-100 per model'), and distinguishes from siblings by focusing on AI visibility across models. It is clear and unique among the sibling tools.

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

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

The description explicitly specifies the default model and the condition for using Anthropic (requires _apiKey), and lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring). It does not explicitly mention when not to use or alternatives, but provides sufficient context for typical usage.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safe, non-destructive operation. Description adds that it routes to 4,552 tools, fills arguments, and returns structured answers with stable citation URIs. No contradictions; context 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?

Front-loaded with key preference statement, followed by detailed usage and examples. While lengthy, every sentence adds value; structure is logical and clear.

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

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

Given no output schema, description covers return format (structured answer with citation URIs), parameter usage, and comprehensive context for when to use. Examples and sibling comparisons ensure completeness for an information retrieval tool.

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

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

Schema coverage is 100%, describing aliases for the question parameter. Description adds natural language usage examples and guidance on what kinds of questions to ask (e.g., 'current US unemployment rate'), improving usability beyond 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?

Clearly states the tool routes questions to a vast set of tools and returns structured answers with citations. Explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, using specific verb+resource phrasing.

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 (factual questions, authoritative data) and when-not-to-use (broad questions use deep_research, hallucination-resistant use ask_pipeworx_grounded). Also mentions it works for breaking news, offering clear context for 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?

The description adds significant behavioral detail beyond the annotations: it explains the internal routing (picking the right tool from many sources), the extraction process using only tool results, and the exact return format including successful and refusal responses. It also notes performance cost (one extra LLM call). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and return format, then provides clear usage guidance and cost trade-off. Every sentence serves a purpose without redundancy. It is appropriately sized for the complexity of the tool.

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

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

Despite the absence of an output schema, the description thoroughly covers the return values (success and refusal) and the tool selection process. It provides sufficient context for an agent to understand invocation behavior. A minor gap is the lack of detail on how the '4,552 tools across 1160 sources' are routed, but this is background knowledge not essential for invocation.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, and they are all aliases for 'question'. The description does not add new meaning beyond what the schema already provides; it only briefly mentions aliases. Baseline 3 is appropriate when schema fully covers parameters.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies that it extracts answers from tool results, returns evidence and refusal reasons, and distinguishes itself from its sibling 'ask_pipeworx' by being grounded and costing an extra LLM call.

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

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

Explicitly provides when to use this tool (when answers will be quoted, cited, or acted on, especially for facts) and when not to (prefer 'ask_pipeworx' for casual lookups). It also names the alternative tool, making the usage guidance complete.

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

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

The description goes far beyond annotations by detailing market resolution confidence, parent_event extraction, news fallback mechanisms, safety short-circuits, wide-spread warnings, and resolution-rule risk. All safety and behavioral traits are thoroughly disclosed.

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

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

The description is very long and covers many details. While front-loaded with the main purpose, it includes extensive technical specifics that could be streamlined. It is appropriately structured for complexity but could be more concise.

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

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

Given the tool's complexity (multiple fan-out patterns, response shapes, edge cases), the description is exceptionally complete. It explains inputs, process, output fields, safety guards, and resolution risks, leaving no significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal additional parameter detail beyond the schema (e.g., the examples illustrate market input but no new 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 that the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the inputs (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage through its unique research workflow.

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

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

The description provides explicit use cases (e.g., 'should I bet on X', 'what does the data say about Y') and gives multiple examples. However, it does not explicitly mention when NOT to use this tool or list specific alternatives, though the sibling list implies options.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds critical context: handles off-calendar fiscal years correctly, cites examples (AAPL Sep, NVDA Jan), specifies data sources (SEC EDGAR/XBRL, FAERS, FDA), and explains sorting and return format (paired data + citation URIs). No contradictions.

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

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

The description is about 10 sentences, front-loaded with example queries. Every sentence adds value, but it could be slightly more concise. Structure is logical and easy to parse.

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, different data sources, fiscal year handling, sorting), the description is comprehensive. It covers what data is returned for each type, mentions citation URIs, and explains the sorting behavior. No output schema, but the description adequately informs about returns.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains difference between 'company' and 'drug' types, provides concrete examples for values (tickers/CIKs for company, drug names for drug), and details what data is pulled for each type. This goes well 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 uses specific verbs ('Compare', 'X vs Y', 'rank these companies') and identifies the resource (2-5 companies or drugs). It distinguishes from siblings like 'entity_profile' by emphasizing side-by-side comparison and replacing multiple sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear usage context. It also explains what data each type pulls and that results are sorted by primary metric. Minor lack of explicit when-not or alternatives beyond the preference.

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

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

The description adds significant behavioral context beyond annotations. It explains that the tool decomposes questions, routes to parallel tools, returns a findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, with explicit gaps[] for unanswered facets. It also notes an expected 15-60s response time and that topics not in the catalog return empty gaps. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with this 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 relatively long but well-structured. Critical information (account requirement, alternative tool) is front-loaded. Each sentence serves a purpose, though some redundancy exists (e.g., 'this is NOT open-web search' could be implied). The length is justified given the tool's complexity and many sibling tools.

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 is comprehensive for a complex tool. It covers prerequisites (account, sign-up link), when to use alternatives, what the tool does internally, output format (findings packet with gaps), and limitations (empty gaps for uncataloged topics). Even without an output schema, the description sufficiently explains return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the depth enum values with counts ('quick=3, standard=5 (default), thorough=8 (paid plans)') and clarifying that the question can be broad/multi-part. This extra context justifies a score of 4.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources... in ONE call'. It distinguishes from siblings like ask_pipeworx by explaining that this tool is for broad/multi-part questions over structured data, whereas ask_pipeworx is for single lookups or breaking news.

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

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

The description provides explicit guidance on when to use this tool vs alternatives. It states: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and that 'thorough' depth requires a paid plan.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds value by stating the return format (top-N tools with schemas, examples, and ready-to-call format) and the behavior of returning curated examples without needing second lookup.

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

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

The description is fairly concise given the amount of information. It is front-loaded with the primary action. The list of domain examples adds length but is useful for illustration. Every sentence serves a purpose, though minor trimming could be made.

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

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

With 100% schema coverage and no output schema, the description covers what the tool returns (top-N tools with schemas and examples) and when to invoke it. It is complete enough for an agent to understand its role and function without additional context.

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

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

Schema coverage is 100% with each parameter described in the schema. The description adds minimal extra meaning beyond the schema; it mentions that 'query' accepts aliases (task, q, description, search) but the schema already lists them. 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: 'Find tools by describing the data or task.' It specifies the resource (tools) and action (discover/browse/search). It distinguishes from siblings by positioning itself as the meta-discovery tool, listing diverse domain examples.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It provides clear context and examples but does not explicitly state when not to use it, though this is implied.

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

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

Annotations already declare readOnly, openWorld, idempotent hints. Description adds context on data sources, a sunset (PatentsView soft-fail), and return fields. No contradiction, but the added value is high.

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 informative but lengthy with many example queries. While dense, it could be more concise; however, every sentence adds value.

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

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

No output schema, but the description thoroughly explains return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). Also addresses name resolution and soft-fail behavior. Complete for a holistic profile 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 description coverage is 100%. The description adds extra context on value format (ticker or CIK) and reiterates that names are not supported, going 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 provides a full cross-source profile of a US public company, listing example queries and specifying data sources. It distinguishes from siblings like resolve_entity by noting that names are not supported.

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 'ALWAYS PREFER over chaining single-pack...lookups' and instructs to use resolve_entity first if only a name is available. Provides clear when-to-use and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so description adds no new behavioral traits. The description says 'Delete', which is consistent. With annotations present, the bar is lower, but no additional context (e.g., irreversibility, auth needs) is provided beyond a use case.

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 compact sentences with no redundancy. First sentence states the core purpose, second provides usage guidance and sibling references. Every word is purposeful.

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

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

For a tool with 1 parameter, no output schema, and clear annotations, the description covers the essential information: what it does, when to use it, and how it relates to siblings. No significant gaps.

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

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

Schema has 100% coverage with parameter 'key' described as 'Memory key to delete'. The description does not add any further meaning or format details for the parameter. 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 title 'Forget' and description 'Delete a previously stored memory by key' specify the action (delete) and resource (memory). It explicitly mentions sibling tools 'remember' and 'recall', distinguishing this tool's purpose as deletion vs storage or retrieval.

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 clear use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It references sibling tools for complementary actions. No explicit when-not-to-use is given, but the when-to-use is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond annotations by explaining the fetching process, extraction of title/description/links, and output format, without contradiction.

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

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

The description is concise with two sentences and a bullet list, all front-loaded and every sentence adds value. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema, rich annotations), the description is complete: it explains what it does, how it works, output format, and 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%, so baseline is 3. The description does not add specific parameter explanations beyond what the schema provides, but it implies the role of URL and max_links indirectly.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself from siblings by focusing on a specific output format and use case.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds scope (caller's subscriptions) and return field list, enhancing transparency beyond annotations.

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

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

Two sentences, front-loaded with purpose. No redundancy, every sentence adds value.

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

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

No output schema, but description lists all return fields. Tool is simple with one optional param; description covers what an agent needs.

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?

Single parameter is fully described in schema (100% coverage). Description adds no extra semantics; baseline score is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling subscribe/unsubscribe tools.

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

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

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

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

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

Beyond annotations (which are all false), the description adds critical behavioral details: free, no quota impact, rate-limited to 5 per identifier per day, and that feedback is read daily and affects roadmap. No contradictions with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: usage conditions, limitations, and tips. No fluff.

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

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

Given there is no output schema, the description nonetheless covers all essential aspects: what, when, how, limits, and consequences. It is completely adequate for an AI agent to decide when to invoke and how to fill parameters.

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

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

Schema coverage is 100%, but the description adds meaning by explaining each type (bug, feature, etc.) and providing guidelines for the message field. It also describes the optional context object's purpose, enhancing schema understanding.

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

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

The description uses the specific verb 'Tell' with the resource 'Pipeworx team' and clearly defines the types of feedback (broken, missing, needs to exist). It distinguishes itself from sibling tools as the dedicated feedback channel, with no ambiguity.

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 the tool: for bugs, feature requests, data gaps, or praise. Also provides a negative guideline: 'don't paste the end-user's prompt.' This leaves no doubt about appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, caching duration (5min-1h), and aggregated nature. No contradictions with annotations.

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

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

The description is very concise with three clear bullet-point use cases. Every sentence adds value, and the key output is front-loaded. Efficient and well-structured.

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

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

Given no output schema, the description adequately covers what the tool returns (top tools, top packs, call volume) and notes caching. It could briefly mention response format (e.g., 'returns JSON'), but is sufficiently complete for a simple read-only tool.

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

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

Schema coverage is 100% for the single parameter 'window', which has enums and description in schema. The description adds semantic value by explaining the implications of window choices (shorter windows for hot trends, longer for steady-state demand).

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

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

The description explicitly states the tool returns top tools, packs, and call volume over a window. It lists three specific use cases, differentiating it from siblings like 'discover_tools' by focusing on trending data derived from CF analytics.

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 indicates when to use the tool through three numbered use cases. While it doesn't explicitly state when not to use or compare to siblings, the use cases provide clear context for 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?

The description discloses many behavioral details beyond annotations: the algorithm (monotonicity violations, partition-sum checks), semantic anchor (Jaccard similarity threshold), partition filter (placeholder slugs), fill check (CLOB depth), and response structure. No contradictions with annotations (readOnlyHint, idempotentHint 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 lengthy but well-structured: it starts with the main purpose, then details modes, and gradually adds algorithmic details (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides essential information for a complex tool. Slightly verbose but not wasteful.

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

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

Given no output schema, the description fully compensates by describing the response fields (opportunities[], partition_check). It covers all important aspects: tool behavior, parameter usage, algorithmic details, caveats (fill check), and a reference to a sibling tool. Comprehensive for a two-parameter 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 tool description adds value by providing concrete examples of event slugs, clarifying that full URLs are accepted, and explaining the difference between the two modes more thoroughly. This enhances semantic understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two primary modes (event and topic) and explicitly differentiates from sibling tools like polymarket_fill_risk by saying 'For custom sizing use polymarket_fill_risk.'

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

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

The description provides explicit guidance: 'Call with NO args for a trending_scan... pass event for strongest per-event partition_check, or topic for a themed cross-event scan.' It explains when to use each mode (e.g., event recommended for a specific market, topic for cross-event scanning) and gives examples. It also warns when not to trade based on fill check results.

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

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

Annotations provide safety hints, but the description adds rich behavioral context: caching ('Cached 1h at the KV level'), diagnostic output for empty segments, 24h-move warnings, and detailed tradeable-edge knob effects. No contradictions with annotations.

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

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

The description is long but well-structured with clear paragraph organization and front-loaded purpose. Every sentence adds necessary detail, though some verbosity could be trimmed for agent efficiency.

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

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

Given the complexity of three model families and nine parameters, the description fully covers output structure (by_segment, diagnostics), filtering logic, and caching behavior. No output schema exists, but the description adequately explains response format.

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%, yet the description adds substantial value by explaining parameter interactions (e.g., min_kelly vs min_partition_leg_kelly), providing default values, and offering practical advice (e.g., slippage_pp comments on execution).

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 specific verb 'scan' and resource 'Polymarket markets', and distinguishes from siblings by detailing three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) for edge detection, making it distinct from arbitrage or tracker tools.

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

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

Explicitly states 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' implying when to use. Does not explicitly list when not to use, but the context of sibling tools and the detailed knob descriptions provide implicit guidance.

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

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

The description complements the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing the response structure (tracked, expired, snapshot_dates) and limitations (history depth, decay calculation). No contradictions with annotations.

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

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

The description is well-structured, front-loading the purpose, then detailing return fields, then limits. While slightly verbose in the response description, every sentence adds value. It could be trimmed but remains clear.

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

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

Given the simplicity of parameters and lack of output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and includes important caveats about data availability and decay computation. It is complete for the tool's complexity.

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

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

The schema coverage is 100%, so the description adds minimal extra semantics. It restates default and max values for 'days' (though slightly inconsistent with schema clamp), and explains 'window' as snapshot family. It does not significantly enhance understanding beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It uses specific verbs like 'Answers' and describes the core question ('how long has this edge existed and is it shrinking?'), distinguishing it from sibling tools like polymarket_edges which likely provide current edge data.

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

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

The description provides context on when to use the tool (for historical edge analysis) and contrasts fresh vs. old edges. It also sets expectations with limits (60-day TTL, daily closes). However, it does not explicitly state when to avoid using it or name alternative tools for specific scenarios.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description discloses detailed behavior: walks order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled for single-market; theoretical_sum vs realizable_sum, thin_legs, forced_directional_risk for basket. Warns about partial fills converting arb to directional risk. No contradiction with annotations.

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

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

Description is long but well-structured with clear headings for modes. Front-loaded with core purpose. Each sentence adds value, but could be slightly more concise. For the complexity, appropriate length.

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

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

Despite no output schema, description fully lists returned fields for both modes, covers edge cases (thin legs, forced directional risk), and explains basket mode implications. Complete for the tool's complexity.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning by explaining parameter semantics in context (e.g., size_usd meaning for buys vs sells, basket mode interpretation as settlement notional), default values, and clamp range. Adds value beyond schema.

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

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

Description clearly states it checks realizable-vs-theoretical edge against live order book depth, with two distinct modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying exactly what it does and when to use it.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides rationale about thin books and hedged positions, guiding the agent clearly.

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

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

Adds significant context beyond annotations: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counts), and warns that most pre-mapped topics return compatibility warnings. 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?

Well-structured with front-loaded purpose, but slightly long. Every sentence adds value; minor conciseness improvement 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?

Thoroughly explains response structure, edge cases, and safety fields despite no output schema. Covers all necessary context for a 3-parameter tool.

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

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

Schema covers all parameters (100% coverage). Description adds use context, lists topic shortcuts, explains override behavior. Adds meaningful context 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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and is distinct from siblings like polymarket_arbitrage.

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

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

Explicitly describes when to use (to check spread between venues) and when not (compatibility_warning fires, no arb exists, events unrelated). Provides guidance on temporal alignment and equivalence of bet shapes.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds scoping detail ('Scoped to your identifier...'), which is beyond annotation info. No contradictions.

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

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

Three sentences, no redundancy. The main action is stated first, followed by usage context and integration with siblings. Every sentence adds value.

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

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

Given low complexity (1 optional param, no output schema) and good annotations, the description covers purpose, usage, scoping, and sibling relationships. Nothing essential missing.

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

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

Schema coverage is 100% with a clear description for the single optional 'key' parameter. The description repeats that omitting key lists all keys, but adds no additional nuance 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 retrieves saved values or lists keys, with specific verbs ('Retrieve', 'list') and resource ('value previously saved'). It contrasts with siblings (remember, forget) by naming them explicitly.

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

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

The description explains when to use ('look up context the agent stored earlier') and how it relates to other tools ('Pair with remember to save, forget to delete'). It lacks explicit when-not scenarios, but context provides adequate guidance.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) are consistent. Description adds important behavior: returns from a persisted feed, mark_read flags events as read, and it's poll-friendly. 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?

Four sentences, all adding value: main purpose, return fields, filtering options, and alternative endpoint. No redundant words. Efficient and clear.

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

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

For a read-only tool with 5 parameters, no output schema, and rich annotations, the description covers return structure, filtering, and alternative access. Sufficient for an agent to use effectively.

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

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

Schema coverage is 100%. Description adds examples (e.g., 'sec_8k' for type) and clarifies mark_read effect. Since the schema already describes each parameter, the description enhances with real-world usage context, justifying a score of 4.

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

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

The description starts with a clear verb and resource: 'Pull fired events from your subscription feed.' It specifies returned fields (source, citation_uri, payload) and distinguishes itself from siblings like list_subscriptions and ask_pipeworx by being a focused read tool for alerts.

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

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

Provides usage context: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This guides when to use the tool vs the direct API. Also explains filtering by type and since, and mark_read behavior. Lacks explicit when-not-to-use statements.

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 fan-out behavior to three sources, fallback from GDELT to GNews, and soft-fail for USPTO. This goes beyond the readOnlyHint annotation by detailing the operational logic.

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

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

The description is front-loaded with example queries but is somewhat lengthy. However, every sentence adds necessary context; minor verbosity is justified by the information density.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats) and no output schema, the description fully covers what the agent needs to know: sources, fallback, parameter details, return structure, and alternative tool context.

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

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

Schema coverage is 100% but the description adds value by explaining the `since` parameter formats (ISO date vs relative shorthand) and the `type` parameter's current limitation to 'company', thus enhancing usability 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 provides a change feed for a company across multiple sources (SEC, news, patents) within a time window. It distinguishes from the sibling tool entity_profile by specifying when to use each.

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

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

Explicitly provides example user queries and advises using entity_profile for static profile needs, offering clear when-to-use and when-not-to-use guidance relative to an alternative.

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

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

Annotations already indicate idempotent and non-destructive; description adds persistence details (24 hours for anonymous) and scoping, but 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 concise sentences, no redundancy, front-loaded with purpose, efficient use of words.

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

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

Covers purpose, usage, persistence, and pairing; no missing information given the tool's simplicity.

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

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

Schema already describes both parameters fully (100% coverage); description adds examples and context for keys and values, enhancing 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 uses a specific verb ('Save') and names the resource ('data the agent will need to reuse later'), and clearly distinguishes from sibling tools like 'recall' and 'forget'.

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), provides examples, and notes pairing with 'recall' and 'forget'.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: cascading through multiple endpoints, auto-disambiguation for company input, and explicit return fields per type (including citation URIs). No contradictions with annotations.

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

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

The description is well-structured, starting with example queries to immediately convey purpose, then detailing supported types. Every sentence adds meaningful information. While not overly long, it could be slightly more concise, but it remains focused and front-loaded.

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

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

Given the tool's simplicity (2 params, no output schema) and presence of annotations, the description is complete. It covers entity types, input formats, return values, and internal cascading. It does not detail error handling, but for a lookup tool this is acceptable.

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

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

Schema coverage is 100%, with clear descriptions for both parameters. The description adds value beyond the schema by explaining return formats (e.g., 'ticker + 10-digit CIK + company_name + citation URI') and providing example values for both types. This helps the agent understand the output structure.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific verb 'resolve' and resource 'name to ID'. It distinguishes from siblings by advising 'Use FIRST whenever you have a name but need an ID.' The examples and list of supported types make the purpose unambiguous.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. It lists supported types and gives examples, but does not explicitly mention when not to use it or alternatives for unsupported entity types. However, the directive is strong enough for most cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns a ranked list with score, confidence, and signal density per entity, and explains the probing process. No contradictions or missing behavioral traits.

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

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

The description is concise, with two sentences that immediately convey the tool's function. The first sentence is a clear front-loaded statement. Every sentence serves a purpose without unnecessary detail.

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 there is no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). All parameters are well-documented in the schema, and the description adds procedural context. The tool is complex but the description is sufficient for an AI agent to understand and invoke it correctly.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds value by noting that the first entity is treated as 'subject' for narrative and that models defaults to 'workers-ai'. 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 clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It specifies that it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides clear context: useful for competitive AI-marketing audits, with an example question. It does not explicitly state when not to use or list alternative tools, but the context is strong enough to guide 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?

Beyond annotations (readOnly, idempotent), description reveals multi-service fan-out, potential 5-30s delay for bundlephobia first measurement, and graceful degradation with sources_failed list. No contradiction with annotations.

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

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

Single paragraph but dense and efficient. Front-loads purpose and usage. Could benefit from short bullet-like structure, but no surplus content.

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

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

With no output schema, description fully details return fields (summary block, per-advisory detail, links, alternatives) and covers edge cases (partial failures, timeouts). Complete for a 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?

Both parameters are fully described in schema (100% coverage). Description adds clarifying examples (scoped packages, default version behavior) but mostly echoes schema info, so slightly above baseline.

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

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

Starts with a clear composite purpose ('should I add this npm package?') and specifies the verb 'scan' and resource 'npm package'. Distinguishes from sibling tools by noting NPM-only scope and referencing alternative 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?

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also provides exclusion criteria: other ecosystems fall under 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?

Discloses technical details beyond annotations: embeddings model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars), truncation behavior with flag. Also mentions that passages have offsets for verification. Annotations already declare readOnlyHint, idempotentHint; description adds significant 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?

Description is compact (~120 words) and front-loaded with purpose. Structured logically: purpose, use case, pairing, technical details. Every sentence adds value; no redundant or boilerplate language.

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 necessary aspects: input parameters, output format (passages with offsets and scores), behavior under overflow, pairing with sibling, and use case guidance. No output schema, but description sufficiently explains returns. Complete for a tool with 3 parameters.

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 with descriptions. Description reinforces meaning: for 'text' gives example content (SEC 10-K, article), for 'limit' mentions range (1-20, default 5), for 'query' provides examples. Adds context about top-N passages and character offset output, slightly augmenting schema.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and the use case of searching inside a large fetched record.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt'. Provides guidance on alternatives: 'Pairs with ask_pipeworx_grounded' and explains the workflow. No ambiguity.

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

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

The description adds behavioral context beyond annotations: it mentions auth requirements, return of subscription id, and rate limits (10/day SMS). Annotations indicate idempotentHint=true, but the description does not elaborate on idempotency; 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 relatively verbose but well-organized: it starts with purpose, then lists types and delivery. Each sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types), the description covers all necessary aspects: auth, supported types, parameter formats, delivery channels, limits, and return value. No output schema exists, but the return value is mentioned.

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

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

Schema coverage is 100%, but the description adds significant meaning with type-specific examples, parameter hints, and detailed delivery options (e.g., webhook signing). This goes beyond the schema's simple type descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific verb and resource. It distinguishes itself from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides explicit guidance on when to use (proactive monitoring), prerequisites (OAuth account), supported types with examples, and delivery options with limits. However, it does not explicitly contrast with alternatives or state when not to use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that the tool returns 'category-bucketed example questions' with 'exact tool + argument shape,' which is significant behavioral context beyond annotations. No contradiction.

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

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

The description is front-loaded with common user queries and uses bullet-like formatting for categories. Though lengthy, every sentence adds value, maintaining good structure.

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

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

No output schema exists, but the description thoroughly explains the return format (category-bucketed example questions with tool+argument shape). It also mentions the live catalog of thousands of tools, providing complete context for usage.

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

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

Schema coverage is 100% with a description. The tool description adds value by explaining the effect of omitting vs. specifying the topic and listing allowed values, exceeding the baseline 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 clearly states the tool is an onboarding entry point that returns categorized example questions about Pipeworx's capabilities. It uses specific verbs and distinguishes itself by being a meta-tool for discovery, unlike direct query tools like ask_pipeworx.

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

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

The description explicitly advises 'use this FIRST when you do not yet know what Pipeworx can do for you.' It explains the topic parameter to narrow focus, but doesn't explicitly state when not to use, though the intent is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by specifying the exact output (title and resource IDs) and the fact that it searches by keyword, which is not covered by 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 with no wasted words. The first sentence directly states the action and source, the second explains the output and links to a sibling tool. Excellent front-loading.

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

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

Given no output schema and two simple parameters, the description covers purpose, input, output, and connection to another tool. It could mention pagination or result limits, but it is largely complete for a search tool with good 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?

The input schema already provides descriptions for both parameters, achieving 100% coverage. The description adds example keywords ('parking', 'trees', 'budget'), which is slightly helpful but not essential. 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 it searches the City of Toronto open-data catalogue by keyword and returns dataset titles and queryable resource IDs. It distinguishes itself from siblings like toronto_query by specifying the output format and recommending use with that 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 explicitly suggests using the output with toronto_query, providing clear context for a common pipeline. It does not explicitly exclude scenarios, but the context is sufficient for an agent to understand when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds details on query capabilities (free-text, filters, sort, pagination) but doesn't cover rate limits or data freshness. Still adds value beyond annotations.

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

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

Concise, two sentences with clear structure: main purpose first, then parameter details and cross-references to siblings. No unnecessary wording.

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 key aspects: how to use (with resource id), parameters, how to find resource ids. Lacks description of return format, but acceptable given tool simplicity and 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 coverage is 100%, baseline 3. Description explains parameter semantics beyond schema descriptions (e.g., 'free-text q', 'exact-match filters', 'sort with field desc', max limit). Adds meaningful context.

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

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

The description clearly states the tool queries City of Toronto datastore resources by resource id, which is specific and distinguishes from siblings like toronto_datasets and toronto_recent.

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

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

Explicitly tells when to use this tool vs alternatives: 'Use toronto_datasets to find a resource id, or toronto_recent for the common ones.'

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 that results are sorted newest-first, that q is a CKAN full-text filter, and that no CKAN resource ID is needed. It does not cover rate limits or error cases, but the annotations already cover safety and idempotency, so the description provides meaningful additional 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 three sentences, front-loading the key purpose and usage preference, with no redundant words. Every sentence adds value.

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

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

For a simple read-only list tool with three parameters and no output schema, the description covers the purpose, datasets, order, filter, limit, and alternative tool comprehensively. No gaps are evident.

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. The tool description does not add new semantic information beyond what is already in the schema; it merely restates the filter and limit concepts. Baseline score of 3 is maintained.

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

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

The description clearly states that the tool returns recent records from a Toronto open dataset by friendly name, listing the two datasets (permits, business) and noting the newest-first order. This explicitly distinguishes it from the sibling tool toronto_query which offers full control.

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 'PREFER OVER WEB SEARCH for "Toronto building permits", "Toronto business licences"' and recommends toronto_query for full control, providing clear when-to-use and when-not-to-use guidance relative to alternatives.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds further behavioral context: ownership enforcement, deactivation instead of deletion, and the side effect that historical events stay accessible via 'recent_alerts'. 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?

Two concise sentences: the first states the core action, the second adds essential behavioral details. No redundant wording, every sentence serves a purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership constraint, lifecycle behavior (deactivation vs deletion), and link to related sibling tool ('recent_alerts'). It is self-contained and fully informative for an 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?

The only parameter 'id' has its description in the schema ('Subscription id (uuid) returned by subscribe') which already provides clear meaning. The description's mention 'by id' adds no new semantic information beyond the schema, so the baseline score of 3 is appropriate for 100% schema coverage.

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

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

The description uses the specific verb 'Cancel' and resource 'subscription by id', clearly indicating the action. It distinguishes this tool from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement, making the purpose unambiguous.

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

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

The description explicitly states that ownership is enforced and that only own subscriptions can be canceled, providing clear when-to-use and when-not-to-use guidance. It also explains that the row is deactivated (not deleted), so historical events remain available via 'recent_alerts', guiding users on alternative tools for viewing history.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral detail: returns verdict types, structured form, actual value with citation, percent delta, and explains that it replaces multiple sequential calls, providing context on efficiency and complexity. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose and usage. It is concise with no wasted sentences, though slightly longer than minimal. Every sentence contributes useful information about scope, return values, and efficiency gains.

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 (claim verification) and simple input schema (one parameter, no output schema), the description sufficiently covers purpose, usage scope, return values, and context. It provides enough detail for an agent to decide when to invoke this tool effectively.

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

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

Schema description coverage is 100% with the 'claim' parameter already having a clear description and examples. The tool description does not add additional parameter semantics beyond what the schema provides, so a 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's purpose as 'natural-language claim verification against authoritative sources' and provides explicit example phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools by stating it replaces 4-6 sequential calls, making its unique value clear.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported scope (company-financial claims) and data sources (SEC EDGAR + XBRL). While it doesn't explicitly list when not to use, the scope limitation provides adequate guidance.

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