Trade Intel

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations, such as the fact that it probes multiple LLMs, requires a BYO API key for Anthropic, and returns per-model results with score, confidence, signals, and raw_response. This provides context on costs and API usage.

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 three sentences that front-load the main action and output. Every sentence provides essential information with no redundancy. It lists the return structure compactly.

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 no output schema, the description adequately explains the return format (per-model {score, confidence, signals, raw_response} + combined view). The purpose, parameters, and usage context are fully covered, making the description complete for an agent to 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?

Schema description coverage is 100%, and the description adds further value by explaining default model behavior ('Default model is Workers AI Llama-3.3-70b (free)'), clarifying the API key usage ('Passed straight through to api.anthropic.com'), and describing the context parameter's disambiguation purpose. 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 knowledge about an entity and returns a visibility score. It specifies verb 'probe', resource 'LLMs', and output 'score (0-100) per model'. It distinguishes from siblings by mentioning specific use cases like AI-marketing audits, pre-launch brand checks, and competitive monitoring, which are not covered by other tools 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?

The description explicitly states when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains the model selection and API key requirements. However, it does not explicitly mention when not to use it or contrast with alternatives, though the use cases imply 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?

The description adds context beyond annotations by explaining that the tool routes to 3,745 tools across 884 sources and returns structured answers with citation URIs. It does not contradict annotations (all consistent: readOnly, openWorld, idempotent). However, it could mention potential wait times or lack of real-time data, but overall it adds meaningful transparency.

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 cohesive paragraph with a clear opening directive. It includes examples but could be slightly more concise. Still, it is well-structured and informative without unnecessary verbosity.

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

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

Given the lack of output schema, the description explains the return format (structured answer with URIs) adequately. It also provides context on the tool's internal routing and scope. It covers the necessary information for an agent to use the tool effectively, though it does not detail error handling or edge cases.

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 aliases well described. The description does not add any additional parameter semantics beyond what is in the schema. Baseline 3 is appropriate as the schema already documents the parameter effectively.

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 routes questions to a large set of verified sources and returns structured answers with citations. It clearly distinguishes itself from web search and provides a specific scope (SEC filings, FDA data, etc.), making its purpose 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 gives explicit guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data...' and lists example queries. It also states 'use whenever the user asks...' providing clear when-to-use instructions, though it does not explicitly mention when not to use it, which is a minor omission.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: same routing as ask_pipeworx, extra LLM call, return fields including refusal reasons. No contradiction with annotations; enhances transparency.

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?

Description is a single paragraph of 4 sentences, front-loaded with purpose. Every sentence provides distinct value: purpose, mechanism, use cases, return format, cost trade-off. No wasted words.

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

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

Given the complexity (high-stakes, refusal reasons, extra LLM call) and absence of output schema, the description covers return fields, failure modes, and behavioral traits. Sufficient for an agent to understand when and how 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% with aliases well described. Description does not add extra parameter semantics beyond stating 'Same routing as ask_pipeworx' implying question parameter is standard. Baseline 3 justified as schema does the heavy lifting.

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 hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx. It specifies the process: picks tool, fetches data, extracts answer only from results. This differentiates it from siblings and defines 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?

Explicitly states when to use: when answer will be quoted, cited, or acted on, and agent must not invent facts (e.g., financial, legal, medical). Also provides exclusion: prefer ask_pipeworx for casual lookups, noting the extra cost. Clear guidance on 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 goes far beyond the provided annotations (readOnlyHint, idempotentHint, destructiveHint) to disclose numerous behavioral traits: market resolution, classification, fan-out to data sources, response structure with edge calculation and warnings, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence and closed markets, wide-spread handling, and resolution-rule risk parsing. 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 very long and packed with information, but it lacks clear structural organization (e.g., sections). It front-loads purpose well but then covers many details in a dense, sometimes stream-of-consciousness style. While every sentence adds value, the overall length and lack of formatting reduce conciseness for an AI agent scanning quickly.

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

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

