Opendata Canada

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

Discloses internal routing to 1,423+ tools, argument filling, and citation URI output, adding context beyond annotations (readOnlyHint, openWorldHint, destructiveHint). 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?

Front-loaded with key guidance, structured with categories and examples. Slightly verbose but efficient for the breadth of information conveyed.

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?

Provides comprehensive context for a single-parameter tool: scope, sources, behavior, output, and usage examples. Lacks explicit mention of limitations or error handling, but acceptable given openWorldHint.

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 a generic parameter description; the tool description does not add additional semantics beyond examples of valid questions. Baseline is 3.

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

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

Clearly states the tool answers factual questions using structured data from many sources, explicitly distinguished from web search, with examples of data types. Distinguishes from siblings like 'search' by preferring this tool over web search.

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

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

Explicit guidance to prefer over web search for factual questions, with specific data type examples and question patterns ('what is', 'look up', etc.). Advises use even if web search could answer, providing clear when-to-use vs alternatives.

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

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

Annotations already declare readOnlyHint=true, so the tool is known to be safe. The description adds valuable behavioral context: it resolves the market, classifies the bet, fans out to relevant packs, and returns an evidence packet with a comparison. 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 the action, then input details, then process and use cases. Every sentence adds meaningful information without unnecessary fluff. It is appropriately sized for a complex tool.

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

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

Given the tool's complexity (multiple input types, classification, fan-out, output), the description covers all essential aspects: inputs, process, and output format (evidence packet + comparison). Despite no output schema, the description adequately describes the return value.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that 'market' can be a slug, URL, or question text, and explains the 'depth' parameter (quick vs thorough). This goes beyond the schema's basic descriptions.

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

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

The description precisely states the tool's action ('Research a Polymarket bet'), resource ('Pipeworx data'), and scope ('in one call'). It also distinguishes from siblings by positioning it as the core demo product that converts better than discovering packs oneself.

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 use cases ('should I bet on X?', 'what does the data say about this Polymarket market?') and implies when to use it. However, it does not explicitly mention when not to use it or point to alternative sibling tools like ask_pipeworx or entity_profile for other types of queries.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true; description adds data sources (SEC EDGAR/XBRL, FAERS, FDA) and return format (paired data + citation URIs). No contradiction.

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

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

Approximately 120 words, front-loaded with purpose and usage examples. Every sentence adds value; no redundancy or filler.

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

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

Despite no output schema, description explains what is returned (paired data + URIs). Covers both parameter types and data sources. Could mention output format consistency but not a gap.

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

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

Schema has 100% description coverage; description enriches both parameters by explaining the difference between 'company' and 'drug' with specific metrics pulled, and how to format values (tickers vs drug names).

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?

Uses specific verbs ('compare', 'side by side') and clearly names the resource types (companies, drugs). Distinguishes from sibling 'entity_profile' by focusing on multi-entity 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?

Explicitly states when to use via example user queries ('compare X and Y', 'X vs Y') and mentions it replaces 8-15 sequential calls. Lacks explicit 'when not to use' but context 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=true and destructiveHint=false, so the description is not required to restate the safety profile. It adds value by specifying 'Returns the top-N most relevant tools with names + descriptions', but does not discuss potential limitations (e.g., ranking model behavior, possible incompleteness). Overall, it adds useful context beyond annotations.

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

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

The description is two sentences long, with the first sentence delivering the core purpose concisely. The second sentence provides expanded context. While the list of examples is extensive, it is front-loaded and earns its place by clarifying scope. A slight reduction in examples could improve conciseness 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 moderate complexity (2 parameters, no output schema), the description covers the essential aspects: what it returns (top-N tools with descriptions), when to use it, and example queries. It does not detail the ranking algorithm or any pagination, but for a discovery tool with readOnlyHint, this is adequate.

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%, meaning both parameters (query, limit) are described in the schema. The description adds value by providing concrete query examples (e.g., 'analyze housing market trends') and implying the limit via 'top-N'. This helps an agent understand parameter usage better than schema alone.

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

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

The description clearly states 'Find tools by describing the data or task' and provides a comprehensive list of examples like 'SEC filings, financials, revenue, profit', making the purpose immediately clear. It distinguishes itself from sibling tools (e.g., search, validate_claim) by being a meta-tool for discovering other tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This provides clear when-to-use guidance and implies not to use when the specific tool is already known, effectively differentiating from siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it returns 'pipeworx:// citation URIs', details the data sources, and implies a compound response. It does not contradict annotations and provides transparency about the citation format.

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

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

