Fintech Intel

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: default model is free, Anthropic requires BYO API key, returns per-model structure including score, confidence, signals, raw_response, plus combined view. 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?

Single paragraph with three sentences. Front-loaded with core purpose and key details. No wasted words. Every sentence adds value.

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

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

Despite no output schema, the description explains return structure (per-model {score, confidence, signals, raw_response} + combined view). Covers parameters, use cases, cost implications (free default, BYO key for Anthropic). Sufficient for a probe tool with good annotations.

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

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

Schema coverage is 100%, so schema descriptions already explain all four parameters. The description adds minor context (e.g., default model, key passing, combined view) but does not significantly enhance meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It specifies the default model (Workers AI Llama-3.3-70b) and optional Anthropic probing. The verb 'probe' and resource 'LLMs for visibility of a brand/product/topic' are specific and distinguish it from siblings like scan_competitor_ai_presence.

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 explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly state when not to use or differentiate from the sibling scan_competitor_ai_presence. However, the context is clear enough for an agent to infer appropriate usage.

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

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

No annotations provided, but description clearly discloses the tool's behavior: it selects the best data source, fills arguments, and returns results. Mentions it uses 'best available data source', which implies dynamic selection. However, lacks details on limitations or failure modes.

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 at three sentences plus examples. Front-loaded with purpose and behavior. Examples add value but could be more tightly integrated.

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 only one parameter, no output schema, and no annotations, the description covers the tool's purpose, usage, and behavior well. It's sufficient for an agent to decide when to use 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 with schema coverage 100%. The description adds context that the question should be in plain English and can be requests or questions, which supplements the schema's 'Your question or request in natural language'.

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 accepts plain English questions and returns answers by selecting the appropriate tool automatically. Provides concrete examples, distinguishing it from siblings which are specific tools.

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

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

Explicitly says to describe needs in natural language without browsing tools or learning schemas. Implicitly contrasts with siblings by advising 'no need to browse tools'. Examples show typical 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 (readOnlyHint=true, openWorldHint=true, destructiveHint=false) are consistent. The description adds detailed behavioral context: it resolves the market, classifies the bet, fans out to relevant data packs, and returns a comparison. 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 relatively long but information-dense. It front-loads the core purpose, then adds necessary detail in a logical sequence. A minor trim could improve conciseness, but every sentence adds value.

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

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

No output schema exists, but the description summarizes the return format (evidence packet, comparison). For a complex tool, it provides adequate completeness. Some might want more structure details, but it's sufficient for an AI agent.

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

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

Schema description coverage is 100%. The description adds meaning beyond the schema by explaining the market parameter can be a slug, URL, or question text, and clarifies the depth parameter's values and default. This helps the agent select correct inputs.

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: researching a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools by being the core demo product that handles internal data 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?

Explicit use cases are provided: 'should I bet on X?', 'what does the data say?', 'is there edge?'. The description implies superiority over alternatives that require manual pack discovery, but no explicit when-not-to-use guidance is given.

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?

With no annotations provided, the description carries the full burden. It discloses that data comes from SEC EDGAR and FDA, and returns paired data plus URIs. However, it does not mention rate limits, authentication needs, or any side effects, leaving some behavioral gaps.

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 the core action. Every sentence adds value—purpose, type-specific details, efficiency claim. No 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 no output schema, the description adequately covers returned data fields per type and mentions resource URIs. It lacks error handling or edge cases, but for a comparison tool the critical information is present.

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

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

Schema description coverage is 100%. The description adds context by explaining value formats (tickers/CIKs for companies, drug names). But it largely mirrors the schema descriptions, not adding substantial new 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 verb 'Compare' and the resource '2–5 entities side by side in one call'. It distinguishes the tool from siblings like fintech_company_deep_dive or fintech_market_snapshot by focusing on comparison rather than single-entity 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 description implies use cases by contrasting with sequential calls (replaces 8–15 agent calls), but it does not explicitly state when not to use it or name alternatives. The context signals that this is for side-by-side comparison, leaving inference but not explicit 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool returns 'the most relevant tools with names and descriptions' and mentions default and max limit. However, it does not disclose any potential side effects, rate limits, or other behavioral traits such as whether it logs queries or requires 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 concise, consisting of three short sentences. The key action and usage guidance are front-loaded, and every sentence adds value without redundancy.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no nested objects) and the absence of annotations, the description is fairly complete. It explains the tool's purpose, usage context, and parameter behavior. However, it lacks information about return format or error handling, which could be important for an 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 input schema has 100% coverage, with descriptions for both parameters. The description adds context about the 'limit' parameter (default 20, max 50) and provides examples for 'query' (e.g., 'analyze housing market trends'). This adds value beyond the schema by clarifying usage patterns and constraints.

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: 'Search the Pipeworx tool catalog by describing what you need.' It uses a specific verb ('Search') and resource ('Pipeworx tool catalog'), and distinguishes it from siblings by noting that it returns 'names and descriptions' for tool discovery, unlike other tools that perform specific fintech analyses or memory functions.

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: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear usage context and a directive to prioritize it before other tools, which effectively differentiates it from sibling tools.

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

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