Given the tool's complexity (3 parameters, no output schema, many edge cases), the description is remarkably complete. It covers input handling, resolution confidence, market status checks (closed, wide spread, cancellation rules), response structure (market, analysis, evidence, news fields, parent event), and error/safety scenarios. All critical behavioral aspects are addressed.

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, but the description adds significant value: 'market' is explained with examples and acceptable formats (slug, URL, text); 'depth' enum values are explained ('quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.'); 'include_raw' is given context about response size and when to use. This greatly enhances parameter 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?

The description starts with a clear action verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It goes on to list specific inputs (slug, URL, question text) and outputs (evidence packet + comparison), which clearly distinguishes this from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage'.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes conditions that short-circuit (low-confidence, closed markets, wide spreads). However, it does not explicitly mention when NOT to use it or point to alternative tools, though context from siblings makes it clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant context: specific data sources (SEC EDGAR/XBRL for company, FAERS for drug), handling of off-calendar fiscal years, and sorted primary metrics. 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 dense paragraph but every sentence adds value. It could be slightly more front-loaded with a concise summary, but overall it is appropriately sized with no wasted words.

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

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

With no output schema, the description mentions 'paired data + pipeworx:// citation URIs per entity', which gives return format insight. It also notes efficiency ('Replaces 8–15 sequential lookups'). Slightly more detail on result limits or pagination would bring it to a 5, but it's already quite 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?

Despite 100% schema coverage, the description enriches parameter understanding by clarifying what data each entity type returns (e.g., 'company' pulls revenue, net income, cash, long-term debt) and providing example values (tickers vs. drug names).

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

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

The description uses specific verbs like 'compare', 'rank', and 'head to head', and clearly identifies the resource (entities) and action (side-by-side comparison). It distinguishes itself from sibling tools like 'entity_profile' which likely handle single 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 instructs to 'ALWAYS PREFER' over sequential single-pack lookups when comparing entities. Also lists example user queries that map directly to this tool, providing clear when-to-use guidance and implicitly advising against alternatives.

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

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

Annotations already indicate readOnly, idempotent, and openWorld. The description adds substantial behavioral context: parallel decomposition, evidence with citations, confidence estimates, handling of unanswered facets (gaps[]), time range, account requirements, and that results are never invented. 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?

Despite its length, every sentence serves a purpose: core functionality, use cases, alternatives, prerequisites, output format, and caveats. It is front-loaded with the primary action and well-organized. No redundant or filler content.

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

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

Given the tool has no output schema, the description compensates by detailing the return format (structured findings packet with evidence, confidence, source, fetched_at, citations, and gaps). It also covers input, process, time expectations, and account constraints. Complete for an agent to understand invocation and result handling.

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%, yet the description enriches both parameters: explains depth numeric mappings (quick=3, standard=5, thorough=8) and the paid plan requirement for thorough, and clarifies that question is natural language and broad/multi-part is fine. This adds 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 starts with a specific verb ('Decomposes', 'routes', 'extracts') and resource ('multi-source research'), and clearly distinguishes from sibling ask_pipeworx by contrasting its single-lookup nature. It fully captures the tool's unique value proposition.

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 ('broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'), along with prerequisites (account, paid plan for certain depth). This provides clear decision criteria for an AI agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool 'returns the top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly,' providing useful behavioral context beyond the annotations.

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

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