The description is efficient: it starts with a single-sentence purpose, then use cases, then return content, then parameter guidance. Every sentence adds value, no fluff. It is well-structured and front-loaded.

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

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

Given the tool's complexity (returns multiple data types) and no output schema, the description adequately explains what is returned. It covers parameters fully. It could mention any limitations (e.g., pagination, max results), but overall it is complete enough 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?

Schema description coverage is 100%. The description adds examples ('AAPL', '0000320193') and reinforces the constraint that names are not supported. This adds practical guidance beyond the schema, meriting a 4.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It specifies the resources included (SEC filings, fundamentals, patents, news, LEI) and distinguishes from siblings by noting it replaces calling 10+ separate tools. It also contrasts with resolve_entity for name resolution.

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

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

Explicit when-to-use scenarios are given: when a user asks for company info like 'tell me about X', or when you'd otherwise need many calls. It also explicitly states when not to use: 'Names not supported — use resolve_entity first if you only have a name.' This provides clear guidance and alternative 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 provide destructiveHint=true, and the description's 'Delete' aligns. But the description adds no further behavioral context beyond the annotation. There is 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?

Two sentences, front-loaded with action, then usage context. No wasted words, every sentence carries 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 one-param tool with no output schema, the description covers core functionality well. It explains usage context but omits success/failure behavior. With destructiveHint already declared, it is mostly complete.

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

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

Schema coverage is 100% with 'Memory key to delete'. The description merely repeats 'by key' without adding extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It explicitly mentions sibling tools 'remember' and 'recall', distinguishing the tool's purpose from them.

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

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

The description gives explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also pairs with 'remember' and 'recall' as alternatives. However, it lacks explicit when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, but the description adds no behavioral context beyond those. No additional traits like pagination or rate limits are mentioned.

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 extremely concise but at the cost of completeness. It is too brief to be useful.

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 one parameter, no output schema, and minimal description, the tool definition is severely incomplete. The agent lacks critical context for correct invocation.

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

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

Schema coverage is 0% and the description does not explain the 'limit' parameter. The agent cannot infer its purpose from the description.

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

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

The description 'List themes.' is too brief and does not clearly state what the tool does. The name 'groups' is mismatched with 'themes', and it fails to distinguish from siblings like 'organizations' or 'search'.

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?

No guidance is provided on when to use this tool versus alternatives. The description lacks 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?

Annotations (readOnlyHint=true, destructiveHint=false) already convey that this tool is a safe read operation. The description adds no additional behavioral context such as pagination, filtering limits, or data freshness. While not contradictory, it falls short of enriching the agent's understanding 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?

At only two words, the description is as concise as possible. It front-loads the core action and resource, making it easy to scan. However, extreme terseness sacrifices valuable context that could be added without significant verbosity.

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

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

Given the absence of an output schema and the tool's simplicity, the description should clarify what an 'org' is and whether the list is exhaustive or paginated. It also fails to mention any ordering or defaults. The annotations mitigate some lack of context, but the description itself is incomplete for safe 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?

The schema has 0% coverage for the 'limit' parameter, and the description does not mention or explain it. The agent receives no insight into how 'limit' affects results, such as whether it caps the total count or applies per page. This is a critical omission for a tool with a parameter.

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

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

The description 'List orgs' clearly states the action (list) and resource (orgs), making the tool's purpose immediately understandable. However, it does not differentiate from the sibling tool 'groups', which could similarly list entities, missing an opportunity to clarify the distinction.

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 no guidance on when to use this tool versus alternatives like 'search' or 'groups'. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.

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 a read-only, non-destructive operation. The description adds no further behavioral context (e.g., return format, pagination, or data scope).

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?

Extremely concise and front-loaded. However, it omits potentially useful detail; the brevity sacrifices completeness.

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

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

No output schema exists, so the description should explain return values. It does not define what a 'dataset' is or what fields are returned, leaving 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?

Despite 0% schema description coverage, the description explicitly states the 'id' parameter can be an id or slug, adding valuable semantic context beyond the raw 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 'Dataset by id/slug' indicates the tool retrieves a dataset, but lacks a specific verb (e.g., 'get'). It clarifies the resource type beyond the name, but remains vague about the action.

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?

No guidance on when to use this tool versus siblings like 'search', 'entity_profile', or 'validate_claim'. The description does not contextualize its use case.

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

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

Discloses rate limit (5 per identifier per day), that it's free and doesn't count against quota, and that team reads digests daily. Annotations are minimal so description carries full burden and does well.

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

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

