Data Cityofchicago

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe and non-destructive. The description adds behavioral context by explaining that the tool routes questions internally and returns structured answers with pipeworx:// citation URIs, which is valuable beyond annotations.

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

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

The description is well-structured with the key directive 'PREFER OVER WEB SEARCH' first, followed by examples and use cases. It is slightly long but each sentence earns its place by adding useful context. Could be trimmed without losing meaning, but it's not verbose.

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

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

Given the tool has one parameter and annotations covering safety and openness, the description is complete. It explains what the tool does, when to use it, and what output to expect (structured answer with citations). No output schema exists, but the description compensates by describing the return 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 description coverage is 100% for the single parameter 'question', which already describes it as natural language. The description does not add significant new semantic meaning beyond the schema, but it reinforces that the question can be any factual query. 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 that ask_pipeworx routes questions to 1,423+ tools across 392+ sources and returns structured answers with citations. It explicitly distinguishes itself from web search by saying 'PREFER OVER WEB SEARCH' and lists extensive domains, making its purpose highly specific and differentiating it from sibling tools.

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

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

The description provides explicit guidance on when to use the tool: for factual questions requiring authoritative structured data, even if web search could answer. It gives examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and phrases like 'use whenever the user asks...' clearly indicate context. No alternative tools are named, but the instruction is clear enough to prevent misuse.

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

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

Describes internal workflow: resolves the market, classifies the bet (lists types), fans out to packs based on classification, and returns an evidence packet plus comparison. This adds value beyond annotations (readOnlyHint, openWorldHint) which only indicate safety and unpredictability.

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 dense paragraph containing all necessary information. No redundant sentences, but could be structured (e.g., bullets) for easier parsing. Efficient but not optimally 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?

Covers purpose, inputs, internal logic, and output (evidence packet + comparison). Lacks details on error handling or output structure, but no output schema exists. Adequate given complexity and sibling 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?

Adds meaning beyond schema: explains 'market' accepts slug, URL, or question text, and 'depth' differentiates quick vs thorough with default. Schema coverage is 100%, but description provides crucial context on 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 clearly states the tool's purpose: 'Research a Polymarket bet... pulling the relevant Pipeworx data...' and distinguishes it from sibling tools by describing it as a one-call solution that fans out to appropriate data packs, unlike manually discovering packs.

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 usage examples: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?".' Input types (slug, URL, question text) are given. However, no explicit when-not-to-use guidance is provided, though it's 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 indicate read-only and non-destructive behavior. The description adds valuable context about data sources (SEC EDGAR, FAERS, etc.) and return format (paired data with citation URIs), enhancing transparency without 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 concise (138 words), well-structured with front-loaded purpose, and every sentence adds value. It efficiently conveys type-specific behavior and use cases 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?

The description covers purpose, usage, data sources, and output format. Without an output schema, it mentions paired data and citation URIs, which is sufficient for an agent. Minor gap: could be more explicit about return structure.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description adds extra context, such as examples of values for each type (tickers vs drug names) and limits (2-5), surpassing 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 compares 2-5 companies or drugs side by side, using specific verbs and resources. It distinguishes itself from siblings like entity_profile by focusing on comparisons instead of single entity deep dives.

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 when to use the tool with example user queries. It details the data pulled for each type but does not mention alternative tools or when not to use, which is acceptable due to clear context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context such as pagination behavior, result ordering, or rate limits, which are expected for a search tool.

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 at one sentence, but it is under-specified. It earns its place by stating the basic purpose, but more detail is warranted given the tool's complexity.

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

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

Given three parameters and no output schema, the description is severely incomplete. It does not explain how to use parameters, what results contain, or any search behaviors, leaving the agent without critical 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?

With 0% schema description coverage and three undocumented parameters (limit, query, offset), the description fails to explain what these parameters do. The brief description does not compensate for the low coverage.

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

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

The description clearly states the action ('Search') and the resource ('dataset catalogue'), but does not differentiate from sibling tools like 'query' or 'bet_research', which might also involve searching. A more specific scope would improve clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, search strategies, or comparisons to siblings such as 'query' or 'entity_profile'.

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

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

Annotations indicate read-only, non-destructive. Description reinforces it returns top-N relevant tools with names and descriptions. No contradictions; discloses behavioral 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?

Two sentences, front-loaded with purpose, includes examples, and ends with usage advice. No unnecessary words.

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

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

No output schema, but description explains return content (names+descriptions). Enough for a simple discovery tool; 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 covers both parameters with descriptions. Description adds meaning about output format (names+descriptions) and usage advice. With 100% schema coverage, baseline 3, but extra context justifies a 4.

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

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

The description clearly states the tool finds tools by describing data or task, with specific examples like SEC filings, financials, FDA drugs, etc. It distinguishes from siblings as a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists contexts like browsing, searching, looking up, discovering tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint, destructiveHint), the description adds detailed behavioral traits: returns SEC filings, financials, patents, news, LEI with citation URIs. No contradictions.

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

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

