Figshare

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

Annotations provide basic safety (readOnlyHint=true, destructiveHint=false), but the description adds no behavioral context (e.g., error handling, response format, or side effects). Minimal transparency beyond structured fields.

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 at two words, but it lacks essential information. This is under-specification, not effective conciseness.

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, zero parameter descriptions, and a trivial description, the tool definition fails to provide complete 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 parameter descriptions coverage is 0%, and the description does not explain 'id' (required) or 'version' (optional). No semantic meaning is conveyed to the agent.

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 'Single article.' is a tautology restating the name 'article'. It fails to specify the action (e.g., get, fetch, retrieve) or the resource semantics, making it indistinguishable from a bare noun.

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 'articles' (plural) or 'article_files'. No context about prerequisites or alternative tools 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?

The description adds no behavioral context beyond the annotations. Annotations indicate readOnlyHint=true and destructiveHint=false, but the description does not explain what the tool returns or any side effects. The description is too vague to be helpful.

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 (three words), but it is under-specified rather than concise. It fails to convey essential information, so the brevity is detrimental.

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

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

The description is completely inadequate for a tool with two parameters and no output schema. It does not state what the tool returns, what action it performs, or how it relates to other tools. The absence of output schema further increases the need for description 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?

The input schema has 0% parameter description coverage. The description does not explain the 'id' or 'version' parameters, leaving their semantics entirely unclear. The tool may be about files, but the role of each parameter is not indicated.

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 'Files in an article.' is a noun phrase and does not specify an action (e.g., list, get, upload). It merely restates the tool name without clarifying the tool's purpose or distinguishing it from sibling tools like 'article' or 'articles'.

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 such as 'article' or 'articles'. The description lacks context about prerequisites, use cases, or when to avoid using the tool.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the read-only nature is clear. However, the description adds no additional behavioral context such as pagination, result size limits, or filtering behavior beyond what is implied by the schema.

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

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

At only two words, the description is excessively terse. While concise, it sacrifices necessary detail and structure. Every sentence should earn its place; here, the single sentence does not provide enough value.

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

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

Given the tool has 5 parameters, no output schema, and multiple sibling tools, the description fails to provide sufficient context for correct use. It lacks information on parameter relationships, result format, or how to navigate between siblings.

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 only 40% schema description coverage, the description should compensate by explaining parameter roles, especially for undocumented fields like 'page', 'query', and 'page_size'. It provides no such information, leaving the agent to guess from parameter 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?

The description states the verb 'Search' and resource 'articles', which clearly indicates the basic action and object. However, it is extremely brief and does not differentiate from the singular sibling 'article'. It is functional but lacks specificity.

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 like 'article' or other search-related tools. The description gives no context for appropriate usage or 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds that the tool routes to the right sub-tool, fills arguments, and returns a structured answer with citation URIs. This contextualizes the openWorldHint well. 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 front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and provides a comprehensive list of domains and examples. While it is relatively long, every sentence adds value; minor redundancy could be trimmed.

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

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

Given the complexity (2,353 tools, no output schema), the description effectively covers purpose, usage, examples, and expected output format (structured answer with citations). It gives the agent clear guidance on when and how to invoke this 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?

Only one parameter 'question' with a natural language description in the schema (100% coverage). The description does not add additional semantic detail about the parameter beyond what the schema provides, but the overall use-case descriptions compensate slightly. 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 defines the tool as a router to 2,353 tools across 559 sources for authoritative structured data, with specific examples of domains (SEC filings, FDA data, etc.) and query types. It distinguishes itself from web search by stating 'PREFER 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?

Explicitly provides when to use (factual questions about real-world entities, events, numbers) and when not to (instead of web search). Includes concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K' to guide the agent.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds behavioral context: it resolves the market, classifies the bet type, fans out to relevant data packs, and returns an evidence packet with comparison. This goes beyond annotations without contradicting them. No details on limitations or rate limits, but sufficient for an AI agent's decision-making.

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

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

The description is a single paragraph of about 7 sentences. It front-loads the core action but includes some marketing language ('This is the core demo product — agents that get bet-relevant context here convert better than ones that have to discover the packs themselves.') which adds noise. Could be trimmed to 4 sentences without losing essential information.

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

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