Two sentences plus rate limit/quote note. Purpose front-loaded, every sentence adds value. 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?

Covers all needed aspects: types, context, message format, rate limits, impact. No output schema needed for feedback 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 all parameters. Description adds overall usage context but no additional parameter-level details beyond schema.

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

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

Clearly states the verb 'tell' and resource 'Pipeworx team' and lists specific use cases (bug, feature, data_gap, praise). Distinguishes from siblings as the only feedback tool among many data retrieval 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 it for bugs, features, etc. Provides guidance on describing issues in terms of Pipeworx tools/packs. Missing explicit 'when not to use' but clear from context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral detail on the two modes and return format (ranked opportunities with trade direction). No contradictions or missing disclosures beyond annotations.

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

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

The description is succinct, well-structured, and front-loaded with the core purpose. Each sentence adds value without redundancy, efficiently covering purpose, modes, and output.

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

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

The description covers purpose, modes, and return format adequately. However, it does not specify whether the parameters are mutually exclusive or what happens if both are omitted. Given the tool has two optional parameters, this omission slightly reduces completeness.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds significant value by explaining the two modes, providing examples for each parameter, and clarifying their use cases beyond the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities by checking for monotonicity violations on Polymarket. It specifies two distinct modes (event and topic), contrasting with sibling tools like polymarket_edges. The verb 'find' and resource 'arbitrage opportunities' are precise.

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

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

The description provides clear guidance on when to use each mode, including an example (May≤June rule) for cross-event mode. However, it does not explicitly exclude other tools or mention when not to use this tool, though the mode explanations effectively serve as 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?

Annotations declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description adds significant behavioral details: it uses a V1 model with FRED and coinpaprika data, computes model probability per market, and ranks by edge magnitude. It also discloses the return structure (top N with trade direction), going well beyond the annotations.

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

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

The description is information-dense but clear, starting with the primary purpose and then explaining the mechanism. It could be slightly more concise by removing minor details (e.g., 'V1 covers crypto-price bets...'), but overall it is well-structured and front-loaded.

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

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

Despite no output schema, the description explains what is returned (top N ranked by edge magnitude with suggested trade direction). Annotations cover safety (readOnly), and the schema covers parameters. The description provides complete context about the model and data sources, making the tool's behavior and output fully understandable.

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

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

All three parameters are documented in the input schema with descriptions covering defaults and constraints (e.g., limit: 'Top N... Default 10, max 25'). The description does not add new semantic information beyond what the schema provides. With 100% schema coverage, baseline is 3.

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

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

The description explicitly states the tool's action: scanning high-volume Polymarket markets to find where Pipeworx data disagrees with market price. It describes the process (groups by asset, fetches price history, computes model probability, ranks by |edge|) and differentiates from siblings by focusing on Pipeworx data vs market price disagreement, addressing the 'what should I bet on today' question.

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 the tool is for discovering betting opportunities with high edge, saving users from manually browsing hundreds of markets. It implies when to use (to find mispriced markets) but does not explicitly state when not to use or contrast with alternatives like polymarket_arbitrage. However, the context is sufficient for most agents.

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

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

Description adds scoping detail (anonymous IP, BYO key hash, account ID) beyond annotations. Annotations already mark readOnlyHint=true, so no contradiction.

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

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

Three sentences, front-loaded with primary action, no redundant words. Every sentence contributes meaning.

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 one optional parameter and no output schema, description covers retrieval vs listing, scoping, and pairing. No gaps.

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

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

Schema describes 'key' parameter; description adds value by explaining that omitting it lists all keys. Enhances understanding beyond schema.

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

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

Description clearly states the tool retrieves values saved via 'remember' or lists keys when omitted. Distinguishes from sibling tools 'remember' and 'forget' by explicitly naming them as counterparts.

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

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

Provides explicit guidance on when to use (look up context stored earlier) and pairing with 'remember' and 'forget'. Could add when not to use, but still clear.

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

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

The description discloses that the tool fans out to multiple sources in parallel, describes the return structure (structured changes + total_changes count + citation URIs), and explains the 'since' parameter format. Annotations already declare readOnlyHint and non-destructive, and the description adds behavioral context beyond that.

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

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