The description is two concise sentences that front-load the purpose with 'Find tools by describing the data or task.' Every sentence adds value—examples, usage guidance, and return format—without 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 discovery tool with no output schema, the description adequately explains that it returns tool definitions (names, descriptions, schemas, examples) and that results are call-ready. It also covers safety via alignment with annotations. The tool's complexity is low, and the description is 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description mentions aliases for the query parameter but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task.' It uses a specific verb-resource combination and lists concrete examples like SEC filings, FDA drugs, etc. It distinguishes itself from sibling tools by being a meta-discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it. It doesn't explicitly state when not to use, but the guidance is strong enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds significant behavioral context: cross-source fan-out, specific data fields returned, USPTO sunset May 2025 with soft-fail behavior, news fallback, and parameter constraints. 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 quite verbose with multiple examples and nested details. While front-loaded with examples, it could be more concise by removing some redundant phrasing. Every sentence adds value, but overall length reduces scanability.

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 lists return fields (CIK, filings, fundamentals, patents, news, LEI). It lacks pagination or total count info, but for a profile tool this is sufficient. Parameter constraints are fully covered.

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 description adds meaning beyond schema by explaining the type constraint ('only company supported'), value format (ticker or zero-padded CIK), and the limitation that names are not supported. Provides usage 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 clearly states it returns a full cross-source profile of a US public company, listing specific data points and sources. It is a specific verb-resource combination (get profile for entity). However, it does not explicitly differentiate from siblings like compare_entities or resolve_entity, though the usage guidelines provide alternatives.

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 (holistic view) and when not to (if only have a name, use resolve_entity first). Provides clear alternatives and context for preference over chaining individual 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds 'Delete', which matches the destructive nature, but does not provide additional behavioral context beyond what annotations convey.

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, each serving a purpose: purpose, usage conditions, and relation to siblings. No wasted words. Front-loaded with actionable 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?

For a simple one-parameter tool with full annotation coverage and no output schema, the description is complete. It covers purpose, usage, and relationships with siblings.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description uses 'by key' but adds no extra 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 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools by explicitly mentioning 'Pair with 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?

The description gives clear usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the internal process (fetches page, extracts title/description/key links) and the output format, beyond what annotations provide.

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 efficient sentences: first defines core function, second explains process, third lists use cases. No unnecessary words, front-loaded with key 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?

For a tool with 2 parameters and no output schema, the description covers purpose, process, and output format. It could mention error handling or rate limits, but is adequate for typical 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 description adds default and max for max_links ('default 25, max 50'), which is not in the schema. This extra context improves usability.

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

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

The description clearly states the action ('generate a production-ready llms.txt file'), the target resource ('any URL'), and the output format. It distinguishes itself from siblings by focusing on a niche technical task (llms.txt generation) not covered by the diverse sibling set.

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 lists three concrete use cases (client indexing, drafting, competitor auditing) but does not explicitly state when not to use it or compare directly to siblings. However, the sibling list is broad and unrelated, so the use cases are sufficient for 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 safe read-only behavior. Description adds return fields and clarifies it lists only the caller's subscriptions, providing useful context beyond annotations.

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

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

Two sentences, front-loaded with main action, no filler 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?

Adequate for a simple read-only tool. Describes what it returns and usage context. Lacks mention of empty result behavior, but minor.

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 description does not need to add param details. Description's mention of 'active' vs 'inactive' aligns with the schema parameter but adds no new semantics.

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 'List the caller's active subscriptions', specifying the verb and resource. It distinguishes from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Suggests when to use, though does not explicitly state when not to use.

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

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

Annotations are neutral (not read-only, not idempotent). Description adds value by stating rate limits and that it doesn't consume tool-call quota. While it doesn't detail side effects, the feedback nature implies no destructive actions, so transparency is good.

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?

Five sentences that are front-loaded with purpose, followed by usage guidelines and constraints. No fluff; every sentence serves a clear 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?

Covers input semantics and team reading behavior. Lacks output specification, but for a feedback tool, success acknowledgment is implicit. Completeness is high given 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 covers all parameters with clear descriptions (100% coverage). Description reinforces the enum meanings and context structure but adds little beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool's purpose: sending feedback to the Pipeworx team. It specifies types of feedback (bug, feature/data_gap, praise) and distinguishes from siblings by focusing on internal feedback rather than querying or retrieving data.

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 each feedback type and what to avoid (e.g., 'don't paste the end-user's prompt'). Provides context on rate limits (5 per day) and that it's free and doesn't count against quota, guiding appropriate use.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Description adds derivation source (CF analytics-engine), no PII, and caching details, adding 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?

Three concise sentences, front-loaded with output, no wasted words. Highly 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?

Describes output components (tools, packs, volume) and data structure (pack, tool, count). No output schema; could clarify exact format but sufficient 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?