With no annotations provided, the description carries full burden for behavioral transparency. It discloses that the tool is composite (bundles many sources), returns citation URIs, and indicates performance characteristics (too slow for federal contracts). It does not mention auth needs or error handling, but for a read-only data retrieval tool, this is sufficient context.

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

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

The description is a single paragraph that efficiently conveys purpose, data types, and usage notes. It is front-loaded with the core action. While a bulleted list might improve scannability, the current structure is concise and every sentence adds value.

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

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

Given the tool's complexity (multiple data sources) and lack of output schema or annotations, the description provides a reasonably complete picture. It covers input format, data returned, and when to use alternatives. It does not explain error handling or rate limits, but for a single-call profile tool, the description is adequate.

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

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

The input schema already describes both parameters with 100% coverage. The description adds important context beyond the schema: it explains that the value parameter accepts ticker or CIK, notes that names are not supported, and directs users to resolve_entity for name resolution. It also clarifies the type parameter is limited to 'company' currently.

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

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

The description explicitly states the tool's purpose: fetching a full profile of an entity across all relevant Pipeworx packs in one call. It lists specific data types (SEC filings, XBRL, patents, news, LEI) and mentions returning pipeworx:// citation URIs. It clearly distinguishes from sibling tools by noting it replaces 10-15 sequential calls and directly contrasts with usa_recipient_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?

The description provides explicit guidance on when to use this tool vs alternatives. It states that for federal contracts, one should call usa_recipient_profile directly because it is too slow to bundle. Additionally, the input schema's description for the value parameter instructs users to use resolve_entity first if they only have a name, offering clear usage boundaries.

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?

No annotations are provided, so the description must convey behavior. It implies a read-only lookup and lists data categories, but does not disclose potential latency, API limits, or whether results are cached. The description is adequate but lacks details on what happens if the bank is not 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?

The description is concise (two sentences) and front-loaded with the tool's purpose, followed by supported data and input format. Every sentence adds value without redundancy.

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

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

Given the simple input schema (one string parameter) and no output schema, the description covers the core functionality well. It could be slightly improved by noting that the tool returns a report or summary, but it is sufficiently complete for an AI agent to understand its usage.

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

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

Schema coverage is 100% (one parameter described). The description adds context by specifying the parameter is a bank name and giving examples, which slightly exceeds the schema. However, no additional constraints (e.g., case sensitivity, partial name matching) are mentioned.

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 performs a bank health check, listing specific data sources (FDIC lookup, financials, complaints) and the required input (bank name). It distinguishes itself from siblings like 'fintech_company_deep_dive' and 'fintech_market_snapshot' by focusing on individual bank health.

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 this tool (for bank health assessment) and provides an example input format. However, it does not explicitly state when not to use it or mention alternative tools like 'fintech_company_deep_dive' for broader company analysis.

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?

With no annotations, the description carries the full burden. It mentions the data sources and that it requires a ticker, but does not disclose side effects (e.g., API call limits), rate limits, or whether results are cached. The description is factual but lacks depth on behavioral constraints.

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

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

The description is two sentences long and front-loaded with the main purpose. Every word adds value. It is concise and avoids 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 complexity (aggregating multiple data sources) and lack of output schema, the description is somewhat complete but omits details about the output format, pagination, or data freshness. It covers the inputs and scope adequately for a summary tool.

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

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