Single paragraph front-loads purpose and then provides necessary details. Every sentence adds value with no fluff.

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

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

Despite no output schema, the description fully explains what the tool returns (filings, fundamentals, patents, news, LEI) and parameter constraints, making it 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% with descriptions. The description adds extra usage guidance (only company type, ticker/CIK format, necessity of resolve_entity for names), improving clarity 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?

The description clearly states 'Get everything about a company in one call' with specific verb and resource. It lists use cases and distinguishes from siblings by noting it replaces calling 10+ other pack 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 when to use with example queries like 'tell me about X'. Also advises to use resolve_entity first if only a name is available, providing clear context.

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

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

Annotations already mark destructiveHint: true; description adds context about why deletion is needed (sensitive data, staleness), reinforcing the destructive nature without contradiction.

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

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

Three sentences, no filler. First sentence immediately states the action, followed by usage guidance and pairing hints.

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 delete tool with one parameter, description covers purpose, usage, and sibling context. Could mention return value or error cases, but overall 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 has 100% coverage for the single 'key' parameter. Description does not add extra meaning beyond that, so baseline score of 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. Siblings like 'remember' and 'recall' make the purpose distinct.

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

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

Provides explicit scenarios for use (stale context, done task, sensitive data) and mentions pairing with siblings, but does not explicitly 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 provide a readOnlyHint and destructiveHint=false, indicating safe read-only access. However, the description adds no additional behavioral context, such as what permissions are needed or what the response format looks like.

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 vague phrase. It is under-specified rather than concise, lacking essential information for an agent to use the tool correctly.

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, one required parameter, and a vague description, the tool definition is incomplete. The agent lacks sufficient context to invoke this tool appropriately.

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 must compensate, but it does not explain the 'resource_id' parameter at all. The description adds no meaning 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 'Resource metadata.' is extremely vague; it does not specify what action is performed on the resource or what kind of metadata is returned. It fails to distinguish from sibling tools like 'entity_profile' or 'datasets'.

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

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