The description is front-loaded with purpose and examples, and every sentence adds value. It is appropriately concise for the complexity, though it could be slightly more streamlined.

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 data sources, parallel execution, return format), the description covers all key aspects: purpose, when to use, parameter semantics, and return values. It is complete for an agent to invoke correctly without needing an 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% so baseline is 3. The description adds value by providing examples and clarifying that 'since' accepts ISO dates or relative shorthand, and that 'value' can be ticker or CIK. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the tool's purpose: 'What's new with a company in the last N days/months?' and provides specific example queries. It names the resources (SEC EDGAR, GDELT, USPTO) and distinguishes from siblings like 'entity_profile' by focusing on changes.

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

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

The description gives explicit example queries and states 'Use when a user asks...' It provides clear context for when to use the tool, but does not explicitly exclude other tools or provide alternatives, which would justify a 5.

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

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

Annotations already show non-readOnly and non-destructive. Description adds scope by identifier, persistence differences (authenticated vs anonymous), and 24-hour expiration. Missing potential overwrite behavior but still strong.

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

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

Four concise sentences, front-loaded with purpose, then usage, then details. No redundant information.

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

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

No output schema needed; description fully covers purpose, usage, lifetime, and pairing instructions. Complete for a simple key-value store.

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

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

Schema has 100% description coverage. Description only provides examples (e.g., 'key' as 'target_ticker'), adding minimal extra meaning. Baseline 3 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?

Clear verb 'save data' with specific usage examples (ticker, address, preference) and explicit mention of reusing across conversations/sessions. Distinguished from siblings 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') and pairs with recall and forget for complementary actions. No confusion with alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint, and the description aligns with that. The description adds behavioral context beyond annotations by mentioning returns of 'pipeworx:// citation URIs' and that it is a lookup operation with no side effects. 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 a single, well-structured paragraph. The first sentence states the core purpose, followed by usage context, examples, return value mention, and ordering advice. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description adequately explains return values (IDs plus citation URIs) and the types of IDs. It mentions the main ID systems (CIK, ticker, RxCUI, LEI). The examples provide concrete completeness. Some details about exact output structure could be added, but overall it is complete for a lookup 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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by providing examples that illustrate parameter usage (e.g., 'Apple' → multiple IDs, 'Ozempic' → RxCUI plus ingredient/brand), which clarifies acceptable values and output 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 verb 'look up' and the resource 'canonical/official identifier' for company or drug. It distinguishes from sibling tools by specifying that it returns IDs needed as input for other tools, and provides concrete examples (Apple → AAPL/CIK, Ozempic → RxCUI).

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

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

The description explicitly says when to use ('when a user mentions a name and you need...') and when to use it before other tools ('Use this BEFORE calling other tools that need official identifiers'). It also mentions alternatives by stating it 'replaces 2–3 lookup calls'.

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, and destructiveHint. The description adds no additional behavioral context such as required permissions, response format, or rate limits.

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

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

The description is a single sentence with no redundancy. However, it is overly concise at the expense of completeness, which is not an ideal tradeoff.

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

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

Given 4 parameters and no output schema, the description is critically incomplete. It does not explain search behavior, parameter usage, or return values, leaving the agent underspecified.

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

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

With 0% schema description coverage, the description fails to clarify any of the four parameters (fq, rows, query, start). The agent must infer meanings from parameter names alone, which is insufficient.

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 'CKAN package_search' specifies the resource (CKAN packages) but lacks an explicit action verb. It differentiates from siblings by mentioning a specific domain, but is vague for an agent unfamiliar with CKAN.

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?

No guidance on when to use this tool, prerequisites, or alternatives. The description does not mention any context or exclusions, leaving the agent without direction.

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

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

Annotations (readOnlyHint, openWorldHint, destructiveHint) are present and consistent. The description adds value by detailing the return format (verdict, structured form, citation, delta) and noting it replaces multiple sequential calls, enhancing transparency beyond annotations.

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

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

The description is concise (4-5 sentences), well-structured with purpose first, then usage, then scope, then output. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter, the description covers purpose, input, output, scope limitations, and even notes the version (v1). The absence of an output schema is compensated by the detailed return type description.

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

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

The input schema has one parameter (claim) with 100% description coverage. The tool description reinforces the parameter's meaning but does not add new semantic information beyond the schema's description, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Fact-check, verify, validate, or confirm/refute a natural-language factual claim or statement against authoritative sources.' It specifies the domain (company-financial claims) and gives concrete examples, distinguishing it from vague purposes.

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

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

The description explicitly tells when to use the tool ('Use when an agent needs to check whether something a user said is true') and provides example phrasings. However, it lacks explicit information on when not to use it or alternative tools for non-financial claims.

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