Schema description coverage is 100% so baseline is 3. The description does not add new parameter details beyond the schema, but it does imply that '_avKey' and '_fredKey' are optional and used for stock/macro data, which is already clear from the schema. No additional value added.

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 a 'complete company financial analysis' and lists the data sources (SEC filings, stock quote, etc.). It distinguishes itself from siblings like 'fintech_bank_health_check' and 'fintech_market_snapshot' by being comprehensive for a single company.

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 implies when to use it (for a full company analysis) and mentions providing a stock ticker, but does not explicitly state when not to use it or suggest alternatives for more specific needs (e.g., 'fintech_market_snapshot' for broader 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 are empty, so description must cover behavioral traits. It discloses the optional FRED key for macro rates, but does not state if complaints/industry data require authentication, rate limits, or what happens on error. 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 a single, well-structured sentence that front-loads the purpose and lists data sources concisely. No redundant words.

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

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

Given no output schema, the description could mention what the dashboard returns (e.g., text summary, JSON), but it names key indicators. For a dashboard tool with one optional param, this is reasonably 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%, so the description need not add much. It clarifies that _fredKey is optional and for macro rates, which matches the schema description. No additional meaning beyond schema, but baseline 3 is appropriate.

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

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

The description clearly states the tool aggregates CFPB, FDIC, and optionally FRED data, with specific metrics listed. It distinguishes itself from siblings like 'fintech_bank_health_check' and 'fintech_company_deep_dive' by focusing on a market-wide dashboard.

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 implies use for a broad market snapshot, contrasting with deeper dives on individual entities. It does not explicitly state when not to use or mention alternative tools, but the scope is clear from the listed data sources.

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?

With no annotations provided, the description bears full burden. It states the tool deletes data, implying destructiveness, but does not clarify if the action is reversible, requires confirmation, or has side effects. Adequate but could be more transparent.

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

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

The description is a single sentence of 6 words, with zero wasted text. It is front-loaded and 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 (1 param, no output schema, no nested objects) and lack of annotations, the description is adequate but minimal. It omits error behavior or return value information, which would be helpful.

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

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

The schema description coverage is 100%, meaning the schema already describes the 'key' parameter well. The description adds no extra meaning beyond the schema, but this is acceptable given high coverage. Baseline 3 is elevated because the single parameter is self-explanatory.

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 'Delete a stored memory by key' uses a specific verb ('Delete') and resource ('stored memory by key'), clearly distinguishing the tool from siblings like 'recall' and 'remember'. It lacks explicit differentiation but is 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?

No guidance is given on when to use this tool vs. alternatives like 'recall' or 'remember'. There is no mention of prerequisites, such as whether the key must exist, or what happens if the key is not found.

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 that it fetches the page, extracts content, and outputs a standard format file. No contradictions; the behavioral disclosure is adequate for a non-destructive read operation.

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

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

The description is two sentences plus a bulleted list of use cases in a single paragraph. It is front-loaded with the main action, no redundant words, and every sentence adds value.

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

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

For a tool with only two well-described parameters, full annotations, and no output schema, the description provides complete context: what it does, how it works, and what it produces. It is sufficient for an agent to understand invocation and expected outcome.

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

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

Both parameters are well-documented in the schema (100% coverage). The description adds a usage example for 'url' but does not significantly extend understanding beyond the schema's own 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 states the specific verb 'generate' with a clear resource 'llms.txt file for any URL' and details the process (fetches, extracts, emits). It distinguishes from sibling tools like ai_visibility_check by focusing on llms.txt 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?

The description explicitly lists three use cases: indexing client sites, drafting own projects, auditing competitors. It does not explicitly mention when not to use it, but the use cases are clear and the tool's purpose is narrow 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?

With no annotations, description discloses rate limiting, content restrictions, and that it is free. Could elaborate on whether feedback is reviewed or any privacy considerations, but sufficient for a feedback tool.

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

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

Three concise sentences: purpose, usage guidance, rate limit. No wasted words; front-loaded with 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?

For a simple feedback tool, the description covers purpose, usage, rate limit, and parameter hints. No output schema needed; completeness is high given the tool's scope.

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 and detailed descriptions. Tool description adds value by summarizing type enum, explaining context is optional, and giving typical message length and max chars.

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 sends feedback to Pipeworx team, enumerates use cases (bug, feature, data_gap, praise), and is distinct from all sibling tools which are about asking questions, comparing, discovering, etc.

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

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

Explicitly tells when to use (bug reports, feature requests, etc.), provides content guidelines (describe in terms of tools/data, no verbatim user prompts), and mentions rate limit (5 per day per identifier).

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context: it is derived from CF analytics-engine, contains no PII, and is cached for 5min-1h. This goes well beyond annotations and gives the agent a clear understanding of the tool's behavior.

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

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

The description is concise (about 6 sentences) and well-structured with bullet points for use cases. Every sentence provides useful information without redundancy. The core purpose is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: what it returns (top tools/packs/volume), data source, privacy, caching, and window options. It is complete for an agent to decide when and how to use it.

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 meaningful guidance: shorter windows for hot trends, longer windows for steady-state demand. This clarifies the enum options and their implications 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 returns top tools, packs, and call volume from other AI agents on Pipeworx over a recent window. It uses specific verbs and resources, and the scope is well-defined, distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description enumerates three concrete use cases (discovering hot data sources, confirming canonical choice, seeing user alignment). It also notes caching behavior. However, it does not explicitly state when not to use the tool or compare directly with alternatives, which would make it perfect.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds context about the two modes and describes the return format (ranked opportunities with trade direction and reasoning), going beyond annotations 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 meaty but concise, with no wasted words. It front-loads the purpose and clearly structures the two modes. Every sentence 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?

Despite no output schema, the description compensates by describing the outputs. Both input parameters are fully covered with extra context. The description is 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?

Both parameters have schema descriptions, but the tool description adds context on how each is used (event slug vs. topic) and provides example values, significantly adding value 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 finds arbitrage opportunities by checking monotonicity violations. It distinguishes two modes (event and topic) and explains the rationale for cross-event mode, making it specific and distinct from siblings.

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 each mode (single event vs. topic/cross-event), includes examples, and explains a scenario where single-event mode misses opportunities, providing excellent guidance.

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

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

The description fully discloses behavior: it scans top markets, groups by asset, fetches price history once, computes model probability per market, ranks by |edge|, and returns top N with suggested direction. This aligns with readOnlyHint and destructiveHint annotations. 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 well-structured with logical flow: purpose, method, and intended use. It is slightly verbose but every sentence adds value. Could be tightened without losing clarity.

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

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

Given the tool's complexity, no output schema, and high schema coverage, the description provides complete context: what it does, how it works, what it returns (top N ranked by edge with trade direction), and its target use case. No gaps identified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions default values and context for parameters (e.g., volume window, minimum edge) but does not add significant new information beyond what the schema already provides. It adds context about the model but not parameter-specific details.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those with largest disagreement between Pipeworx data and market price. It specifies domain (crypto-price bets), model, and usage. While it doesn't explicitly differentiate from siblings like polymarket_arbitrage, the purpose is very specific and distinct.

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

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

The description explicitly frames the tool for the 'what should I bet on today' question, indicating it helps discover opportunities without manual browsing. However, it does not mention when not to use it or provide alternatives among siblings, which would strengthen 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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds value by detailing the two modes, behavior (fetches prices, computes spread), and return structure, consistent 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-organized into sections with clear explanation of modes and returns. While every sentence adds value, it could be slightly more concise by removing redundant phrasing, 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 details the return format (leg-by-leg prices in 0-1, spread in percentage points) and covers all behavioral aspects. For a tool with two modes and cross-venue complexity, it is complete and informative.

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 each parameter. The description further clarifies the relationship between parameters (e.g., topic is overridden by explicit ticker/slug) and explains the two modes, 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage or compare_entities. It specifies two modes (topic shortcuts and explicit pairings) and the output format.

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 topic mode vs explicit mode, and notes that the spread is an arbitrage signal. However, it does not explicitly exclude alternatives or mention when not to use this tool, though this is clear enough from context.

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

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

Without annotations, the description carries the burden. It clearly states the tool is non-destructive (retrieval only) and explains behavior when key is omitted. No contradictions with missing 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, no wasted words. Purpose and usage are front-loaded. Every sentence adds value.

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

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

Given the tool is simple (one optional parameter, no output schema), the description is complete enough. It explains what happens with and without the key, and mentions persistence across sessions.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds value by explaining the effect of omitting the parameter (list all), which is not in the schema description that only says 'omit to list all keys'.

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

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

The description clearly states the tool retrieves a memory by key or lists all memories if key is omitted, with a specific verb 'retrieve' and resource 'memory'. It distinguishes itself from sibling tools like 'remember' and 'forget' by focusing on 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 states when to use (retrieve context saved earlier) and provides guidance on omitting key to list all. It doesn't explicitly mention when not to use or alternatives, but the context is clear given the sibling tools.

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

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

No annotations provided, so description fully covers behavior: parallel fan-out to three sources, date format flexibility, return structure with counts and URIs. Lacks only minor details like default timeout or error handling.

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

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

Two sentences with no filler. Front-loaded with purpose, then expands details. Every sentence adds value.

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

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

For a 3-param tool without output schema, description fully explains inputs and output structure (structured changes, count, URIs). Matches 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 covers all parameters (100%), and description adds value with examples for 'since' (ISO/relative), 'value' (ticker/CIK), and 'type' (only company).

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 verb 'what's new' and resource 'entity since a point in time'. Specific fan-out details for type='company' differentiate it from sibling tools like entity_profile or 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?

Explicitly states use cases: 'brief me on what happened with X' or change-monitoring workflows. Provides clear context but does not explicitly list when not to use it.

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?

With no annotations, the description carries full burden. It discloses persistence behavior: authenticated users get persistent memory, anonymous sessions last 24 hours. This adds context beyond the schema, but could mention memory limits or overwrite behavior.

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

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

Two sentences: first states purpose and verb, second gives usage context and persistence details. No wasted words, front-loaded.

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

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

Given the simple tool (2 params, no output schema), the description is complete enough. It explains when to use and persistence behavior. It does not need to describe return values as there is no output schema.

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

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

Schema description coverage is 100%, so the schema fully describes both parameters. The description adds a usage context ('save intermediate findings...') but does not add meaning beyond the schema's parameter 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 stores a key-value pair in session memory, using specific verbs ('Store') and a concrete resource ('session memory'). It distinguishes from siblings like 'forget' and 'recall' by its 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 says when to use this tool: to save intermediate findings, user preferences, or context across tool calls. It implies alternatives (recall/forget) but does not explicitly exclude them or provide when-not-to-use guidance.

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

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

With no annotations, the description takes full responsibility. It discloses that the call is a single lookup, returns specific fields (ticker, CIK, company name, URIs), and notes the v1 limitation. This sufficiently covers expected behavior, though no mention of error handling or idempotency.

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

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

The description is a single well-formed sentence with additional clarifying points about version and efficiency. Every sentence adds value, and it is front-loaded with the core functionality.

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 only 2 parameters and no output schema, the description explains the return format (fields and URIs) and usage context. It could mention potential error responses for invalid input, but overall is adequate for a simple lookup tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value beyond the schema by providing concrete examples for 'value' (e.g., 'AAPL', '0000320193', 'Apple') and clarifying the current 'type' enum option via version note.

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 entities to canonical IDs across Pipeworx data sources, specifying the supported type (company) and providing examples like ticker, CIK, or name. It distinguishes from siblings by noting it replaces 2-3 lookup calls, making the purpose highly specific.

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 (to get canonical IDs for companies) and what inputs are accepted, but does not explicitly exclude other entity types or compare to sibling tools like ask_pipeworx that might also perform lookups.

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

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

Describes the probing process, ranking by score, and output (ranked list with score, confidence, signal density). Annotations already indicate read-only and non-destructive behavior; the description adds procedural detail.

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

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

Three well-structured sentences, front-loaded with purpose. Each sentence adds value: purpose, process, use case. Could be slightly more concise but is 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?

No output schema, but description explicitly lists output fields (score, confidence, signal density). Parameters fully described in schema. The description is complete for a non-mutation tool with good annotations.

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

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

Schema covers 100% of parameters with descriptions. The description adds semantic value by noting that the first entity is treated as the 'subject' for narrative purposes, and that context disambiguates common 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using 'ai_visibility_check' to probe each. It differentiates from sibling 'ai_visibility_check' by focusing on multi-entity comparison and ranking.

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 use case ('competitive AI-marketing audits') and an example question. Implicitly distinguishes from single-entity check by mentioning multiple entities, but does not explicitly state when not to use or list 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?

With no annotations, the description must fully disclose behavior. It details output and sources but does not mention rate limits, authentication, error handling for out-of-domain claims, or read-only nature explicitly. Adds moderate context beyond 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?

Two sentences, no fluff. First sentence states core purpose, second provides details and benefit. Front-loaded and 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 no output schema, description fully explains return fields (verdict types, citation). Domain and scope are clear. Completeness is high for a single-parameter tool.

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

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

Schema coverage is 100% with a clear description. The tool description adds value by specifying claim types (company-financial) and providing examples, going 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?

Clearly states it fact-checks natural-language claims against authoritative sources, specifies domain (company-financial for US public companies via SEC EDGAR & XBRL), and lists returned verdict types. Distinguishes from siblings like ask_pipeworx or entity_profile by being a specialized validator.

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 notes it replaces 4-6 sequential agent calls, implying a clear when-to-use scenario. Domain restriction (v1 supports company-financial claims) is stated but no explicit exclusions or alternative tool mentions.

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