Parameter window is fully described in schema with default, enum, and behavioral hints. Description adds no further semantic detail beyond that.

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. Distinguishes from 27 sibling tools which focus on queries, profiles, trades, 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 lists three use cases (discovery, confirmation, alignment) and explains window choice. Lacks when-not-to-use guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by detailed behavioral disclosures: requirements, semantic anchor (Jaccard similarity), partition filter, fill check with live CLOB depth, and conditions to avoid trading. 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 long (over 500 words) and dense with information. While well-structured with clear sections (REQUIRES, SEMANTIC ANCHOR, etc.), it sacrifices conciseness for completeness, which may overwhelm quick scanning.

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

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

Despite lacking an output schema, the description details the response structure: opportunities array, partition_check object, and fill check results. Covers all aspects of tool behavior, making it fully self-contained for the agent.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant meaning: event slug format and URL acceptance, topic as seed question, and behavioral differences between modes. Provides concrete 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event vs. topic) and differentiates from siblings like polymarket_fill_risk by mentioning custom sizing usage.

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

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

Explicitly advises when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Provides examples and explains what each mode catches. However, it does not explicitly state when not to use the tool, though the context implies 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: three model families, filtering logic, caching, diagnostics on empty segments, and Fed bet handling. 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 very long and detailed, with dense technical information. While well-structured and front-loaded, it could be more concise. Every sentence adds value, but length reduces readability.

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 complex tool with 9 parameters and no output schema, the description is highly complete. It explains the response structure (by_segment, diagnostics, fed info), caching, and tradeable-edge knobs. No significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for parameters like slippage_pp and min_partition_leg_kelly, explaining trade-offs and edge cases. It adds 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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on data-model disagreement.

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

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

The description provides clear context for when to use ('what should I bet on today') and explains the three segments. However, it does not explicitly state when not to use the tool or directly compare to 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?

Annotations indicate read-only, idempotent, open-world. The description adds valuable context: response includes tracked[], expired[], snapshot_dates[]; decay computed from daily closes (not intraday); history depth bounded by 60-day TTL. 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 detailed yet well-structured: purpose first, then response fields, then limitations. Every sentence adds value, though it could be slightly more 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?

Despite no output schema, the description thoroughly explains the response structure (tracked with time-series, expired with lifespan, snapshot dates) and limitations. It is complete for a telemetry tool.

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

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

Schema covers both parameters (100% coverage). Description adds defaults (14 for days, '1wk' for window), clamp range (2-30), and explains 'snapshot family' concept, enriching the schema meaning.

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 provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?' The verb 'track' and resource 'edge persistence and decay' are clear, and it distinguishes itself from sibling like 'polymarket_edges' by focusing on time-series decay.

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 (to understand edge persistence and decay) and includes limitations (60-day TTL, snapshotting start). It implies when not to use (if raw edges are needed, use polymarket_edges), but does not explicitly state alternatives or contraindications.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so description adds value by explaining live order-book checking, ladder walking, and verdict output (clean/degraded/cannot_fill). It also warns about partial fill risks, which is beyond what annotations cover.

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

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

The description is somewhat lengthy (multiple sentences) but well-structured: modes separated, warnings highlighted. Every sentence adds value, so it earns its length.

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 many return fields (top_of_book, vwap_fill_price, etc.) and caveats (thin legs, directional risk). It provides sufficient context for correct invocation and interpretation.

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% (baseline 3). Description adds meaning: side default with auto-detection for baskets, size_usd explained differently for single-market and basket modes. This contextualizes parameters beyond raw schema.

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

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

The description clearly states the tool's purpose: a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, lists specific return fields, and contrasts with sibling tools like polymarket_arbitrage.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (partial baskets convert arb to directional position) and when not to rely on theoretical overround on thin books.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enriches this by detailing the two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and the fact that the tool may return warnings rather than spreads. No contradiction exists.

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

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

The description is front-loaded with the core purpose, but it is somewhat verbose, packing many details into a single paragraph. While all sentences contribute value, breaking into sections 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?