With no output schema, the description should clearly describe the return format. It mentions 'evidence packet plus a simple market-vs-model comparison' but does not specify structure, pagination, or format. For a tool with only 2 parameters and moderate complexity, this is adequate for basic understanding but not fully 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% (both parameters have descriptions). The description adds significant value by explaining the 'depth' parameter effect: 'quick = 2-3 evidence sources, thorough = full fan-out' (not in schema's description which only says 'quick = 2-3 evidence sources, thorough = full fan-out'). For 'market', it confirms the three valid input types (slug, URL, question text), expanding on schema's brief description.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug, URL, or question text) and outputs (evidence packet and comparison). It distinguishes from siblings by calling itself the 'core demo product' and stating that agents using it 'convert better than ones that have to discover the packs themselves.'

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

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

The description explicitly states when to use this tool: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?".' It does not provide explicit when-not-to-use guidance or name alternatives, but the context of being the core research tool implies precedence over siblings that might require manual pack discovery.

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 readOnlyHint and destructiveHint, but the description adds no behavioral details such as error handling or response format. No contradiction found.

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 (two words), but lacks front-loaded clarity. Not informative enough to be considered concise.

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

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

Given one parameter and no output schema, the description should clarify that this retrieves a single collection by ID. The current text is insufficient.

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 0%, and the description only says 'Single collection.' No explanation of the required 'id' parameter beyond its type.

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 'Single collection.' implies a collection resource but lacks an action verb (e.g., get, retrieve). It does not distinguish from sibling 'collections' beyond singular vs plural.

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 explicit guidance on when to use this tool versus alternatives like 'collections'. The context is implied but not stated.

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, but description adds no behavioral context beyond that minimal statement.

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 but under-specified; the single sentence does not provide sufficient 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, no explanation of search behavior, pagination, or result format. Inadequate for a tool with multiple parameters.

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

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

Schema coverage is 0%, and description does not explain any of the three parameters (page, query, page_size). Description fails to compensate.

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 'Search collections.' provides a verb and resource but is vague. It doesn't specify what collections are or how this differs from sibling tools like 'collection' or 'articles'.

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. No context on prerequisites or use cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds useful behavioral context: data sources (SEC EDGAR/XBRL, FAERS), return format (paired data + citation URIs), and efficiency claims (replaces many calls).

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 purpose, no unnecessary words. Well-structured and easy to parse.

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

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

Covers usage context, parameter details, return values (paired data and citations), and effectively compensates for missing output schema. Complete and self-contained.

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

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

