Hagstova Fo

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: the default model is free, Anthropic probing requires a BYO key with direct payment, and it outlines the return structure (per-model + combined view). No contradictions.

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

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

The description is three concise sentences: the first states the core function, the second adds key parameter details, and the third lists use cases. No redundancy or unnecessary words.

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

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

For a tool with no output schema, the description adequately covers the return shape (per-model fields and combined view) and the score range (0-100). All four parameters are explained in context, making the tool easy to use without additional documentation.

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 significant value by explaining the default model, the purpose of '_apiKey' and 'models' parameter behavior (omit for default), and the context parameter's disambiguation role. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for entity visibility and returns a score, with a specific verb 'probe' and resource. It distinguishes itself among sibling tools through its unique 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 clear usage context for AI-marketing audits, pre-launch brand checks, and competitive monitoring. However, it does not explicitly mention when not to use this tool or contrast with similar siblings like 'scan_competitor_ai_presence'.

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 reveals key behaviors beyond annotations: it routes questions to one of 3,547 tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. Annotations already indicate read-only, idempotent, open-world, and the description adds substantial context about how the tool operates internally.

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

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

The description is front-loaded with a strong preference statement, then concisely lists data types, explains the routing mechanism, gives query patterns, and provides examples. Every sentence contributes valuable information; no fluff or repetition.

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 as a meta-routing tool, the description is remarkably complete. It covers what questions are suitable, how the tool works (routing, argument filling, citations), and provides examples. No output schema exists, but the description sufficiently explains what to expect (structured answer with URIs).

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description only says 'Your question or request in natural language' and mentions aliases, which largely duplicates the schema. Baseline of 3 is appropriate as the schema already provides good meaning, and the description adds minimal extra value.

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

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

The description explicitly states the tool answers factual questions about current/historical data from authoritative sources with citations. It distinguishes itself from web search by being preferred for structured data, and gives numerous examples like SEC filings, FDA data, etc. This clearly communicates the tool's purpose and scope.

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: 'PREFER OVER WEB SEARCH' for specific types of questions. It lists query patterns ('what is', 'look up', 'find', etc.) and examples. It even says 'even if web search could also answer it.' This tells the agent exactly when to use this tool over 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?

The description provides extensive behavioral details beyond annotations: resolver contract with match confidence levels, parent_event extractor, news fields with fallback handling, safety mechanisms for low-confidence/closed markets, and warnings about wide spreads. No contradiction with annotations (readOnlyHint=true, etc.).

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

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

The description is long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose in the first sentence. While verbose, it efficiently packs dense information for a complex tool.

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

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