Despite lacking an output schema, the description thoroughly explains the response structure (leg prices, top_spreads_pp, safety fields) and covers edge cases (leg mismatch, temporal misalignment, skipped comparisons). It is fully adequate for an AI to understand the tool's behavior and output.

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 three parameters, providing standard descriptions. The tool description adds significant meaning by explaining the two-mode interaction (topic vs explicit tickers), the list of topic shortcuts, and how explicit parameters override topic-mapped sides. This exceeds baseline expectations.

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

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

The description clearly defines the tool as cross-venue spread analysis between Kalshi and Polymarket, specifies two distinct modes (topic shortcuts vs explicit tickers), and explains when the comparison is valid. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue rather than intra-venue 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 provides explicit guidance on when to use the tool (e.g., to find real cross-venue spreads) and when not to (e.g., when compatibility_warning fires). It notes that pre-mapped topics often produce warnings. However, it does not explicitly direct users to alternative tools for single-venue analysis or other tasks, leaving some ambiguity.

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, idempotentHint, and destructiveHint. The description adds behavioral context: listing behavior when key is omitted, scoping to identifier, and pairing with other tools. No contradictions.

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

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

Three sentences, front-loaded with action, then usage guidance. Every sentence is necessary and no words are wasted.

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

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

The description covers both use cases (retrieve by key, list all), scoping, and relationships to remember and forget. It is complete given the simple schema and 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 coverage is 100%, and the description adds meaning beyond the schema: 'omit the key argument' to list all keys. This clarifies the parameter behavior.

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 specifies the verb (retrieve/list) and resource (saved values/keys) clearly. It also distinguishes from siblings (remember and forget are named).

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 ('look up context the agent stored earlier... without re-deriving it') and mentions scoping and pairing with remember/forget. It does not explicitly state when not to use it, 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?

The description adds context beyond annotations: it explains that mark_read=true flags events as read, mentions the external API mirror, and describes return fields. All consistent with readOnlyHint and idempotentHint. 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?

Five sentences, each purposeful. Front-loaded with main action, then return fields, filters, mark_read behavior, and external access. No wasted words. Efficiently sized.

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

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

No output schema, but description explains return fields sufficiently. Covers filtering, state mutation via mark_read, and external API. Missing error scenarios but acceptable for a read tool.

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

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

With 100% schema coverage, the description adds meaning for some parameters (e.g., 'set mark_read:true to flag returned events read so the next call only shows newer ones'). It doesn't cover limit or unread_only, but schema does. Overall adds 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 'Pull' and the resource 'fired events from your subscription feed'. It specifies the return contents (source, citation_uri, raw payload) and distinguishes from sibling tools like list_subscriptions by focusing on alerts rather than subscription management.

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 ('Pull fired events from your subscription feed') and provides an alternative access method (GET endpoint for scripts/dashboards). It does not explicitly list when not to use it or compare to sibling tools, but the context is clear.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the tool is safe. The description adds detailed behavioral context: fans out to multiple sources, fallback from GDELT to GNews, PatentsView API sunset, and output structure. 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 dense and front-loaded with example queries. While lengthy, each sentence contributes useful information. Could be slightly more concise, but overall well-structured.

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

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

Given the complexity (multiple sources, fallback logic, no output schema), the description covers inputs, process, and expected outputs (changes array, total_changes, URIs). It misses pagination details but is fairly complete for an agent.

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

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

Schema description coverage is 100%, but the description adds value by explaining accepted formats for 'since' (ISO date or relative shorthand with examples) and recommending typical values. It also clarifies that 'value' can be ticker or CIK.

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 provides a change feed for a company covering SEC filings, news, and patents. It distinguishes from the sibling tool 'entity_profile' by specifying when to use the static profile instead.

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

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