Schema already describes both parameters fully (100% coverage). Description adds value by explaining what each entity type retrieves and providing example formats for values (tickers for companies, 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?

Clearly states the tool compares 2-5 companies or drugs side-by-side. Uses specific verbs and resources, and distinguishes from siblings by noting it replaces 8-15 sequential agent 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?

Explicitly lists example user queries that trigger this tool (compare X and Y, vs, stack up, which is bigger) and differentiates between company and drug types. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds that it returns 'top-N most relevant tools with names + descriptions,' providing the return behavior without contradicting annotations.

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

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

The description is front-loaded with the primary action and then specifies use cases and behavior. While slightly verbose, every sentence adds value, and the structure is logical.

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

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

Given the tool's simplicity (no output schema, no nested objects), the description covers the core behavior: returns tool names and descriptions. It adequately informs an agent without missing critical details.

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 examples for 'query' (e.g., 'analyze housing market trends') and clarifies limit defaults (20) and max (50), indicating search-like behavior beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (e.g., SEC filings, financials) and distinguishes from sibling tools by positioning itself as a discovery tool to find the right tool among many.

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

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

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 context about returned data (citation URIs) and scope, but could mention that 'everything' is limited to the listed categories. 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?

Two sentences, front-loaded with purpose, followed by usage examples and a clear list of returned data. No redundant or filler content.

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

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

Despite no output schema, the description enumerates all major return categories (SEC filings, fundamentals, patents, news, LEI) and mentions citation format. For a complex multi-source tool, this is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%. The description adds actionable guidance beyond the schema: it notes that 'type' only supports 'company' (already in enum) and explains that 'value' requires ticker or CIK, with an explicit alternative (resolve_entity) for 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?

The description starts with a specific verb-resource pair ('Get everything about a company') and lists multiple data sources (SEC filings, fundamentals, patents, news, LEI). It explicitly differentiates from siblings by noting it replaces 10+ pack tool 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 when-to-use examples are given (e.g., 'tell me about X', 'brief me on Tesla'). It clarifies input requirements (ticker or zero-padded CIK) and directs users to resolve_entity for names, preventing incorrect invocations.

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 destructiveHint=true. Description adds context on why to delete (stale data, task completion, sensitive data), enhancing transparency 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?

Two efficient sentences with no wasted words, front-loading the operation and then conditions.

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 simple tool with one parameter and annotations, the description is complete and provides sufficient context for correct usage.

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

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

Input schema has 100% coverage and description mentions 'by key', but no additional parameter semantics beyond what schema provides. 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 action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes the tool from siblings like 'remember' and 'recall' by its delete function.

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

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

Provides explicit when-to-use conditions ('context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with siblings 'remember' and 'recall'.

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, the description discloses rate limits (5 per identifier per day), cost (free), quota impact (none), and how the feedback is used (team reads digests daily, signals affect roadmap). No contradiction with annotations.

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

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

The description is somewhat lengthy but every sentence adds value. It is well-structured: purpose first, then usage, then behavioral notes. Could be slightly tighter, but still very effective.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers everything: purpose, when to use, how to use, constraints, and semantics. It is fully complete for an AI agent to invoke correctly.

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

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

The description adds significant meaning beyond the input schema: it explains the enum values in detail, gives guidance on writing the message (be specific, don't paste end-user prompt), and clarifies the context parameter's role. Schema coverage is 100%, but the description enriches it.

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

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

The description clearly states that the tool is for sending feedback about bugs, features, data gaps, or praise to the Pipeworx team. It uses specific verbs and nouns, and distinguishes itself from sibling tools which are all 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?

The description explicitly tells when to use the tool: when a tool returns wrong/stale data (bug), when a desired tool is missing (feature/data_gap), or for praise. It also mentions that it's free and doesn't count against quota, 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 declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context about searching and checking monotonicity, and mentions that it returns ranked opportunities with reasoning. It does not contradict annotations and provides useful behavioral detail beyond the safety profile.

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

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

The description is well-structured with clear mode labels and concise explanations. Every sentence adds necessary context without redundancy. At ~120 words, it is appropriately sized and front-loaded with the core purpose.

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

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

Despite no output schema, the description explains the return format (ranked opportunities with reasoning) and the rationale for cross-event mode. It covers the two modes sufficiently, though it assumes familiarity with monotonicity concepts. Overall, it is complete enough for an agent to decide when to use this tool and what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., event slug 'when-will-bitcoin-hit-150k' and topic 'Strait of Hormuz traffic returns to normal') and clarifying that the topic mode involves searching across events, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations. It distinguishes two modes (event and topic) with explicit examples, and explains why cross-event mode catches cases single-event mode misses. This provides a specific verb-plus-resource definition that differentiates from siblings like polymarket_edges.

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

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

The description gives explicit when-to-use guidance by outlining two modes and their appropriate inputs. It explains that cross-event mode is needed when Polymarket splits cutoffs into separate events, which single-event mode would miss, thereby directing the agent to the right mode.

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

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

The description goes beyond annotations by detailing the algorithm: groups by asset, fetches price history once, computes model probability, ranks by edge, and returns top N with suggested direction. It also discloses data sources (FRED, coinpaprika) and model type (lognormal). Annotations (readOnlyHint, openWorldHint) are consistent and add 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 front-loaded with the core purpose in the first sentence. It is somewhat verbose but packs essential details (data sources, model, grouping logic) efficiently. Could be slightly shorter, but still well-structured.

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

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

Given the absence of an output schema, the description sufficiently explains return values (ranked edges with suggested direction). It also sets expectations with 'V1 covers crypto-price bets' and includes algorithmic details. The annotations provide safety cues. Overall, it is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description does not add additional meaning beyond the schema; it merely restates defaults (e.g., 'Default 10, max 25'). No extra semantics are provided, but the schema is sufficient.

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: scan high-volume Polymarket markets and return those where Pipeworx data disagrees most with market price. It is specific about the resource (Polymarket markets) and action (scanning, computing edges, ranking). It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 an explicit use case: 'Built for the 'what should I bet on today' question — agents/users discover opportunities without paging through hundreds of markets by hand.' This provides clear context. It does not explicitly state when not to use it or mention alternatives, but the purpose is well-defined.

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. The description adds scoping details (identifier-based) and the effect of omitting the key. 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?

Two sentences, each earning its place. First sentence states function, second gives usage guidance. No fluff.

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

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

For a simple read tool with good annotations and single optional parameter, the description covers purpose, usage, and pairing. Absence of output schema doesn't harm 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?

Schema coverage is 100% with parameter description. The description adds key behavior: 'omit the key argument to list all keys', which is not in the schema. This 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 verb-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from sibling tools (remember and forget) by name and purpose.

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 concrete use cases ('the user's target ticker, an address, prior research notes') and mentions scoping and pairing with remember/forget. It lacks explicit when-not-to-use but is otherwise strong.

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) already declare non-destructive read-only behavior. The description adds beyond annotations: parallel fan-out to three sources, return structure (changes, count, URIs), and acceptable date formats. 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?

A single paragraph that efficiently combines purpose, examples, sources, parameter guidance, and output description. No wasted sentences, though slightly dense for quick scanning.

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

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

Given the complexity (multiple sources, no output schema), the description adequately covers return values (structured changes, count, URIs) and parameter usage. Could mention rate limits or auth needs, but annotations cover safety.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining the `since` format (ISO vs relative) and suggesting defaults ("30d"), and clarifies `value` as ticker or CIK. This goes beyond the schema alone.

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

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

The description clearly states it retrieves recent changes for a company, with specific examples like "what's happening with X?" and details on data sources (SEC EDGAR, GDELT, USPTO). It distinguishes itself from siblings like entity_profile (static profile) and articles (full text) by focusing on change detection.

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 query patterns that trigger this tool, such as "any updates on Y?" or "brief me on what happened with Microsoft this quarter." It implies when to use but does not explicitly list when not to use or name alternatives, though the sibling context clarifies choices.

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 persistence behavior (authenticated vs anonymous), scoping by identifier, and the read/write nature, adding significant value beyond annotations.

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

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

Four sentences, each earning its place: purpose, usage, scoping, and sibling links. Front-loaded with action and resource.

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 two-parameter tool, the description covers purpose, usage, behavior, parameter meaning, and related tools. No gaps given the absence of 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%, but the description adds meaning by explaining key-value pair nature and providing examples of keys and values, going 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 saves data for reuse across conversations/sessions, with specific verb and resource, and implicitly distinguishes 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?

Provides explicit when-to-use guidance with examples (e.g., resolved ticker, user preference) and mentions pairing with recall/forget, 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool returns IDs and citation URIs, but discloses no additional behavioral traits such as rate limits or authentication needs, so it adds moderate value beyond annotations.

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

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

The description is a single dense paragraph of three sentences that front-loads the core purpose and uses. Each sentence contributes meaningful information 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 simplicity (2 params, no output schema) and the presence of annotations, the description adequately covers the tool's function, workflow role, and expected outputs (IDs + URIs), though it could specify the response structure more precisely.

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 have descriptions in the schema (100% coverage). The description enriches these by providing real-world examples (e.g., 'Apple' → AAPL) and explaining how the type and value interplay, adding 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 clearly states the tool resolves names to official identifiers (CIK, ticker, RxCUI, LEI) for companies and drugs, distinguishing it from siblings like entity_profile and validate_claim by positioning it as a prerequisite step.

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

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

The description specifies when to use (when you need an identifier for other tools) and gives concrete examples. It does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already provide read-only, non-destructive, and open-world hints. The description adds: the tool returns a verdict with citation, supports only v1 financial claims, and replaces multiple steps. This adds useful behavioral context beyond annotations, though it does not detail rate limits or authentication.

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

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

The description is well-structured with front-loaded purpose and usage, followed by scope and return details. It is somewhat verbose with synonym lists, but every sentence adds value. Efficient for its content.

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

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

With no output schema, the description adequately describes the return verdicts and citation. It explains the tool's scope and limitations. However, it could be more explicit about handling out-of-domain claims or error conditions. Adequate for agent decision-making.

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 already describes the 'claim' parameter with examples. The description repeats the nature of the claim and adds domain limitation (company-financial), but does not provide significant additional semantic nuance. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: fact-check, verify, validate, or confirm/refute factual claims. It provides specific verbs and resources (SEC EDGAR + XBRL for company-financial claims) and distinguishes itself from siblings by focusing on claim verification rather than entity profiling or comparison.

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

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

The description explicitly says 'Use when an agent needs to check whether something a user said is true' and gives example queries. It does not explicitly state when not to use, but the domain restriction (company-financial claims) implies exclusivity. Clear context, but lacks explicit exclusions.

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