Given three parameters and no output schema, the description thoroughly explains the output structure (result.market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and resolver behavior. 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 coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description adds minimal extra meaning beyond what the schema already provides (e.g., examples for market, enum for depth). 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 the tool researches Polymarket bets by pulling Pipeworx data in one call, specifying input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on deep research for a single bet.

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 to use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear usage context. However, it does not explicitly mention when not to use it or compare directly to sibling tools, though the examples implicitly differentiate.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds rich behavioral details: for companies it pulls 10-K revenue/net income/cash/debt, handles off-calendar fiscal years; for drugs it pulls FAERS counts, FDA approvals, trial counts; results sorted by primary metric; returns paired data 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?

The description is compact for its content, front-loaded with trigger phrases, and every sentence provides distinct value. Could be slightly more structured, but overall efficient.

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

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

Despite no output schema, the description clearly explains return format (paired data + URIs) and data types. Combined with schema and annotations, it fully covers what an agent needs 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?

Schema coverage is 100%, but the description adds value by explaining the meaning of each type ('company' pulls financials, 'drug' pulls safety data) and providing concrete examples for values. This enriches the schema's basic descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases. It explicitly distinguishes from sequential single-pack lookups, which are likely done by sibling tools like entity_profile.

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

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

Description provides explicit when-to-use cues (user says 'compare X and Y', etc.) and advises preference over sequential lookups. It lacks explicit when-not-to-use scenarios, but the guidance is strong and 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 declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining that results are 'ready to call directly, no second schema lookup needed', which enhances understanding of the tool's immediate usability. No contradictions with annotations.

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

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

The description is sufficiently concise and front-loaded with the purpose, followed by examples and usage guidance. Each sentence contributes to clarity, though it could be slightly tightened without losing information.

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

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

Given no output schema, the description adequately explains the return (names, descriptions, schemas, ready-to-call). It covers the input (natural language query) and the limit parameter, providing a complete picture for a discovery 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% and the description does not add substantial meaning beyond the schema's parameter descriptions. It mentions curated examples which are already in the schema. Minimal added semantic value.

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

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

The description clearly states the primary action ('Find tools by describing the data or task') and provides concrete examples of domains (SEC filings, financials, etc.), effectively distinguishing it from sibling tools like query_table or entity_profile which focus on specific data retrieval.

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

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

The description explicitly instructs to 'Call this FIRST when you have many tools available and want to see the option set', providing clear guidance on when to use this tool versus alternatives. It also lists many example queries to help the agent understand applicability.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: how it fans out across sources, the specific return data (cik, recent_filings with URIs, fundamentals sorted by period_end, patents with a soft-fail note, news via GDELT→GNews fallback, LEI), and the input format requirements. No contradictions with annotations.

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

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

The description is well-structured, starting with a clear, example-rich summary of the tool's purpose and primary use case. It then details the supported inputs, data sources, and return fields. While it is relatively long, every sentence adds value, covering limitations, fallbacks, and prerequisites. The information is front-loaded, allowing agents to quickly grasp the core function.

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

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

Despite lacking an output schema, the description thoroughly explains the return data structure and sources. It addresses edge cases (patent API sunset, news fallback), limitations (names not supported, only US public companies), and provides cross-references to sibling tools (resolve_entity). For a complex tool with multiple data sources and fallbacks, the description is remarkably complete and actionable.

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% (both 'type' and 'value' have descriptions). The description reinforces these with concrete examples ('Pass ticker 'AAPL' or zero-padded CIK '0000320193'') and clarifies exclusion ('names not supported'). While the schema already documents the parameters, the description adds practical usage context and example values, making it more helpful.

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: 'full cross-source profile of a US public company in ONE parallel call.' It lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It also distinguishes itself from chaining multiple single-purpose lookups, and references the sibling 'resolve_entity' for name resolution, providing clear differentiation.

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

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

The description explicitly advises when to use the tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when NOT to use it directly: 'names not supported (use resolve_entity first if you only have a name).' This provides clear, actionable guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale context, but doesn't add significant behavioral details beyond annotations.

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

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

Two sentences, front-loaded with the action, and no wasted words. Efficient and to the point.

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

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

With one required parameter and simple behavior, the description covers all necessary aspects. It mentions pairing with siblings, which is helpful. No output schema needed.

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

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

Schema coverage is 100% and the parameter 'key' has a clear description. The description adds no extra semantic meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes from siblings by explicitly mentioning 'remember and recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with 'remember and recall', providing clear context and alternatives.

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

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

Annotations (readOnly, openWorld, idempotent, non-destructive) indicate safety. Description adds that it fetches the page, extracts title/description/links, and outputs standard llms.txt markdown. No contradictions; behavioral details are appropriate.

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 main purpose. Each sentence is valuable and no redundant information. Highly 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, usage, and basic behavior. Could mention error handling or output format details, but given the simplicity and good annotations, it's largely complete. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'Full URL' and 'Maximum number of link entries' but does not add new info beyond the schema descriptions (default 25, max 50 are already in 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 'Generate a production-ready llms.txt file for any URL', specifying the verb and resource. It distinguishes from sibling tools, none of which are related to HTML or markdown generation.

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?

Description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It doesn't mention when not to use or alternatives, 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?

The description adds significant behavioral context beyond the annotations: states it's free, doesn't count against quota, rate-limited to 5 per identifier per day, and that the team reads digests daily. No contradictions with the annotations.

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

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

The description is concise, with no redundant sentences. It front-loads the purpose and then provides usage guidelines. Could be slightly more compact but overall efficient.

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

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

Given the tool's simplicity and no output schema, the description covers all essential aspects: purpose, usage, constraints (rate limit, quota), and parameter semantics. It is complete for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining each enum value for 'type' and providing guidance on message content (be specific, 1-2 sentences, 2000 chars max) and context structure. This goes beyond the schema definitions.

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: giving feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs like 'tell' and lists the types of feedback, effectively distinguishing it from sibling tools which are about data retrieval or analysis.

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 tool explicitly describes when to use it (for bug reports, feature requests, data gaps, praise) and provides guidance on what not to do (don't paste end-user prompts). It also mentions rate limits and that it doesn't count against the tool-call quota, giving clear usage parameters.

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 safe, idempotent read. Description adds data source (CF analytics-engine), privacy (no PII), and caching (5min-1h), providing transparency beyond annotations.

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

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

Two sentences plus bulleted list. Front-loaded with purpose, every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and no output schema, description fully covers purpose, use cases, data source, privacy, and caching. 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 100% of parameters with enum and description. Description adds semantic guidance on window choice (hot vs. steady-state), providing extra value.

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

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

Clearly states it returns top tools, packs, and call volume over a window. Differentiates from 23 sibling tools by focusing on trending rather than specific queries or entities.

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 three use cases for when to use the tool, but does not mention when not to use it or suggest alternatives for other tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral detail: the mechanics of monotonicity and partition checks, the semantic anchor (Jaccard similarity >= 0.30), and the partition filter (placeholder slugs). It also explains error conditions (no args fail, skipped_low_similarity). No contradictions with annotations.

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

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

The description is approximately 250 words, which is somewhat long but justified by the tool's complexity. It is front-loaded with the critical constraint and structured into sections (event mode, topic mode, semantic anchor, partition filter, response). While every sentence adds value, minor tightening could improve readability without losing 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 exists, so the description fully explains the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}'. It also covers error handling and filtering details. Given the tool's two modes and multiple validation steps, the description provides complete context for use.

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

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

Schema coverage is 100% with descriptions for both parameters. The free-text description goes well beyond the schema by explaining the context of each mode, providing example slugs/questions, and detailing the internal logic (e.g., Jaccard similarity threshold, partition filter). This adds significant meaning that helps the agent choose and format parameters correctly.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two distinct modes (event and topic) with concrete examples, making the purpose highly specific and actionable. While it does not explicitly distinguish from siblings like 'polymarket_edges', the description is self-contained and unambiguous.

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

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

The description opens with a strong usage requirement: 'REQUIRES one of event (single-event mode) OR topic (cross-event mode) — call with no args fails.' It explains when to use each mode, with examples of cross-event catching patterns single-event misses. However, it does not provide guidance on when to use this tool vs. siblings like 'polymarket_edges' or 'polymarket_kalshi_spread', which would strengthen the guidelines.

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, open-world, idempotent, non-destructive behavior. The description adds extensive context beyond annotations, explaining three model families, edge calculation details (e.g., Fed bets surface excluded, Kelly fractions, slippage), and diagnostic information. It also notes caching behavior ('Cached 1h at the KV level'). 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 lengthy but well-structured with clear sections (segments, tradeable-edge knobs, response top-level). It front-loads the core purpose and uses bold/highlights for key terms. While every sentence adds value, it could be slightly more concise without losing essential detail.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is comprehensive. It thoroughly explains the output structure (by_segment, fed_candidates, _diagnostics), diagnostic fields, and edge calculation. Covers all necessary information for an agent to understand and invoke the tool correctly.

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

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

All 9 parameters have descriptions in the input schema (100% coverage). The description adds significant extra meaning beyond the schema, such as clarifying why 'min_kelly' does not filter partitions and providing examples for parameters like 'slippage_pp' and 'min_partition_leg_kelly'. It enhances the schema's basics.

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 top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan,' 'return') and resource ('Polymarket markets,' 'opportunities'), differentiating it from sibling tools like 'polymarket_arbitrage' and 'polymarket_kalshi_spread' by its focus on Pipeworx disagreement and opportunity 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?

The description explains when to use the tool ('Built for what should I bet on today'), provides context for excluding Fed bets due to unreliability, and details configurable knobs. However, it does not explicitly name alternatives when a different tool would be more appropriate, though the sibling context implies those exist.

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, idempotent, non-destructive. Description adds significant behavioral context: compatibility warnings, temporal alignment, skipped cross types, and safety 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?

Well-structured with clear sections. Front-loaded with core purpose. Dense but not overly verbose; every sentence adds value.

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

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

Covers all aspects: modes, response structure, safety fields, temporal alignment, and counters. Despite no output schema, response is fully 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 provides descriptions for all 3 parameters. Description adds semantic value by explaining mode interaction (topic vs explicit tickers, override behavior) and providing examples.

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

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

The description explicitly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue 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?

Describes two modes and warns that most pre-mapped topics return compatibility warning, guiding against over-reliance. Does not explicitly contrast with sibling tools 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 declare readOnly, idempotent, non-destructive. Description adds the cell limit constraint as behavioral context, but does not discuss response format or other behaviors. Some added value.

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

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

Two concise sentences, each serving a clear purpose: first states action, second provides critical constraint. 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?

Covers purpose and key usage constraint, but lacks description of return values or response structure. Given no output schema, this leaves some ambiguity. Adequate for a simple 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 already describes both parameters with format details. Description reiterates 'body is a PxWeb query object' and adds cell limit context, but does not significantly deepen understanding beyond schema.

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

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

Clearly states 'Pull data from a table' with specific PxWeb query object. Differentiates from sibling 'table_meta' but not from other data retrieval tools; however, the PxWeb specificity makes purpose clear.

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

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

Provides a critical usage hint about cell limits and narrowing dimensions, but no explicit when-to-use vs alternatives or when-not-to-use. Adequate but minimal guidance.

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

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

Annotations already indicate readOnlyHint: true, idempotentHint: true, destructiveHint: false. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, 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?

The description is three sentences, each earning its place: purpose, usage example, scope and pairing. No unnecessary words, front-loaded with the core action.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete: it covers what the tool does, when to use it, parameter behavior, scoping, and relationships with sibling tools.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning by explaining the behavior when 'key' is omitted (list all keys), which is also in the schema's description but reinforced here, and clarifies the retrieve vs. list dual functionality.

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 dual purpose: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses specific verbs (retrieve/list) and identifies the resource (saved memories), distinguishing it from sibling tools like 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?

The description provides clear context ('look up context the agent stored earlier') and examples (ticker, address, notes) but does not explicitly state when not to use the tool or name alternatives, though the sibling relationships are 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?

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint): it explains parallel fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO due to API sunset, and output structure (grouped by source, total_changes, citation URIs). It does not detail pagination or rate limits but is otherwise thorough. 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 efficiently structured: it opens with natural language queries, defines the core function, details each source and parameter, and closes with the alternative tool. Every sentence earns its place; no redundancy or filler.

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

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

Given moderate complexity (multiple sources, fallback logic, parameter formatting) and no output schema, the description covers inputs, behavior, and alternatives adequately. It describes the return structure (changes grouped, total_changes, citation URIs). Missing some edge cases (e.g., empty results, error handling) but is sufficient for agent 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?

With 100% schema description coverage, the baseline is 3. The description adds meaning by explaining the 'since' parameter accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), specifies that 'value' can be a ticker or zero-padded CIK, and clarifies 'type' only supports 'company' today. This adds value beyond the schema's brief field descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to multiple sources. It uses specific verbs and resources ('change feed', 'fans out to SEC EDGAR...') and explicitly distinguishes from the sibling tool entity_profile by contrasting dynamic vs static profiles.

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 opens with common user queries ('What's new with X', 'latest on Y') that signal when to use this tool, then ends with an explicit directive: 'Use entity_profile instead when you want the static profile...' This tells the agent when NOT to use it and identifies an alternative.

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

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

Annotations provide idempotentHint and not destructive, but description adds behavioral context: scoped by identifier, persistence duration (24 hours for anonymous, permanent for authenticated). Could mention overwrite behavior but not required.

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

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

Concise and well-structured: first sentence states core purpose, then usage context, then storage details, then retrieval/delete pairing. Every sentence adds unique 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?

Fully covers all necessary aspects for a simple 2-param tool: what it does, when to use, how long data persists, and how to interact with sibling tools. No gaps given the tool's complexity and annotations.

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

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

Schema has 100% coverage with clear descriptions. Description adds value by providing concrete examples of keys and values ('subject_property', 'target_ticker', 'user_preference'), enhancing semantic understanding beyond schema.

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

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

Description clearly states the tool's purpose: saving data for reuse across conversations/sessions. It uses specific verbs ('save', 'reuse') and resource ('data', 'key-value pair') and distinguishes from sibling tools '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?

Explicit guidance on when to use ('when you discover something worth carrying forward') and explicit mentions of alternatives: 'recall' for retrieval and 'forget' for deletion.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds that it cascades through several endpoints internally and auto-disambiguates for company names, providing useful behavioral context beyond annotations.

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

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

Well-structured with examples in quotes followed by type enumeration. Front-loaded with key purpose. Slightly wordy in the middle but overall efficient for the information provided.

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

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

No output schema exists, but the description fully explains return values for each type (ticker+CIK+name+URI for company, RxCUI+ingredient+brand+URI for drug). It also notes the tool replaces 2-3 manual lookups, providing a complete picture.

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 providing examples for each type (e.g., 'AAPL', '0000320193', 'ozempic') and noting auto-disambiguation. This enhances the schema's descriptions.

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

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

The description clearly states it resolves names to canonical IDs, listing specific use cases (ticker, CIK, RxCUI) and supported types (company, drug). It distinguishes itself by specifying it replaces multiple manual lookups, contrasting with sibling tools like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and gives clear examples. While it doesn't explicitly say when not to use or compare with siblings, the context is sufficient for an AI to decide.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds internal detail: it calls ai_visibility_check for each entity, returns a ranked list with score, confidence, signal density. No contradictions; adds useful behavioral context beyond static hints.

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

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

The description is extremely concise: two sentences. The first sentence provides a clear purpose and action summary. The second sentence adds usage context and output details. No filler or redundant information.

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

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

Given no output schema, the description covers the output structure adequately (ranked list with score, confidence, signal density). It explains the internal process (calling ai_visibility_check), the input parameters' roles, and the competitive analysis use case. Sufficient for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by specifying that the first entity in the array is treated as the subject for narrative, which is not in the schema. This is a useful semantic clarification.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and identifies most/least recognized. It explicitly mentions probing each entity with ai_visibility_check, which distinguishes it from the sibling tool ai_visibility_check that likely checks a single entity.

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 context: 'useful for competitive AI-marketing audits' and gives an example question. Implies when not to use by contrasting with single-entity check. Also notes that the first entity is treated as the subject, guiding correct invocation.

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

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

The description adds significant behavioral context beyond annotations: it explains the composite nature, graceful degradation, bundlephobia's initial 5-30s delay, and that sources_failed lists timeouts. Annotations already declare read-only, idempotent, and non-destructive, and the description aligns with these.

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

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

The description is a single paragraph that is front-loaded with the core purpose. Every sentence adds necessary information, though it is slightly long. It is well-structured with clear separation of features.

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 (composite tool, no output schema), the description is highly complete: it lists return fields, explains partial failures, mentions limitations (npm only v1, bundlephobia delay), and provides usage guidance. No output schema exists, but the description adequately covers what is returned.

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 noting that scoped packages are accepted and that version defaults to latest, which goes beyond the schema descriptions.

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

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

The description clearly identifies the tool as a composite check for adding an npm package, listing specific data sources (deps.dev, bundlephobia) and what it returns. It uses specific verbs and distinguishes itself from sibling tools like compare_entities.

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

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

The description explicitly states when to use the tool ('is X safe / popular / small' or 'what does adding lodash cost me') and notes that NPM ecosystem is the scope, with alternatives for other ecosystems. It lacks explicit when-not-to-use guidance but provides sufficient context.

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

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

Annotations declare readOnly, non-destructive, idempotent. The description adds details on item types and ID suffixes, which supplements the behavioral profile 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 concise sentences front-load the main verb and resource. Every word adds value, though the structure could be slightly improved with bullet points for clarity.

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

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

For a simple tool with one optional param and no output schema, the description covers core functionality. However, it omits error handling or behavior on invalid paths, leaving some 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 the path parameter at 100%. The description adds context by explaining the default behavior and providing examples, enhancing 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 navigates a subject tree and specifies the return for an empty path. It differentiates from sibling tools like table_meta by focusing on tree structure, though it could be more explicit about its unique role.

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 path examples but lacks explicit guidance on when to use this tool over alternatives like entity_profile or query_table. Usage context is implied but not directly 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and side effects. The description adds only the path constraint and purpose, but does not provide additional behavioral context such as error handling or data freshness. Thus, minimal added 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 extremely concise: one sentence defining purpose plus a single constraint. No extraneous words, efficiently front-loaded. Every element earns its place.

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

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

For a simple read-only metadata tool with one parameter and no output schema, the description covers the return type and input constraint. However, it could be more complete by hinting at the format of 'valid values' or potential return size. Still, it is largely sufficient given the tool's simplicity.

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

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

The input schema covers 100% of parameters with a descriptive example for 'path'. The description adds a validation rule ('must end in .px'), which provides extra clarity but does not fundamentally change understanding. 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 the tool retrieves table definition including dimensions and valid values, and specifies the path format requirement. It distinguishes itself from sibling tools like 'query_table' by focusing on metadata.

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

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

The description provides a specific usage guideline about the path ending in '.px', but it does not explicitly inform the agent when to use this tool versus alternatives like 'query_table'. The context implies it is for table metadata, but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so no contradiction exists. The description adds valuable behavioral context: it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → numeric comparison) and lists the return fields (verdict, extracted form, actual value, percent delta). This goes beyond the annotations by explaining efficiency and output structure.

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 (three sentences) and front-loaded with the key invocation patterns. Each sentence serves a distinct purpose: usage triggers, scope limitation, return details, and efficiency benefit. No wasted words, and the structure makes it easy to scan.

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 having only one parameter and no output schema, the description covers everything needed for an agent to invoke it correctly. It explains the domain (company-financial claims via SEC EDGAR + XBRL), the exact return values (verdict types, structured form, citation, percent delta), and the efficiency gain. This is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description's 'claim' parameter description adds concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion') that clarify the expected natural-language format. This additional detail helps the agent understand acceptable input variations beyond the schema's generic 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 specifies the tool's purpose: natural-language claim verification against authoritative sources. It lists trigger phrases like 'Is it true that…' and 'fact check,' and explicitly distinguishes from sibling tools by narrowing to company-financial claims (revenue, net income, cash position). This makes the purpose unambiguous and uniquely identifiable.

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 tells when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and gives concrete examples of input types. It does not explicitly state when not to use it, but it does imply a scope limitation (company-financial claims), which helps guide decision-making. A minor omission of direct alternatives keeps it from a 5.

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