No guidance on when to use this tool versus alternatives. For example, it does not explain how this differs from 'entity_profile' or when to prefer one over the other.

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 limits (5 per identifier per day) and quota impact (free, doesn't count against tool-call quota), adding value beyond annotations. 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 purpose, each sentence adds value. Slightly verbose but still efficient; could be trimmed slightly without losing 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?

Given the tool's complexity (3 params, no output schema), the description covers all necessary aspects: usage, when to use, message tips, rate limits, and quota impact.

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

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

Schema coverage is 100%, and the description adds extra guidance on message specificity and length, improving parameter 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 is for providing feedback to the Pipeworx team, listing specific types (bug, feature, data_gap, praise) and distinguishing it from sibling tools that are query/research oriented.

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 each feedback type and includes a negative instruction ('don't paste the end-user's prompt'), providing clear guidance on 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 explains that the tool searches Polymarket, checks monotonicity, and returns ranked opportunities with reasoning. Annotations declare readOnlyHint and openWorldHint, which align with the described behavior. It does not mention rate limits or auth, but is sufficiently transparent for its 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?

The description is concise and well-organized, presenting the purpose, two modes, use-case rationale, and return value in a single paragraph. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (two modes, cross-event searching) and no output schema, the description covers the essential aspects: what it does, how to invoke each mode, and what it returns. It could elaborate on the monotonicity concept, but the current level is adequate 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 coverage is 100%, but the description adds significant context beyond parameter names: it explains the two modes, provides examples, and clarifies the cross-event logic. This helps an agent understand when to use which parameter.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations. It specifies two distinct modes (event and topic) and distinguishes itself from potential siblings by explaining the cross-event use case, which other tools might not cover.

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, with examples and a rationale for the cross-event mode. However, it does not explicitly state when not to use this tool or contrast it with alternatives like polymarket_edges, which would further enhance clarity.

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

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

Annotations indicate read-only, non-destructive, open-world. The description adds significant behavioral context: scanning process, grouping by asset, computing model probability, ranking by edge, and returning trade direction. 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 somewhat long but front-loaded with the core purpose. Every sentence adds value, explaining the algorithm and output. 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 the complexity (model, multiple steps, output), the description covers the process, constraints (V1, crypto-price bets), input parameters, and what is returned (top N with trade direction). No output schema needed as description clarifies return shape.

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 three parameters (limit, window, min_edge_pp). The description echoes these concepts but adds no new semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those with largest disagreement, specifying the resource and action. It also mentions the ranking by edge magnitude and the intended question 'what should I bet on today,' distinguishing it 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?

The description explicitly states the tool is built for the 'what should I bet on today' question and that it saves time paging through markets. It provides clear context for when to use, though it does not list when not to use or explicitly name alternatives.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds no behavioral context beyond stating it's a query, which is redundant 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 extremely short (two words), but this is under-specification rather than conciseness. It fails to provide necessary detail, making it nearly useless.

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 7 parameters, no output schema, and no parameter descriptions, the description is completely inadequate for an agent to understand how to invoke or interpret results.

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 7 parameters with 0% description coverage. The description does not explain any parameters, such as the meaning of 'select', 'where', 'order', etc., or how to construct a SoQL query.

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 'SoQL query' indicates the tool performs a query using Socrata Query Language, but does not specify what resource it queries (e.g., datasets, metadata). It is vague and does not distinguish from sibling tools like 'datasets'.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools like 'datasets' or 'validate_claim' have different purposes, but no differentiation is provided.

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

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

Annotations already indicate read-only and non-destructive; description adds scoping behavior and listing functionality, providing extra useful 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?

Two sentences, no wasted words, purpose immediately 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?

Fully covers purpose, usage, scope, and sibling interactions for a simple one-parameter read 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 parameter fully; description clarifies that omitting key lists all keys, adding 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 the verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings remember and forget.

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

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

Explicitly says when to use (to look up stored context) and provides context of scoping and pairing with remember/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 indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details: parallel fan-out to three sources and the return format (structured changes + count + 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 concise (4 sentences) and front-loaded with the core question. Each sentence adds value: usage examples, technical details, and return type. No redundant or vague 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?

Given three simple parameters and no output schema, the description adequately covers input formats, sources, and output summary. It could detail the structure of 'changes' but for a monitoring tool this is sufficient. Minor gap but overall complete.

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

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

Schema coverage is 100%, but the description adds significant semantic context: 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y'), suggests '30d' or '1m' for monitoring, and clarifies 'value' accepts ticker or zero-padded CIK. This greatly aids correct 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 clearly states the tool's purpose: 'What's new with a company in the last N days/months?' It provides multiple example queries and outlines the three data sources (SEC EDGAR, GDELT, USPTO). This distinguishes it from sibling tools like entity_profile, which provides static company information.

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 includes explicit usage examples ('when a user asks...') and covers temporal qualifiers like 'this quarter' or 'this month'. It implies monitoring use cases but does not explicitly name alternative tools or state when not to use it. Clear context but lacks exclusions.

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

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

Annotations already indicate it is not readOnly, not destructive, and not openWorld. The description adds useful behavioral details: scoping by identifier, persistent vs. anonymous session retention (24 hours), and pairing with other tools. 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 well-structured sentences with front-loaded purpose. Every sentence adds value: purpose, usage guidance, and behavioral details. No wasted words.

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

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

The description covers purpose, usage, behavior, and syntax. It pairs well with sibling tools and explains persistence. Without an output schema, it could briefly mention the return value (e.g., confirmation), but overall it is sufficient for a simple store 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 parameter descriptions in the schema. The description adds examples for keys and values but does not significantly enhance the semantic understanding 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 tool's purpose with a specific verb ('Save') and resource ('data to reuse later'). It distinguishes from sibling tools like 'forget' and 'recall' by mentioning them explicitly, making the purpose unmistakable.

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

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

The description explicitly says when to use this tool ('when you discover something worth carrying forward, so you don't have to look it up again') and suggests pairing with recall and forget. It lacks explicit when-not-to-use guidelines but provides clear context.

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

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

Annotations already mark it as read-only and non-destructive. Description adds valuable behavioral context: returns multiple ID systems and pipeworx:// citation URIs, and can resolve both company and drug entities.

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. Every sentence adds information: what it does, when to use, examples, and workflow position.

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 good annotations and full schema coverage, description fully covers purpose, usage, parameters, and return content (IDs + citations). No output schema needed—return info is sufficiently described.

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

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

Schema has 100% description coverage. Description enriches both parameters: explains 'type' enum values and gives concrete examples for 'value' (e.g., ticker, CIK, or name for company; brand/generic for drug).

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 resolves names to canonical identifiers (CIK, ticker, RxCUI, LEI) for companies and drugs. It distinguishes itself by noting it replaces 2–3 separate lookups and should be used before other tools requiring official IDs.

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

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

Explicitly says when to use: when a user mentions a name and you need an official identifier. Also instructs to call this BEFORE other tools that need these IDs. Provides examples for both entity types.

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 detail beyond annotations: returns verdict types, extraction, citation, percent delta. Annotations already indicate read-only, non-destructive; description reinforces and enriches with output specifics.

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

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

Four sentences, front-loaded with purpose and usage, no extraneous words. Efficient and structured.

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

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

For a single-parameter tool without output schema, description covers purpose, usage, scope, and output completely. States limitations (v1, US companies, financial).

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

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

Schema coverage 100% for 'claim'; description adds examples and clarifies it's natural-language. Adds value beyond schema definition.

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 tool validates factual claims, specifies it handles company-financial claims via SEC EDGAR+XBRL, and distinguishes from siblings by replacing multiple sequential calls.

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

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

Explicit usage guidance: 'Use when an agent needs to check whether something a user said is true' with examples. Does not exclude alternatives but provides clear context.

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