The description gives explicit examples of when to use (e.g., 'What's new with X', 'latest on Y') and provides a clear alternative: 'Use entity_profile instead when you want the static profile...' It also suggests typical values for the 'since' parameter.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. Description adds context beyond annotations: storage scoped by agent identifier, persistent for authenticated users, 24-hour TTL for anonymous sessions. This clarifies lifecycle and scope. However, it does not mention the effect of repeated writes (overwrite behavior) which would align with idempotent hint, so minor gap.

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 purpose. Each sentence adds distinct value: purpose, when-to-use with examples, pairing with siblings, and behavioral nuances (scoping, persistence). No redundant or irrelevant information. Highly 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 (2 params, no output schema, annotations present), the description is fully adequate. It covers purpose, usage, parameter guidance, behavioral details, and inter-tool relationships. No output schema needed; return value likely implicit success. All necessary information for correct agent invocation 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 already describes both key and value parameters clearly (key as string with example patterns, value as text). Description adds value by providing example key patterns ('subject_property', 'target_ticker', 'user_preference') and specifying that value can hold any text (findings, addresses, etc.), reinforcing the flexible nature of storage.

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 saves data for later reuse, specifies it's a key-value store scoped by identifier, and distinguishes from siblings recall and forget by mentioning pairing. It uses a specific verb ('Save') and resource ('data'), and the context of cross-session persistence sets it apart from other tools.

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

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

Explicitly states when to use: when discovering something worth carrying forward (resolved ticker, address, preference, research subject). Mentions alternatives: pair with recall to retrieve and forget to delete. Provides clear context for use vs. non-use.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds that it cascades through multiple endpoints internally and auto-disambiguates company names, enriching behavioral insight 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?

Dense single paragraph front-loaded with purpose. Lists supported types with return details. Efficient but could be slightly more structured (e.g., bullet points) for readability.

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

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

Despite no output schema, description explains return format for each type (ticker+CIK+uri, RxCUI+ingredient+brand+uri). Covers internal cascading and disambiguation. Complete for a lookup tool.

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

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

Schema coverage 100%, but description adds concrete examples (e.g., 'ticker (AAPL)', CIK, drug names) and explains what identifiers are returned for each type, increasing param understanding.

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

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

Description clearly states the tool resolves spoken names to canonical identifiers, with explicit examples ('What's the ticker for...'). It distinguishes from siblings by positioning itself as the first step before other tools need IDs.

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

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

Explicit guidance to 'Use FIRST whenever you have a name but need an ID.' Supported types and input formats are detailed. Lacks explicit when-not-to-use, but context from sibling tools implies disuse when ID is already known.

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, openWorld, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check for each entity, ranks by score, and returns a structured result (score, confidence, signal density). No contradictions. Does not mention potential rate limits or dependency on ai_visibility_check availability.

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

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

Three well-structured sentences with no waste. Front-loaded with the core purpose, followed by how it works and a concrete example use case. 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 (batch operation, internal tool call, ranked output), the description fully covers inputs (entities, models, apiKey, context) and outputs (ranked list with score, confidence, signal density). No output schema exists, so the description appropriately fills the gap. Differentiates from siblings effectively.

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

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

Schema has 100% description coverage. Description adds meaning beyond schema: clarifies that the first entity in the array is the 'subject' for narrative, and the rest are competitors. Also implies default model is workers-ai. This enhances understanding without redundancy.

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

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

Clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. Distinguishes from sibling tools like ai_visibility_check (single entity probe) and compare_entities (generic comparison) by specifying the batch ranking behavior.

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 describes use case for competitive AI-marketing audits and hints at multi-entity comparison. Implies single-entity use should leverage ai_visibility_check, but does not explicitly state when not to use or name alternatives. Clear context but lacks explicit exclusions.

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

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

The description adds significant behavioral context beyond the annotations: it fans out to two services, returns a detailed summary with fields like is_latest, license, bundle size, etc., mentions graceful degradation with sources_failed, and warns of a 5-30s delay for bundlephobia's first measurement. 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 well-structured and front-loaded with the composite nature. Every sentence adds value, though it is slightly longer than necessary. Still, it remains clear and focused.

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 (fan-out, multiple return fields, partial failures) and absence of an output schema, the description provides a fairly complete picture. It explains return values, error handling, and scope limitations, though some edge cases (e.g., exact behavior when version not found) are not detailed, which is acceptable.

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

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

Schema description coverage is 100% for both parameters. The description adds meaning beyond schema by clarifying that package accepts scoped packages (e.g., @types/node) and that version defaults to the latest published version when omitted, enhancing usability.

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 composite check for npm packages, fanning out across deps.dev and bundlephobia to assess safety, popularity, and size. It uses specific verbs like 'check' and 'fan out,' and distinguishes from siblings like 'scan_competitor_ai_presence' which targets a different domain.

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

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

The description explicitly specifies when to use the tool: whenever an agent asks about npm package safety/popularity/size or cost of adding a package like lodash. It also provides when-not guidance by noting that other ecosystems (PyPI, Maven, etc.) should fall under deps.dev:version directly, making alternatives 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, openWorldHint, idempotentHint, and destructiveHint. The description adds specific behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. 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 efficient and front-loaded: first sentence states core purpose, followed by use case, companion tool, and technical details. 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 no output schema, the description sufficiently explains what is returned (passages with offsets and scores) and covers technical constraints (embedding model, window size, char limit, truncation flag).

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%, with each parameter already described (text, query, limit). The description does not add new semantic meaning beyond the schema, though it provides example queries in the description. Baseline of 3 is appropriate.

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

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

The description explicitly states it performs semantic search inside a fetched record, specifying inputs (text and query) and outputs (top-N passages with offsets and scores). It distinguishes from siblings by explaining when to use it ('too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded.

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

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

The description gives clear usage context: 'Use when the record is too big to cram into the prompt' and explains it saves context. It explicitly pairs with ask_pipeworx_grounded, providing an alternative workflow.

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 behavioral context beyond annotations, including account requirements, delivery channel constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and signing details. Annotations indicate idempotentHint=true but description doesn't elaborate on idempotency behavior, though it's consistent.

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

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

The description is a single dense paragraph packed with information but could be better organized with bullet points or sections. While it front-loads the main purpose, the dense formatting reduces readability.

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

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

The description covers purpose, auth requirements, types, param examples, delivery channels with constraints, and return value. It lacks discussion of error handling or behavior on duplicate subscriptions, but overall sufficient for the tool's complexity given 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 coverage is 100%, and the description adds substantial meaning with explicit examples for each type (e.g., sec_8k with item codes, polymarket_edge with topic, fred_series with series_id) and detailed delivery options with validation rules and signing mechanism.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists specific subscription types (sec_8k, polymarket_edge, fred_series) and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 subscribe to alerts for specific event types) and includes prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It does not explicitly say when not to use it, but context from sibling tools and examples provides adequate 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, idempotentHint, and no destructive action. The description adds value by explaining that the tool draws from a 'live catalog of thousands of tools' and returns specific categories. It also clarifies that calling with no arguments gives a full spread, which aids in understanding the tool's behavior. 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 front-loaded with common queries and key purpose, then details the output and parameter use. It is slightly lengthy due to listing categories, but each sentence serves a purpose. The structure is logical and efficient for an agent reader.

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 fully covers what the agent needs: purpose, usage scenario, parameter guidance, and output structure (category-bucketed example questions with tool+argument shape). The context signals confirm no hidden complexity, and the description is complete.

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

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

Schema coverage is 100% with one optional parameter. The description adds context by explaining the topic parameter can focus on specific areas (e.g., finance, pharma) and that omitting it gives a cross-category spread. This provides meaning beyond the schema's description.

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

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

The description clearly states it is an onboarding entry point returning category-bucketed example questions. It uses specific verb phrases like 'returns category-bucketed example questions' and distinguishes itself from siblings by referencing meta-tools such as ask_pipeworx. The purpose is unambiguous and immediately actionable.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides examples of when to call it. It also explains the optional topic parameter for focusing. While it doesn't explicitly list when not to use it, the guidance is clear and sufficient for an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds context about what data is returned (imports, exports, top commodities, exchange rates) but does not disclose additional behavioral traits. This is adequate given 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 two sentences long: the first sentence states the purpose and returns, the second provides concrete examples. No unnecessary words; every sentence earns its place. It is well-structured and easy to parse.

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

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

Given that an output schema exists, the description does not need to detail return values. It covers the core purpose, gives example country codes, and notes parameter defaults. It is complete enough for a simple query tool, though it could mention that country codes are numeric (e.g., UN/ISO codes).

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 adds example country codes and mentions that year defaults to last year and _fredKey is optional for dollar index, which provides useful context beyond the schema. However, the schema already describes each parameter, so the added value is moderate.

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 'compares trade flows between two countries' and lists specific return data (imports, exports, top commodities, exchange rates). It uses a specific verb ('Compare') and resource ('trade flows'), and the bilateral focus implicitly distinguishes it from sibling tools like trade_country_profile (single country) and trade_macro_dashboard (macro view).

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 indicates when to use the tool (to compare trade flows between two countries) and provides example country codes for common use cases. However, it does not explicitly state when NOT to use it or mention alternative tools, but the context is clear enough given the sibling list.

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, destructiveHint=false, and the description adds no additional behavioral context such as data freshness or limitations.

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 that front-load the purpose and provide immediate key examples with no wasted words.

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

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

The description adequately covers input and output for a simple snapshot tool, especially since an output schema exists; however, it could mention that results are limited to top 10 items.

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 reinforces the use of country codes with examples, but adds minimal extra 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 tool returns a country's trade snapshot including top 10 import/export partners and top 10 commodities, which differentiates it from sibling tools like trade_bilateral_analysis or trade_macro_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 provides example country codes and implies usage for quick profiles, but does not explicitly state when to use or not use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description is consistent and adds that it checks US trade indicators, but does not introduce new behavioral traits beyond what annotations cover. It does not contradict 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 specific indicators. Every word is informative, with no redundancy or wasted space.

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, output schema exists), the description covers the main purpose and data types. However, it lacks context about data sources, update frequency, or the optional API key usage. Still, it is reasonably complete for a dashboard check 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% for the single parameter (_fredKey with description). The description does not mention the parameter or provide additional semantics beyond the schema. Baseline score of 3 is appropriate as schema already covers parameter meaning.

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 'Check' and specifies exact resources: 'US trade indicators' including specific categories like customs revenue, exchange rates, trade balance, etc. This differentiates from sibling tools like 'trade_bilateral_analysis' and 'trade_country_profile' which focus on bilateral or country-specific data.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or exclusion criteria. With many sibling tools in the same domain, the lack of usage context is a significant gap.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false. The description adds context that the row is deactivated (not deleted) and historical events remain available via recent_alerts, which is valuable behavioral insight beyond the annotations.

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

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

Two sentences, no wasted words. The first sentence states the action and requirement; the second adds important behavioral context. Highly 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?

The explanation of deactivation and historical availability is sufficient for a simple cancellation tool. However, it does not mention what the tool returns on success or failure, which would complete the 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% with a description for the 'id' parameter. The description does not add any additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action 'cancel a subscription by id' and identifies the resource as a subscription. It also specifies ownership enforcement, which distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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 usage by stating that you can only cancel your own subscriptions and that the row is deactivated, not deleted. However, it does not explicitly explain when to use this tool versus alternatives or provide any exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context: returns a verdict with structured form, actual value, and pipeworx:// citation, and specifies supported claim types via SEC EDGAR + XBRL. 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 examples, scope, return details, and efficiency note. It's front-loaded with trigger phrases. Slightly verbose but still efficient. Could be tightened slightly.

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 of natural-language claim verification, the description adequately covers purpose, supported claims, output format, and data sources. No output schema, but verdict types are described. Complete for effective 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% (parameter 'claim' described in schema). The description adds meaning by explaining the claim is natural-language with concrete examples like 'Microsoft made about $100B in profit last year', and describes how it's processed.

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 verifies natural-language claims against authoritative sources, with specific examples like "Apple's FY2024 revenue was $400 billion". It distinguishes itself by noting it replaces 4-6 sequential calls, and the title 'Validate Claim' aligns with the description.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes to company-financial claims. While it doesn't list explicit alternatives, the mention of replacing sequential calls implies a efficiency advantage over manual multi-step processes.

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